Merge v4.4.5 into master

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

@@ -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:
 
@@ -51,28 +53,25 @@ 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*
+  <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>`__ 
 
-.. admonition:: Implement Seperation of Least Privilege for KMS Access
-   :class: note
+- ``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. 
@@ -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:
 
@@ -127,29 +209,30 @@ The :binary:`~bin.mongo` shell provides helper methods for data
 encryption key management:
 
 .. list-table::
-   :widths: 40 40
+   :header-rows: 1
+   :widths: 60 40
+
+   * - Use Case
+     - Helper Methods
 
    * - Retrieving data encryption keys
-     -
-       - :method:`KeyVault.getKey()`
-       - :method:`KeyVault.getKeys()`
-       - :method:`KeyVault.getKeyByAltName()`
+     - | :method:`KeyVault.getKey()`
+       | :method:`KeyVault.getKeys()`
+       | :method:`KeyVault.getKeyByAltName()`
 
    * - Creating or Modifying data encryption keys
-     -
-      - :method:`KeyVault.createKey()`
-      - :method:`KeyVault.addKeyAlternateName()`
-      - :method:`KeyVault.removeKeyAlternateName()`
+     - | :method:`KeyVault.createKey()`
+       | :method:`KeyVault.addKeyAlternateName()`
+       | :method:`KeyVault.removeKeyAlternateName()`
 
    * - Removing data encryption keys
-
+     - :method:`KeyVault.deleteKey()`
+
        .. important::
 
           Removing a data encryption key renders all fields encrypted
           using that data encryption key as permanently unreadable.
 
-     - 
-      - :method:`KeyVault.deleteKey()`
 
 Applications with :authrole:`read` access to the key vault collection
 can retrieve data encryption keys by querying the collection. However,
@@ -162,7 +245,7 @@ vault. Applications must have access to both the remote key vault
 cluster and the connection cluster to perform client-side field level
 encryption operations.
 
-data encryption keys have the following structure:
+Data encryption keys have the following structure:
 
 .. code-block:: json
 

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`.