Skip to content

Extract autoEncryption driver options in MongoDB\Driver\Manager::__construct() #4754

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+135 −137
Open

Extract autoEncryption driver options in MongoDB\Driver\Manager::__construct() #4754

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
272 changes: 135 additions & 137 deletions reference/mongodb/mongodb/driver/manager/construct.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 table below.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like to add a link to a reference in the page.

</para>
<note>
<para>
Expand All @@ -659,142 +659,6 @@ mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][
<literal>bypassAutoEncryption</literal> is &true;.
</para>
</note>
<para>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to add a note that these are explained separately below? We could also close out the current <table> and <para>, then add a new <para> with a title of "Auto encryption options" to create a separate table for them. That table could specifies that "these keys are available in the autoEncryption driver option, which would allow you to skip refactoring of the language snippets.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reworked the PR to create a new table and keep the full row entities.

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>
Expand Down Expand Up @@ -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:
<table>
<title>autoEncryption</title>
<tgroup cols="3">
Copy link
Member Author

@GromNaN GromNaN Jul 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I could add this to set the column widths, but this is not using % anywhere.

Suggested change
<tgroup cols="3">
<tgroup cols="3">
<colspec colwidth="25%" colname="option"/>
<colspec colwidth="10%" colname="type"/>
<colspec colwidth="65%" colname="description"/>

In few places it's using 2* notation that is not handled by the website.

doc-en/reference/yaz/functions/yaz-hits.xml

Lines 61 to 63 in c21abf2

<tgroup cols="2">
<colspec colwidth="1*" colname="element"/>
<colspec colwidth="2*" colname="description"/>

The website CSS should use table-layout: auto instead of fixed so that the column width are adjusted automatically.

<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>
Expand Down