Merge branch 'v4.4.5'

Author: andf-mongodb

source/core/security-client-side-encryption-key-management.txt

@@ -19,9 +19,9 @@ Supported Key Management Services
 
 Client-side field level encryption requires a Key Management Service
 (KMS) for accessing a Customer Master Key (CMK). MongoDB automatically
-encrypts data encryption keys using the specified CMK during 
-:doc:`data encryption key creation 
-</reference/method/KeyVault.createKey>`. 
+encrypts data encryption keys using the specified CMK during
+:doc:`data encryption key creation
+</reference/method/KeyVault.createKey>`.
 
 Deleting the CMK renders all data encryption keys encrypted with that
 CMK as permanently unreadable, which in turn renders all values
@@ -30,7 +30,9 @@ encrypted with those data encryption keys as permanently unreadable.
 Client-side field level encryption supports the following KMS providers:
 
 - :ref:`Amazon Web Services KMS <field-level-encryption-aws-kms>`
-- :ref:`Locally Managed Keyfile <field-level-encryption-local-kms>`
+- :ref:`Azure Key Vault <field-level-encryption-azure-keyvault>`
+- :ref:`Google Cloud Platform KMS <field-level-encryption-gcp-kms>`
+- :ref:`Locally Managed Key <field-level-encryption-local-kms>`
 
 .. _field-level-encryption-aws-kms:
 
@@ -39,43 +41,40 @@ Amazon Web Services KMS
 
 .. include:: /includes/extracts/csfle-aws-kms-4.2.0-4.2.1-broken.rst
 
-MongoDB client-side encryption supports using the 
-`Amazon Web Services Key Management Service 
+MongoDB client-side encryption supports using the
+`Amazon Web Services Key Management Service
 <https://aws.amazon.com/kms>`__ for encrypting
 and decrypting data encryption keys. Specifically, MongoDB securely
 transmits the data encryption key to AWS KMS for encrypting or
 decrypting using the specified Customer Master Key (CMK). The CMK never
-leaves the AWS KMS. 
+leaves the AWS KMS.
 
-The :binary:`~bin.mongo` shell supports two methods for configuring 
+The :binary:`~bin.mongo` shell supports two methods for configuring
 access to an AWS KMS:
 
-- Use the client-side field level encryption :ref:`command-line options 
-  <mongo-client-side-field-level-encryption-options>`,
-
-  *or*
+- Use the client-side field level encryption :ref:`command-line options
+  <mongo-client-side-field-level-encryption-options>`, or
 
 - Use the :method:`Mongo()` constructor to create a database connection
   with the required AWS :ref:`KMS configuration options
   <ClientSideFieldLevelEncryptionOptions>`.
 
-Configuring access to an AWS KMS requires at minimum an AWS access key
-and its corresponding secret key. The IAM user associated to the access
-key *must* have at least one policy with the following actions:
-
-- ``kms:Decrypt`` 
-  `(reference) 
-  <https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html>`__ 
+Configuring access to an AWS KMS requires at minimum an AWS Access Key
+and its corresponding Secret Key. The IAM User associated to the Access
+Key must have at least one policy with the following actions:
 
-- ``kms:Encrypt`` 
-  `(reference) 
-  <https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html>`__ 
+- ``kms:Encrypt``
+  `(reference)
+  <https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html>`__
 
-.. note:: Implement Seperation of Least Privilege for KMS Access
+- ``kms:Decrypt``
+  `(reference)
+  <https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html>`__
 
+.. note:: Implement Principle of Least Privilege for KMS Access
 
-   Consider configuring IAM user roles such that MongoDB has only the 
-   access to the actions and resources required to function. 
+   Consider configuring IAM user roles such that MongoDB has only the
+   access to the actions and resources required to function.
 
    For example, the following policy JSON scopes the required actions to
    a single CMK:
@@ -97,8 +96,90 @@ key *must* have at least one policy with the following actions:
           ]
       }
 
