mirror of
https://github.com/php/doc-en.git
synced 2026-03-23 23:32:18 +01:00
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>
This commit is contained in:
Jérôme Tamarelle
@@ -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>
|
||||
|
||||
Reference in New Issue
Block a user