diff --git a/source/client-side-encryption/client-side-encryption.rst b/source/client-side-encryption/client-side-encryption.rst index 0a92f12f56..8b5a5c09f6 100644 --- a/source/client-side-encryption/client-side-encryption.rst +++ b/source/client-side-encryption/client-side-encryption.rst @@ -4,6 +4,8 @@ Client Side Encryption :Status: Accepted :Minimum Server Version: 4.2 (CSFLE), 6.0 (Queryable Encryption) +:Last Modified: 2022-10-26 +:Version: 1.11.0 .. _lmc-c-api: https://github.com/mongodb/libmongocrypt/blob/master/src/mongocrypt.h.in @@ -1572,6 +1574,9 @@ is propagated to the user. Connecting to mongocryptd_ -------------------------- +If the crypt_shared_ library is loaded, the driver MUST NOT attempt to connect +to mongocryptd_. (Refer: `Detecting crypt_shared Availability`_). + Single-threaded drivers MUST connect with `serverSelectionTryOnce=false <../server-selection/server-selection.rst#serverselectiontryonce>`_ , connectTimeoutMS=10000, and MUST bypass `cooldownMS <../server-discovery-and-monitoring/server-discovery-and-monitoring.rst#cooldownms>`__ when connecting to mongocryptd. See `Why are serverSelectionTryOnce and cooldownMS disabled for single-threaded drivers connecting to mongocryptd?`_. @@ -1583,7 +1588,7 @@ selection error is propagated to the user. .. note:: A correctly-behaving driver will never attempt to connect to mongocryptd_ - when |opt-crypt_shared-required| is set to |true|. + when |opt-crypt_shared-required| is set to |true| or crypt_shared_ is loaded. ClientEncryption ================ @@ -2515,6 +2520,7 @@ Changelog :align: left Date, Description + 22-10-26, Do not connect to `mongocryptd` if shared library is loaded. 22-10-11, Specify a timeout on Azure IMDS HTTP requests and fix the resource URL 22-10-05, Remove spec front matter and ``versionadded`` RST macros (since spec version was removed) 22-09-26, Add behavior for automatic Azure KeyVault credentials for ``kmsProviders``. diff --git a/source/client-side-encryption/tests/README.rst b/source/client-side-encryption/tests/README.rst index 5457de981b..6e40d2b0a4 100644 --- a/source/client-side-encryption/tests/README.rst +++ b/source/client-side-encryption/tests/README.rst @@ -2379,3 +2379,43 @@ This should successfully load and use the Azure credentials of the service accou attached to the virtual machine. Expect the key to be successfully created. + +20. Bypass creating mongocryptd client when shared library is loaded +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + IMPORTANT: If crypt_shared_ is not visible to the operating system's library + search mechanism, this test should be skipped. + + +The following tests that a mongocryptd client is not created when shared library is in-use. + +#. Start a new thread (referred to as ``listenerThread``) + +#. On ``listenerThread``, create a TcpListener on 127.0.0.1 endpoint and port 27021. Start the listener and wait for establishing connections. + If any connection is established, then signal about this to the main thread. + + Drivers MAY pass a different port if they expect their testing infrastructure to be using port 27021. Pass a port that should be free. + +#. Create a MongoClient configured with auto encryption (referred to as ``client_encrypted``) + + Configure the required options. Use the ``local`` KMS provider as follows: + + .. code:: javascript + + { "local": { "key": } } + + Configure with the ``keyVaultNamespace`` set to ``keyvault.datakeys``. + + Configure the following ``extraOptions``: + + .. code:: javascript + + { + "mongocryptdURI": "mongodb://localhost:27021" + } + +#. Use ``client_encrypted`` to insert the document ``{"unencrypted": "test"}`` into ``db.coll``. + +#. Expect no signal from ``listenerThread``.