-For complete documentation on data encryption key management using AWS KMS, see 
-:doc:`/tutorial/manage-client-side-encryption-data-keys`.
+For complete documentation on data encryption key management using AWS
+KMS, see :doc:`/tutorial/manage-client-side-encryption-data-keys` and
+select the "Amazon Web Services KMS" tab.
+
+.. _field-level-encryption-azure-keyvault:
+
+Azure Key Vault
+~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.4.5
+
+MongoDB client-side encryption supports using the
+`Azure Key Vault Key Management Service
+<https://docs.microsoft.com/en-us/azure/key-vault/>`__ for encrypting
+and decrypting data encryption keys. Specifically, MongoDB securely
+transmits the data encryption key to Azure Key Vault for encrypting or
+decrypting using the specified Customer Master Key (CMK). The CMK never
+leaves the Azure Key Vault.
+
+The :binary:`~bin.mongo` shell supports specifying Azure Key Vault
+as a KMS using the :method:`Mongo()` constructor using the
+:ref:`KMS configuration options
+<ClientSideFieldLevelEncryptionOptions>`.
+
+Configuring access to Azure Key Vault requires at minimum an Azure
+Tenant ID, Client ID, and Client Secret. The Tenant ID must have the
+ability to perform the following actions:
+
+- ``wrap key``
+  `(reference)
+  <https://docs.microsoft.com/en-us/rest/api/keyvault/wrapkey/wrapkey>`__
+
+- ``unwrap key``
+  `(reference)
+  <https://docs.microsoft.com/en-us/rest/api/keyvault/unwrapkey/unwrapkey>`__
+
+.. note::
+
+   MongoDB does *not* support Azure's client certificate authentication
+   (also known as TLS mutual authentication).
+
+For complete documentation on data encryption key management using
+Azure Key Vault, see
+:doc:`/tutorial/manage-client-side-encryption-data-keys` and select the
+"Azure Key Vault" tab.
+
+.. _field-level-encryption-gcp-kms:
+
+Google Cloud Platform KMS
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.4.5
+
+MongoDB client-side encryption supports using the
+`Google Cloud KMS <https://cloud.google.com/kms/docs/>`__ for encrypting
+and decrypting data encryption keys. Specifically, MongoDB securely
+transmits the data encryption key to Google Cloud KMS for encrypting or
+decrypting using the specified Customer Master Key (CMK). The CMK never
+leaves the Google Cloud KMS.
+
+The :binary:`~bin.mongo` shell supports specifying Google Cloud KMS
+as a KMS using the :method:`Mongo()` constructor using the
+:ref:`KMS configuration options
+<ClientSideFieldLevelEncryptionOptions>`.
+
+Configuring access to Google Cloud KMS requires at minimum a Google
+Cloud Email and associated Private Key. The Google Cloud Email account
+must have the following IAM permissions for the specified Private Key:
+
+- ``cloudkms.cryptoKeyVersions.useToEncrypt``
+
+- ``cloudkms.cryptoKeyVersions.useToDecrypt``
+
+These IAM permissions are included in certain
+`Google Cloud predefined roles
+<https://cloud.google.com/kms/docs/reference/permissions-and-roles#predefined>`__
+or can be included in a
+`Google Cloud custom role
+<https://cloud.google.com/kms/docs/reference/permissions-and-roles#custom_roles>`__.
+
+For complete documentation on data encryption key management using
+Google Cloud KMS, see
+:doc:`/tutorial/manage-client-side-encryption-data-keys` and select the
+"Google Cloud KMS" tab.
 
 .. _field-level-encryption-local-kms:
 
@@ -111,7 +192,8 @@ be a 96-byte long string.
 
 For complete documentation on data encryption key management using a
 locally managed key, see
-:doc:`/tutorial/manage-client-side-encryption-data-keys`.
+:doc:`/tutorial/manage-client-side-encryption-data-keys` and select the
+"Local Keyfile" tab.
 
 .. _field-level-encryption-keyvault:
 
@@ -147,7 +229,7 @@ encryption key management:
      - :method:`KeyVault.deleteKey()`
 
        .. important::
-          
+
           Removing a data encryption key renders all fields encrypted
           using that data encryption key as permanently unreadable.
 
@@ -201,4 +283,4 @@ For complete documentation on data encryption key management, see
    :titlesonly:
    :hidden:
 
-   /tutorial/manage-client-side-encryption-data-keys.txt
+   /tutorial/manage-client-side-encryption-data-keys.txt

source/core/security-client-side-encryption.txt

@@ -168,16 +168,21 @@ driver and each encryption component:
   and is only available with MongoDB Enterprise. ``mongocryptd`` does
   not perform cryptographic functions.
 
-- The key vault is a MongoDB collection that stores all data encryption
-  keys used to encrypt values. Data encryption keys are themselves
-  encrypted using a Customer Master Key (CMK) prior to storage in the
-  collection. The key vault may reside on a different MongoDB cluster
-  than the one storing the encrypted data. See
-  :ref:`field-level-encryption-keyvault` for more information.
-
-- The Key Management System stores the Customer Master Key used to
-  encrypt data encryption keys. See :ref:`field-level-encryption-kms`
-  for more information.
+- The :ref:`Key Vault <field-level-encryption-keyvault>` is a MongoDB
+  collection that stores all data encryption keys used to encrypt
+  values. Data encryption keys are themselves encrypted using a Customer
+  Master Key (CMK) prior to storage in the collection. The key vault may
+  reside on a different MongoDB cluster than the one storing the
+  encrypted data.
+
+- The :ref:`Key Management Service (KMS) <field-level-encryption-kms>`
+  stores the Customer Master Key (CMK) used to encrypt data encryption
+  keys. MongoDB supports the following KMS providers:
+
+  - :ref:`Amazon Web Services KMS <field-level-encryption-aws-kms>`
+  - :ref:`Azure Key Vault <field-level-encryption-azure-keyvault>`
+  - :ref:`Google Cloud Platform KMS <field-level-encryption-gcp-kms>`
+  - :ref:`Locally Managed Key <field-level-encryption-local-kms>`
 
 - The MongoDB cluster which stores the encrypted data may also
   enforce client-side field level encryption. See
