Skip to content

Commit 7ba4efc

Browse files
GromNaNalcaeus
GromNaN
and
alcaeus
authored
Extract autoEncryption driver options in MongoDB\Driver\Manager::__construct() (#4754)
* Extract MongoDB autoEncryption options into a distinct table for readability * Add link to autoEncryption options --------- Co-authored-by: Andreas Braun <git@alcaeus.org>
1 parent 565bd8b commit 7ba4efc

File tree

1 file changed

+135
-137
lines changed

1 file changed

+135
-137
lines changed

‎reference/mongodb/mongodb/driver/manager/construct.xml

Lines changed: 135 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -636,7 +636,7 @@ mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][
636636
<entry>
637637
<para>
638638
Provides options to enable automatic client-side field level
639-
encryption.
639+
encryption. The list of options is described in the <link linkend="mongodb-driver-manager.construct-autoencryption">table below</link>.
640640
</para>
641641
<note>
642642
<para>
@@ -659,142 +659,6 @@ mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][
659659
<literal>bypassAutoEncryption</literal> is &true;.
660660
</para>
661661
</note>
662-
<para>
663-
The following options are supported:
664-
665-
<table>
666-
<title>Options for automatic encryption</title>
667-
<tgroup cols="3">
668-
<thead>
669-
<row>
670-
<entry>Option</entry>
671-
<entry>Type</entry>
672-
<entry>Description</entry>
673-
</row>
674-
</thead>
675-
<tbody>
676-
&mongodb.option.encryption.keyVaultClient;
677-
&mongodb.option.encryption.keyVaultNamespace;
678-
&mongodb.option.encryption.kmsProviders;
679-
&mongodb.option.encryption.tlsOptions;
680-
<row>
681-
<entry>schemaMap</entry>
682-
<entry><type class="union"><type>array</type><type>object</type></type></entry>
683-
<entry>
684-
<para>
685-
Map of collection namespaces to a local JSON schema. This is
686-
used to configure automatic encryption. See
687-
<link xlink:href="&url.mongodb.docs;reference/security-client-side-automatic-json-schema/">Automatic Encryption Rules</link>
688-
in the MongoDB manual for more information. It is an error to
689-
specify a collection in both <literal>schemaMap</literal> and
690-
<literal>encryptedFieldsMap</literal>.
691-
</para>
692-
<note>
693-
<simpara>
694-
Supplying a <literal>schemaMap</literal> provides more
695-
security than relying on JSON schemas obtained from the
696-
server. It protects against a malicious server advertising a
697-
false JSON schema, which could trick the client into sending
698-
unencrypted data that should be encrypted.
699-
</simpara>
700-
</note>
701-
<note>
702-
<simpara>
703-
Schemas supplied in the <literal>schemaMap</literal> only
704-
apply to configuring automatic encryption for client side
705-
encryption. Other validation rules in the JSON schema will
706-
not be enforced by the driver and will result in an error.
707-
</simpara>
708-
</note>
709-
</entry>
710-
</row>
711-
<row>
712-
<entry>bypassAutoEncryption</entry>
713-
<entry><type>bool</type></entry>
714-
<entry>
715-
If &true;, <literal>mongocryptd</literal> will not be spawned
716-
automatically. This is used to disable automatic encryption.
717-
Defaults to &false;.
718-
</entry>
719-
</row>
720-
<row>
721-
<entry>bypassQueryAnalysis</entry>
722-
<entry><type>bool</type></entry>
723-
<entry>
724-
<para>
725-
If &true;, automatic analysis of outgoing commands will be
726-
disabled and <literal>mongocryptd</literal> will not be
727-
spawned automatically. This enables the use case of explicit
728-
encryption for querying indexed fields without requiring the
729-
enterprise licensed <literal>crypt_shared</literal> library or
730-
<literal>mongocryptd</literal> process. Defaults to &false;.
731-
</para>
732-
</entry>
733-
</row>
734-
<row>
735-
<entry>encryptedFieldsMap</entry>
736-
<entry><type class="union"><type>array</type><type>object</type></type></entry>
737-
<entry>
738-
<para>
739-
Map of collection namespaces to an
740-
<literal>encryptedFields</literal> document. This is used to
741-
configure queryable encryption. See
742-
<link xlink:href="&url.mongodb.docs;core/queryable-encryption/fundamentals/encrypt-and-query/">Field Encryption and Queryability</link>
743-
in the MongoDB manual for more information. It is an error to
744-
specify a collection in both
745-
<literal>encryptedFieldsMap</literal> and
746-
<literal>schemaMap</literal>.
747-
</para>
748-
<note>
749-
<simpara>
750-
Supplying an <literal>encryptedFieldsMap</literal> provides
751-
more security than relying on an
752-
<literal>encryptedFields</literal> obtained from the server.
753-
It protects against a malicious server advertising a false
754-
<literal>encryptedFields</literal>.
755-
</simpara>
756-
</note>
757-
</entry>
758-
</row>
759-
<row>
760-
<entry>extraOptions</entry>
761-
<entry><type>array</type></entry>
762-
<entry>
763-
<para>
764-
The <literal>extraOptions</literal> relate to the
765-
<literal>mongocryptd</literal> process. The following options
766-
are supported:
767-
</para>
768-
<simplelist>
769-
<member><literal>mongocryptdURI</literal> (<type>string</type>): URI to connect to an existing <literal>mongocryptd</literal> process. Defaults to <literal>"mongodb://localhost:27020"</literal>.</member>
770-
<member><literal>mongocryptdBypassSpawn</literal> (<type>bool</type>): If &true;, prevent the driver from spawning <literal>mongocryptd</literal>. Defaults to &false;.</member>
771-
<member><literal>mongocryptdSpawnPath</literal> (<type>string</type>): Absolute path to search for <literal>mongocryptd</literal> binary. Defaults to empty string and consults system paths.</member>
772-
<member><literal>mongocryptdSpawnArgs</literal> (<type>array</type>): Array of string arguments to pass to <literal>mongocryptd</literal> when spawning. Defaults to <literal>["--idleShutdownTimeoutSecs=60"]</literal>.</member>
773-
<member><literal>cryptSharedLibPath</literal> (<type>string</type>): Absolute path to <literal>crypt_shared</literal> shared library. Defaults to empty string and consults system paths.</member>
774-
<member><literal>cryptSharedLibRequired</literal> (<type>bool</type>): If &true;, require the driver to load <literal>crypt_shared</literal>. Defaults to &false;.</member>
775-
</simplelist>
776-
<para>
777-
See the <link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#extraoptions">Client-Side Encryption Specification</link> for more information.
778-
</para>
779-
</entry>
780-
</row>
781-
</tbody>
782-
</tgroup>
783-
</table>
784-
</para>
785-
786-
<note>
787-
<simpara>
788-
Automatic encryption is an enterprise only feature that only
789-
applies to operations on a collection. Automatic encryption is not
790-
supported for operations on a database or view, and operations that
791-
are not bypassed will result in error. To bypass automatic
792-
encryption for all operations, set <literal>bypassAutoEncryption=true</literal>
793-
in <literal>autoEncryption</literal>. For more information on
794-
allowed operations, see the
795-
<link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#libmongocrypt-auto-encryption-whitelist">Client-Side Encryption Specification</link>.
796-
</simpara>
797-
</note>
798662
</entry>
799663
</row>
800664
<row>
@@ -865,6 +729,140 @@ mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][
865729
</tgroup>
866730
</table>
867731
</para>
732+
<para xml:id="mongodb-driver-manager.construct-autoencryption">
733+
Options supported by automatic encryption through the <literal>autoEncryption</literal> driver option:
734+
<table>
735+
<title>autoEncryption</title>
736+
<tgroup cols="3">
737+
<thead>
738+
<row>
739+
<entry>Option</entry>
740+
<entry>Type</entry>
741+
<entry>Description</entry>
742+
</row>
743+
</thead>
744+
<tbody>
745+
&mongodb.option.encryption.keyVaultClient;
746+
&mongodb.option.encryption.keyVaultNamespace;
747+
&mongodb.option.encryption.kmsProviders;
748+
&mongodb.option.encryption.tlsOptions;
749+
<row>
750+
<entry>schemaMap</entry>
751+
<entry><type class="union"><type>array</type><type>object</type></type></entry>
752+
<entry>
753+
<para>
754+
Map of collection namespaces to a local JSON schema. This is
755+
used to configure automatic encryption. See
756+
<link xlink:href="&url.mongodb.docs;reference/security-client-side-automatic-json-schema/">Automatic Encryption Rules</link>
757+
in the MongoDB manual for more information. It is an error to
758+
specify a collection in both <literal>schemaMap</literal> and
759+
<literal>encryptedFieldsMap</literal>.
760+
</para>
761+
<note>
762+
<simpara>
763+
Supplying a <literal>schemaMap</literal> provides more
764+
security than relying on JSON schemas obtained from the
765+
server. It protects against a malicious server advertising a
766+
false JSON schema, which could trick the client into sending
767+
unencrypted data that should be encrypted.
768+
</simpara>
769+
</note>
770+
<note>
771+
<simpara>
772+
Schemas supplied in the <literal>schemaMap</literal> only
773+
apply to configuring automatic encryption for client side
774+
encryption. Other validation rules in the JSON schema will
775+
not be enforced by the driver and will result in an error.
776+
</simpara>
777+
</note>
778+
</entry>
779+
</row>
780+
<row>
781+
<entry>bypassAutoEncryption</entry>
782+
<entry><type>bool</type></entry>
783+
<entry>
784+
If &true;, <literal>mongocryptd</literal> will not be spawned
785+
automatically. This is used to disable automatic encryption.
786+
Defaults to &false;.
787+
</entry>
788+
</row>
789+
<row>
790+
<entry>bypassQueryAnalysis</entry>
791+
<entry><type>bool</type></entry>
792+
<entry>
793+
<para>
794+
If &true;, automatic analysis of outgoing commands will be
795+
disabled and <literal>mongocryptd</literal> will not be
796+
spawned automatically. This enables the use case of explicit
797+
encryption for querying indexed fields without requiring the
798+
enterprise licensed <literal>crypt_shared</literal> library or
799+
<literal>mongocryptd</literal> process. Defaults to &false;.
800+
</para>
801+
</entry>
802+
</row>
803+
<row>
804+
<entry>encryptedFieldsMap</entry>
805+
<entry><type class="union"><type>array</type><type>object</type></type></entry>
806+
<entry>
807+
<para>
808+
Map of collection namespaces to an
809+
<literal>encryptedFields</literal> document. This is used to
810+
configure queryable encryption. See
811+
<link xlink:href="&url.mongodb.docs;core/queryable-encryption/fundamentals/encrypt-and-query/">Field Encryption and Queryability</link>
812+
in the MongoDB manual for more information. It is an error to
813+
specify a collection in both
814+
<literal>encryptedFieldsMap</literal> and
815+
<literal>schemaMap</literal>.
816+
</para>
817+
<note>
818+
<simpara>
819+
Supplying an <literal>encryptedFieldsMap</literal> provides
820+
more security than relying on an
821+
<literal>encryptedFields</literal> obtained from the server.
822+
It protects against a malicious server advertising a false
823+
<literal>encryptedFields</literal>.
824+
</simpara>
825+
</note>
826+
</entry>
827+
</row>
828+
<row>
829+
<entry>extraOptions</entry>
830+
<entry><type>array</type></entry>
831+
<entry>
832+
<para>
833+
The <literal>extraOptions</literal> relate to the
834+
<literal>mongocryptd</literal> process. The following options
835+
are supported:
836+
</para>
837+
<simplelist>
838+
<member><literal>mongocryptdURI</literal> (<type>string</type>): URI to connect to an existing <literal>mongocryptd</literal> process. Defaults to <literal>"mongodb://localhost:27020"</literal>.</member>
839+
<member><literal>mongocryptdBypassSpawn</literal> (<type>bool</type>): If &true;, prevent the driver from spawning <literal>mongocryptd</literal>. Defaults to &false;.</member>
840+
<member><literal>mongocryptdSpawnPath</literal> (<type>string</type>): Absolute path to search for <literal>mongocryptd</literal> binary. Defaults to empty string and consults system paths.</member>
841+
<member><literal>mongocryptdSpawnArgs</literal> (<type>array</type>): Array of string arguments to pass to <literal>mongocryptd</literal> when spawning. Defaults to <literal>["--idleShutdownTimeoutSecs=60"]</literal>.</member>
842+
<member><literal>cryptSharedLibPath</literal> (<type>string</type>): Absolute path to <literal>crypt_shared</literal> shared library. Defaults to empty string and consults system paths.</member>
843+
<member><literal>cryptSharedLibRequired</literal> (<type>bool</type>): If &true;, require the driver to load <literal>crypt_shared</literal>. Defaults to &false;.</member>
844+
</simplelist>
845+
<para>
846+
See the <link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#extraoptions">Client-Side Encryption Specification</link> for more information.
847+
</para>
848+
</entry>
849+
</row>
850+
</tbody>
851+
</tgroup>
852+
</table>
853+
<note>
854+
<simpara>
855+
Automatic encryption is an enterprise only feature that only
856+
applies to operations on a collection. Automatic encryption is not
857+
supported for operations on a database or view, and operations that
858+
are not bypassed will result in error. To bypass automatic
859+
encryption for all operations, set <literal>bypassAutoEncryption=true</literal>
860+
in <literal>autoEncryption</literal>. For more information on
861+
allowed operations, see the
862+
<link xlink:href="&url.mongodb.specs;/blob/master/source/client-side-encryption/client-side-encryption.rst#libmongocrypt-auto-encryption-whitelist">Client-Side Encryption Specification</link>.
863+
</simpara>
864+
</note>
865+
</para>
868866
</listitem>
869867
</varlistentry>
870868
</variablelist>

0 commit comments

Comments
 (0)