[DOC-CVS] [doc-en] master: Extract `autoEncryption` driver options in `MongoDB\Driver\Manager::__construct()` (#4754)
[email protected] (Jérôme Tamarelle via GitHub)
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: Jérôme Tamarelle (GromNaN) Committer: GitHub (web-flow) Pusher: alcaeus Date: 2025-07-08T13:41:45+02:00 Commit: https://github.com/php/doc-en/commit/7ba4efc7524c06343c6e9f1fc2b10f91cfdfd945 Raw diff: https://github.com/php/doc-en/commit/7ba4efc7524c06343c6e9f1fc2b10f91cfdfd945.diff 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 <[email protected]> Changed paths: M reference/mongodb/mongodb/driver/manager/construct.xml Diff: diff --git a/reference/mongodb/mongodb/driver/manager/construct.xml b/reference/mongodb/mongodb/driver/manager/construct.xml index a6104a2250ca..575cee2882e3 100644 --- a/reference/mongodb/mongodb/driver/manager/construct.xml +++ b/reference/mongodb/mongodb/driver/manager/construct.xml @@ -636,7 +636,7 @@ mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][ <entry> <para> Provides options to enable automatic client-side field level - encryption. + encryption. The list of options is described in the <link linkend="mongodb-driver-manager.construct-autoencryption">table below</link>. </para> <note> <para> @@ -659,142 +659,6 @@ mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][ <literal>bypassAutoEncryption</literal> is &true;. </para> </note> - <para> - The following options are supported: - - <table> - <title>Options for automatic encryption</title> - <tgroup cols="3"> - <thead> - <row> - <entry>Option</entry> - <entry>Type</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - &mongodb.option.encryption.keyVaultClient; - &mongodb.option.encryption.keyVaultNamespace; - &mongodb.option.encryption.kmsProviders; - &mongodb.option.encryption.tlsOptions; - <row> - <entry>schemaMap</entry> - <entry><type class="union"><type>array</type><type>object</type></type></entry> - <entry> - <para> - Map of collection namespaces to a local JSON schema. This is - used to configure automatic encryption. See - <link xlink:href="&url.mongodb.docs;reference/security-client-side-automatic-json-schema/">Automatic Encryption Rules</link> - in the MongoDB manual for more information. It is an error to - specify a collection in both <literal>schemaMap</literal> and - <literal>encryptedFieldsMap</literal>. - </para> - <note> - <simpara> - Supplying a <literal>schemaMap</literal> provides more - security than relying on JSON schemas obtained from the - server. It protects against a malicious server advertising a - false JSON schema, which could trick the client into sending - unencrypted data that should be encrypted. - </simpara> - </note> - <note> - <simpara> - Schemas supplied in the <literal>schemaMap</literal> only - apply to configuring automatic encryption for client side - encryption. Other validation rules in the JSON schema will - not be enforced by the driver and will result in an error. - </simpara> - </note> - </entry> - </row> - <row> - <entry>bypassAutoEncryption</entry> - <entry><type>bool</type></entry> - <entry> - If &true;, <literal>mongocryptd</literal> will not be spawned - automatically. This is used to disable automatic encryption. - Defaults to &false;. - </entry> - </row> - <row> - <entry>bypassQueryAnalysis</entry> - <entry><type>bool</type></entry> - <entry> - <para> - If &true;, automatic analysis of outgoing commands will be - disabled and <literal>mongocryptd</literal> will not be - spawned automatically. This enables the use case of explicit - encryption for querying indexed fields without requiring the - enterprise licensed <literal>crypt_shared</literal> library or - <literal>mongocryptd</literal> process. Defaults to &false;. - </para> - </entry> - </row> - <row> - <entry>encryptedFieldsMap</entry> - <entry><type class="union"><type>array</type><type>object</type></type></entry> - <entry> - <para> - Map of collection namespaces to an - <literal>encryptedFields</literal> document. This is used to - configure queryable encryption. See - <link xlink:href="&url.mongodb.docs;core/queryable-encryption/fundamentals/encrypt-and-query/">Field Encryption and Queryability</link> - in the MongoDB manual for more information. It is an error to - specify a collection in both - <literal>encryptedFieldsMap</literal> and - <literal>schemaMap</literal>. - </para> - <note> - <simpara> - Supplying an <literal>encryptedFieldsMap</literal> provides - more security than relying on an - <literal>encryptedFields</literal> obtained from the server. - It protects against a malicious server advertising a false - <literal>encryptedFields</literal>. - </simpara> - </note> - </entry> - </row> - <row> - <entry>extraOptions</entry> - <entry><type>array</type></entry> - <entry> - <para> - The <literal>extraOptions</literal> relate to the - <literal>mongocryptd</literal> process. The following options - are supported: - </para> - <simplelist> - <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> - <member><literal>mongocryptdBypassSpawn</literal> (<type>bool</type>): If &true;, prevent the driver from spawning <literal>mongocryptd</literal>. Defaults to &false;.</member> - <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> - <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> - <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> - <member><literal>cryptSharedLibRequired</literal> (<type>bool</type>): If &true;, require the driver to load <literal>crypt_shared</literal>. Defaults to &false;.</member> - </simplelist> - <para> - 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. - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> - </para> - - <note> - <simpara> - Automatic encryption is an enterprise only feature that only - applies to operations on a collection. Automatic encryption is not - supported for operations on a database or view, and operations that - are not bypassed will result in error. To bypass automatic - encryption for all operations, set <literal>bypassAutoEncryption=true</literal> - in <literal>autoEncryption</literal>. For more information on - allowed operations, see the - <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>. - </simpara> - </note> </entry> </row> <row> @@ -865,6 +729,140 @@ mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][ </tgroup> </table> </para> + <para xml:id="mongodb-driver-manager.construct-autoencryption"> + Options supported by automatic encryption through the <literal>autoEncryption</literal> driver option: + <table> + <title>autoEncryption</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Option</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + &mongodb.option.encryption.keyVaultClient; + &mongodb.option.encryption.keyVaultNamespace; + &mongodb.option.encryption.kmsProviders; + &mongodb.option.encryption.tlsOptions; + <row> + <entry>schemaMap</entry> + <entry><type class="union"><type>array</type><type>object</type></type></entry> + <entry> + <para> + Map of collection namespaces to a local JSON schema. This is + used to configure automatic encryption. See + <link xlink:href="&url.mongodb.docs;reference/security-client-side-automatic-json-schema/">Automatic Encryption Rules</link> + in the MongoDB manual for more information. It is an error to + specify a collection in both <literal>schemaMap</literal> and + <literal>encryptedFieldsMap</literal>. + </para> + <note> + <simpara> + Supplying a <literal>schemaMap</literal> provides more + security than relying on JSON schemas obtained from the + server. It protects against a malicious server advertising a + false JSON schema, which could trick the client into sending + unencrypted data that should be encrypted. + </simpara> + </note> + <note> + <simpara> + Schemas supplied in the <literal>schemaMap</literal> only + apply to configuring automatic encryption for client side + encryption. Other validation rules in the JSON schema will + not be enforced by the driver and will result in an error. + </simpara> + </note> + </entry> + </row> + <row> + <entry>bypassAutoEncryption</entry> + <entry><type>bool</type></entry> + <entry> + If &true;, <literal>mongocryptd</literal> will not be spawned + automatically. This is used to disable automatic encryption. + Defaults to &false;. + </entry> + </row> + <row> + <entry>bypassQueryAnalysis</entry> + <entry><type>bool</type></entry> + <entry> + <para> + If &true;, automatic analysis of outgoing commands will be + disabled and <literal>mongocryptd</literal> will not be + spawned automatically. This enables the use case of explicit + encryption for querying indexed fields without requiring the + enterprise licensed <literal>crypt_shared</literal> library or + <literal>mongocryptd</literal> process. Defaults to &false;. + </para> + </entry> + </row> + <row> + <entry>encryptedFieldsMap</entry> + <entry><type class="union"><type>array</type><type>object</type></type></entry> + <entry> + <para> + Map of collection namespaces to an + <literal>encryptedFields</literal> document. This is used to + configure queryable encryption. See + <link xlink:href="&url.mongodb.docs;core/queryable-encryption/fundamentals/encrypt-and-query/">Field Encryption and Queryability</link> + in the MongoDB manual for more information. It is an error to + specify a collection in both + <literal>encryptedFieldsMap</literal> and + <literal>schemaMap</literal>. + </para> + <note> + <simpara> + Supplying an <literal>encryptedFieldsMap</literal> provides + more security than relying on an + <literal>encryptedFields</literal> obtained from the server. + It protects against a malicious server advertising a false + <literal>encryptedFields</literal>. + </simpara> + </note> + </entry> + </row> + <row> + <entry>extraOptions</entry> + <entry><type>array</type></entry> + <entry> + <para> + The <literal>extraOptions</literal> relate to the + <literal>mongocryptd</literal> process. The following options + are supported: + </para> + <simplelist> + <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> + <member><literal>mongocryptdBypassSpawn</literal> (<type>bool</type>): If &true;, prevent the driver from spawning <literal>mongocryptd</literal>. Defaults to &false;.</member> + <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> + <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> + <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> + <member><literal>cryptSharedLibRequired</literal> (<type>bool</type>): If &true;, require the driver to load <literal>crypt_shared</literal>. Defaults to &false;.</member> + </simplelist> + <para> + 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. + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <note> + <simpara> + Automatic encryption is an enterprise only feature that only + applies to operations on a collection. Automatic encryption is not + supported for operations on a database or view, and operations that + are not bypassed will result in error. To bypass automatic + encryption for all operations, set <literal>bypassAutoEncryption=true</literal> + in <literal>autoEncryption</literal>. For more information on + allowed operations, see the + <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>. + </simpara> + </note> + </para> </listitem> </varlistentry> </variablelist>