@@ -252,8 +257,9 @@ Automatic Field Decryption
 The :bsontype:`BinData <Binary>` blob metadata includes the data
 encryption key ``_id`` and encryption algorithm used to encrypt the
 binary data. The 4.2-compatible drivers and 4.2 :binary:`~bin.mongo`
-shell use this metadata to attempt automatic decryption ``BinData`` type
-6 values. The automatic decryption process works as follows:
+shell use this metadata to attempt automatic decryption of
+:bsontype:`BinData <Binary>` subtype 6 objects. The automatic
+decryption process works as follows:
 
 1. Check the :bsontype:`BinData <Binary>` blob metadata for the
    data encryption key and encryption algorithm used to encrypt the
@@ -265,17 +271,22 @@ shell use this metadata to attempt automatic decryption ``BinData`` type
    the ``BinData`` blob.
 
 #. Check the data encryption key metadata for the Customer Master Key
-   used to encrypt the key material. 
-
-#. For the Amazon Web Services KMS, send the data encryption key to the
-   KMS service for decryption. If the CMK does not exist *or* if the
-   connection configuration does not grant access to the CMK, 
-   decryption fails and the driver returns the ``BinData`` blob.
-
-   For the Locally Managed Key, retrieve the local key and decrypt the
-   data encryption key. If the local key specified in the database
-   configuration was not used to encrypt the data encryption key,
-   decryption fails and the driver returns the ``BinData`` blob.
+   (CMK) used to encrypt the key material. 
+
+#. For the :ref:`Amazon Web Services KMS
+   <field-level-encryption-aws-kms>`, :ref:`Azure Key Vault
+   <field-level-encryption-azure-keyvault>`, or
+   :ref:`Google Cloud Platform KMS <field-level-encryption-gcp-kms>`,
+   send the data encryption key to the KMS provider for decryption. If
+   the CMK does not exist *or* if the connection configuration does not
+   grant access to the CMK, decryption fails and the driver returns the
+   ``BinData`` blob.
+
+   For the :ref:`Locally Managed Key
+   <field-level-encryption-local-kms>`, retrieve the local key and
+   decrypt the data encryption key. If the local key specified in the
+   database configuration was not used to encrypt the data encryption
+   key, decryption fails and the driver returns the ``BinData`` blob.
 
 #. Decrypt the :bsontype:`BinData <Binary>` value using the decrypted
    data encryption key and appropriate algorithm.

source/includes/extracts-client-side-field-level-encryption.yaml

@@ -8,16 +8,22 @@ content: |
     
   - Use the :method:`Mongo()` constructor from the :binary:`~bin.mongo`
     shell to establish a connection with the required client-side field
-    level encryption options. The :method:`Mongo()` method supports both
-    Amazon Web Services and Local Key Management Service (KMS) providers
-    for Customer Master Key (CMK) management.
+    level encryption options. The :method:`Mongo()` method supports the
+    following Key Management Service (KMS) providers for Customer
+    Master Key (CMK) management:
+
+    - :ref:`Amazon Web Services KMS <field-level-encryption-aws-kms>`
+    - :ref:`Azure Key Vault <field-level-encryption-azure-keyvault>`
+    - :ref:`Google Cloud Platform KMS <field-level-encryption-gcp-kms>`
+    - :ref:`Locally Managed Key <field-level-encryption-local-kms>`
 
     *or*
 
-  - Use the ``mongo`` shell :ref:`command line options
+  - Use the :binary:`~bin.mongo` shell :ref:`command line options
     <mongo-client-side-field-level-encryption-options>` to establish a
     connection with the required options. The command line options only
-    support the AWS KMS provider for CMK management. 
+    support the :ref:`Amazon Web Services KMS
+    <field-level-encryption-aws-kms>` provider for CMK management. 
 ---
 ref: csfle-keyvault-unique-index
 content: |

source/includes/fact-createkey-returns-uuid.rst

@@ -0,0 +1,24 @@
+If successful, :method:`~KeyVault.createKey()` returns the
+:abbr:`UUID (Universally unique identifier)` of the new data encryption
+key. The ``UUID`` is a BSON :bsontype:`Binary (BinData) <Binary>` object
+with subtype ``4`` that uniquely identifies the data encryption key.
+The ``UUID`` string is the hexadecimal representation of the
+underlying binary data.
+
+If you are providing the data encryption key to an official 4.2+
+compatible driver in order to configure
+:ref:`automatic client-side field level encryption
+<field-level-encryption-json-schema>`, you must use the ``base64``
+representation of the ``UUID`` string.
+
+You can run the following operation in the :binary:`~bin.mongo`
+shell to convert a ``UUID`` hexadecimal string to its ``base64``
+representation:
+
+.. code-block:: javascript
+
+   UUID("b4b41b33-5c97-412e-a02b-743498346079").base64()
+
+Supply the ``UUID`` of your own data encryption key to this command, as
+returned from :method:`~KeyVault.createKey()` above, or as described in
+:ref:`field-level-encryption-data-key-retrieve`.