DOCSP-29387 - CSFLE - Change references from mongocryptd to Shared Library (#4290)

* Change references from mongocryptd to Shared Library

* add to toc

* add readers and remove mongocryptd from tutorial text

* add csfle shared library note

* fix link to learn more note

* Chris feedback csfle

* Chris feedback qe

* remove libmongocrypt note

* caps

* Cynthia feedback

Author: jordan-smith721

source/core/csfle/install.txt

@@ -25,15 +25,15 @@ What You Need
 Before you can use {+csfle-abbrev+}, you must set up the following items
 in your development environment:
 
+- (Optional) Download the :ref:`{+shared-library+} <csfle-reference-shared-library-download>`. 
+  The shared library is a preferred alternative to :ref:`mongocryptd <csfle-mongocryptd>` and
+  does not require spawning a new process. `mongocryptd` is still supported.
 - Install :manual:`MongoDB Enterprise Edition version 4.2 or later </installation/#mongodb-enterprise-edition-installation-tutorials>`.
 - Install a :ref:`MongoDB Driver Compatible with CSFLE <csfle-driver-compatibility>`.
 - Start a
   :manual:`MongoDB instance </tutorial/manage-mongodb-processes/#start-mongod-processes>`
   or
   :atlas:`Atlas Cluster </getting-started?jmp=docs>`.
-- Grant file system permissions. The client application or a privileged
-  user needs permissions to start the :ref:`mongocryptd
-  <csfle-reference-mongocryptd>` process on the host.
 - Install specific driver dependencies. To see the list of
   dependencies for your driver, select the tab corresponding to the language you
   would like to use to complete this guide:

source/core/csfle/reference.txt

@@ -27,6 +27,7 @@ of the {+csfle+} ({+csfle-abbrev+}) feature:
 - :ref:`csfle-reference-encryption-components`
 - :ref:`csfle-reference-decryption`
 - :ref:`csfle-reference-cryptographic-primitives`
+- :ref:`csfle-reference-shared-library`
 - :ref:`csfle-reference-mongocryptd`
 - :ref:`csfle-reference-libmongocrypt`
 
@@ -43,5 +44,6 @@ of the {+csfle+} ({+csfle-abbrev+}) feature:
    /core/csfle/reference/encryption-components
    /core/csfle/reference/decryption
    /core/csfle/reference/cryptographic-primitives
+   /core/csfle/reference/shared-library
    /core/csfle/reference/mongocryptd
    /core/csfle/reference/libmongocrypt

source/core/csfle/reference/encryption-schemas.txt

@@ -107,14 +107,14 @@ Definition
 
    If :autoencryptkeyword:`~encrypt.keyId` or
    :autoencryptkeyword:`~encrypt.algorithm` are omitted, the
-   :ref:`mongocryptd` checks the full tree of parent fields and attempts
-   to construct those options from the nearest
+   :ref:`Shared Library <csfle-reference-shared-library>` checks all parent
+   fields and attempts to construct those options from the nearest
    :autoencryptkeyword:`encryptMetadata` object that specifies the
    option. :autoencryptkeyword:`~encrypt.bsonType` cannot be inherited
    and *may* be required depending on the value of
    :autoencryptkeyword:`~encrypt.algorithm`.
 
-   If ``mongocryptd`` cannot construct the full ``encrypt`` object using
+   If the Shared Library cannot construct the full ``encrypt`` object using
    the fields specified to the object and any required
    ``encryptMetadata``-inherited keys, automatic encryption fails and
    returns an error.
@@ -133,10 +133,10 @@ Definition
    For complete documentation on the encryption algorithms, see
    :ref:`csfle-reference-encryption-algorithms`.
 
-   If omitted, :ref:`<csfle-reference-mongocryptd>` checks the full tree of parent fields
-   for the nearest :autoencryptkeyword:`encryptMetadata.algorithm` key
-   and inherits that value. If no parent
-   :autoencryptkeyword:`~encryptMetadata.algorithm` exists, automatic
+   If omitted, the :ref:`Shared Library <csfle-reference-shared-library>` checks
+   all parent fields for the closest ancestor containing an
+   :autoencryptkeyword:`encryptMetadata.algorithm` key and inherits that value.
+   If no parent :autoencryptkeyword:`~encryptMetadata.algorithm` exists, automatic
    field level encryption fails and returns an error.
 
    - If ``encrypt.algorithm`` or its inherited value is
@@ -196,8 +196,8 @@ Definition
 
   Specify *one* string inside the array.
 
-  If omitted, :ref:`mongocryptd` checks the full tree of parent
-  fields for the nearest 
+  If omitted, the :ref:`Shared Library <csfle-reference-shared-library>` checks
+  all parent fields for the closest ancestor containing an 
   :autoencryptkeyword:`encryptMetadata.keyId` key and inherits
   that value. If no parent 
   :autoencryptkeyword:`~encryptMetadata.keyId` exists,
@@ -239,7 +239,7 @@ Definition
   Defines encryption options which an :autoencryptkeyword:`encrypt`
   object nested in the sibling ``properties`` may inherit. If an
   :autoencryptkeyword:`encrypt` is missing an option required to support
-  encryption, ``mongocryptd`` searches the entire tree of parent objects
+  encryption, the Shared Library searches all parent objects
   to locate an :autoencryptkeyword:`encryptMetadata` object that
   specifies the missing option.
 
@@ -263,8 +263,8 @@ Definition
 
   The encryption algorithm to use to encrypt a given field. If an
   :autoencryptkeyword:`encrypt` object is missing the
-  :autoencryptkeyword:`~encrypt.algorithm` field, ``mongocryptd``
-  searches the entire tree of parent objects to locate an
+  :autoencryptkeyword:`~encrypt.algorithm` field, the Shared Library
+  searches all parent objects to locate an
   :autoencryptkeyword:`encryptMetadata` object that specifies
   :autoencryptkeyword:`encryptMetadata.algorithm`.
 
@@ -290,8 +290,8 @@ Definition
   Specify *one* string inside the array.
 
   If an :autoencryptkeyword:`encrypt` object is missing the 
-  :autoencryptkeyword:`~encrypt.keyId` field, ``mongocryptd``
-  searches the entire tree of parent objects to locate 
+  :autoencryptkeyword:`~encrypt.keyId` field, the Shared Library
+  searches all parent objects to locate 
   an :autoencryptkeyword:`encryptMetadata` object that
   specifies :autoencryptkeyword:`encryptMetadata.keyId`.
 

source/core/csfle/reference/shared-library.txt

@@ -0,0 +1,97 @@
+.. _csfle-reference-shared-library:
+
+=============================================
+{+shared-library+} for {+csfle-abbrev+}
+=============================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+The {+shared-library+} is a **dynamic library** that enables your client
+application to perform {+csfle+}.
+A dynamic library is a set of functionality accessed
+by an application at runtime rather than compile time.
+The {+shared-library+} performs the following tasks:
+
+- Reads the encryption schema to determine which fields to encrypt or decrypt
+- Prevents your application from executing unsupported operations on encrypted
+  fields
+
+The {+shared-library+} *does not* do any of the following:
+
+- Perform data encryption or decryption
+- Access the encryption key material
+- Listen for data over the network
+
+The {+shared-library+} is a preferred alternative to ``mongocryptd`` and does
+not require you to spawn another process to perform automatic encryption.
+
+.. tip::
+   
+   While we recommend using the {+shared-library+}, ``mongocryptd`` is still supported.
+
+   To learn more about ``mongocryptd``, see :ref:`<csfle-reference-mongocryptd>`.
+
+To learn more about automatic encryption, see
+:ref:`<csfle-features>`.
+
+.. _csfle-reference-shared-library-download:
+
+Download the {+shared-library+}
+------------------------------------------------
+
+Download the {+shared-library+} from the `MongoDB Download Center <https://www.mongodb.com/try/download/enterprise>`__ by selecting the
+version and platform, then the library: 
+
+#. In the :guilabel:`Version` dropdown, select ``{+shared-library-version-drop-down+}``.
+#. In the :guilabel:`Platform` dropdown, select your platform.
+#. In the :guilabel:`Package` dropdown, select ``crypt_shared``.
+#. Click :guilabel:`Download`.
+
+.. tip::
+
+   To view an expanded list of available releases and packages, see
+   `MongoDB Enterprise Downloads <https://www.mongodb.com/download-center/enterprise/releases>`__.
+
+.. _csfle-reference-shared-library-configuration:
+
+Configuration
+-------------
+
+You can configure how your driver searches for the {+shared-library+}
+through the following parameters:
+
+.. list-table::
+    :header-rows: 1
+    :stub-columns: 1
+    :widths: 30 70
+
+    * - Name
+      - Description
+
+    * - cryptSharedLibPath
+      - | Specifies the absolute path to the {+shared-library+} package,
+        | {+shared-library-package+}.
+        | **Default**: ``undefined``
+
+    * - cryptSharedLibRequired
+      - | Specifies if the driver must use the {+shared-library+}. If ``true``,
+        | the driver raises an error if the {+shared-library+} is unavailable.
+        | If ``false``, the driver performs the following sequence of actions:
+        
+        #. Attempts to use the {+shared-library+}.
+        #. If the {+shared-library+} is unavailable, the driver attempts to
+           spawn and connect to ``mongocryptd``.
+   
+        | **Default**: ``false``
+
+To view an example demonstrating how to configure these parameters, see
+the :ref:`Quick Start <csfle-quick-start>`.

source/core/queryable-encryption/reference/shared-library.txt

@@ -21,16 +21,15 @@ A dynamic library is a set of functionality accessed
 by an application at runtime rather than compile time.
 The {+shared-library+} performs the following tasks:
 
-- Uses your {+enc-fields-map+} to mark fields in
-  read and write operations for encryption
+- Reads the {+enc-fields-map+} to determine which fields to encrypt or decrypt
 - Prevents your application from executing unsupported operations on encrypted
   fields
 
-The {+shared-library+} does not perform any of the following tasks:
+The {+shared-library+} *does not* do any of the following:
 
-- The {+shared-library+} *does not* perform encryption or decryption itself
-- The {+shared-library+} *does not* access any encryption key material
-- The {+shared-library+} *does not* listen over the network
+- Perform data encryption or decryption
+- Access the encryption key material
+- Listen for data over the network
 
 .. important:: Supported MongoDB Server Products
 
@@ -42,40 +41,35 @@ The {+shared-library+} does not perform any of the following tasks:
    Automatic {+qe+} is not available in any version of MongoDB
    Community Server.
 
-The {+shared-library+} provides the same functionality as ``mongocryptd``,
-but does not require you to spawn another process to perform automatic
-encryption.
+The {+shared-library+} is a preferred alternative to ``mongocryptd`` and does
+not require you to spawn another process to perform automatic encryption.
 
-To learn more about automatic encryption, see
-:ref:`<qe-features>`.
-
-To learn more about ``mongocryptd``, see
-:ref:`<qe-reference-mongocryptd>`.
+.. tip::
+   
+   While we recommend using the {+shared-library+}, ``mongocryptd`` is still supported.
 
-.. note:: libmongocrypt Performs Encryption
+   To learn more about ``mongocryptd``, see :ref:`<qe-reference-mongocryptd>`.
 
-   Drivers compatible with MongoDB 6.0 and later use the
-   Apache-licensed `libmongocrypt
-   <https://github.com/mongodb/libmongocrypt>`__ library for performing
-   encryption and decryption.
+To learn more about automatic encryption, see
+:ref:`<qe-features>`.
 
 .. _qe-reference-shared-library-download:
 
 Download the {+shared-library+}
 ------------------------------------------------
 
-Download the {+shared-library+} using one of the following methods:
+Download the {+shared-library+} from the `MongoDB Download Center <https://www.mongodb.com/try/download/enterprise>`__ by selecting the
+version and platform, then the library: 
 
-* Download the latest {+shared-library-package+} library archive for your
-  platform from `MongoDB Enterprise Downloads <https://www.mongodb.com/download-center/enterprise/releases>`__.
+#. In the :guilabel:`Version` dropdown, select ``{+shared-library-version-drop-down+}``.
+#. In the :guilabel:`Platform` dropdown, select your platform.
+#. In the :guilabel:`Package` dropdown, select ``crypt_shared``.
+#. Click :guilabel:`Download`.
 
-* Download the {+shared-library+} from the `MongoDB Download Center <https://www.mongodb.com/try/download/enterprise>`__ by selecting the
-  version and platform, then the library: 
+.. tip::
 
-  #. In the **Version** dropdown, select ``{+shared-library-version-drop-down+}``.
-  #. In the **Platform** dropdown, select your platform.
-  #. In the **Package** dropdown, select ``crypt_shared``.
-  #. Click **Download**.
+   To view an expanded list of available releases and packages, see
+   `MongoDB Enterprise Downloads <https://www.mongodb.com/download-center/enterprise/releases>`__.
 
 .. _qe-reference-shared-library-configuration:
 

source/includes/generated/in-use-encryption/csfle/dotnet/aws/reader/CSFLE/InsertEncryptedDocument.cs

@@ -113,10 +113,10 @@ public static void Insert()
 
 
             // start-extra-options
-            var mongoBinariesPath = "<Path to mongocryptd binary>";
+            var mongoBinariesPath = "<Full path to your Automatic Encryption Shared Library>";
             var extraOptions = new Dictionary<string, object>()
             {
-               { "mongocryptdSpawnPath", mongoBinariesPath },
+               { "cryptSharedLibPath", mongoBinariesPath },
             };
             // end-extra-options
 

source/includes/generated/in-use-encryption/csfle/dotnet/azure/reader/CSFLE/InsertEncryptedDocument.cs

@@ -114,10 +114,10 @@ public static void Insert()
 
 
             // start-extra-options
-            var mongoBinariesPath = "<Path to mongocryptd binary>";
+            var mongoBinariesPath = "<Full path to your Automatic Encryption Shared Library>";
             var extraOptions = new Dictionary<string, object>()
             {
-               { "mongocryptdSpawnPath", mongoBinariesPath },
+               { "cryptSharedLibPath", mongoBinariesPath },
             };
             // end-extra-options
 

source/includes/generated/in-use-encryption/csfle/dotnet/gcp/reader/CSFLE/InsertEncryptedDocument.cs

@@ -113,10 +113,10 @@ public static void Insert()
 
 
             // start-extra-options
-            var mongoBinariesPath = "<Path to mongocryptd binary>";
+            var mongoBinariesPath = "<Full path to your Automatic Encryption Shared Library>";
             var extraOptions = new Dictionary<string, object>()
             {
-               { "mongocryptdSpawnPath", mongoBinariesPath },
+               { "cryptSharedLibPath", mongoBinariesPath },
             };
             // end-extra-options
 

source/includes/generated/in-use-encryption/csfle/dotnet/kmip/reader/CSFLE/InsertEncryptedDocument.cs

@@ -122,10 +122,10 @@ public static void Insert()
             // end-create-tls
 
             // start-extra-options
-            var mongoBinariesPath = "<Path to mongocryptd binary>";
+            var mongoBinariesPath = "<Full path to your Automatic Encryption Shared Library>";
             var extraOptions = new Dictionary<string, object>()
             {
-               { "mongocryptdSpawnPath", mongoBinariesPath },
+               { "cryptSharedLibPath", mongoBinariesPath },
             };
             // end-extra-options
 

source/includes/generated/in-use-encryption/csfle/dotnet/local/reader/CSFLE/InsertEncryptedDocument.cs

@@ -116,10 +116,10 @@ public static void Insert()
 
 
             // start-extra-options
-            var mongoBinariesPath = "<Path to mongocryptd binary>";
+            var mongoBinariesPath = "<Full path to your Automatic Encryption Shared Library>";
             var extraOptions = new Dictionary<string, object>()
             {
-               { "mongocryptdSpawnPath", mongoBinariesPath },
+               { "cryptSharedLibPath", mongoBinariesPath },
             };
             // end-extra-options