diff --git a/source/core/security-client-side-encryption-key-management.txt b/source/core/security-client-side-encryption-key-management.txt index 9ca1e5c7fa6..9c39efc9187 100644 --- a/source/core/security-client-side-encryption-key-management.txt +++ b/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 ` -- :ref:`Locally Managed Keyfile ` +- :ref:`Azure Key Vault ` +- :ref:`Google Cloud Platform KMS ` +- :ref:`Locally Managed Key ` .. _field-level-encryption-aws-kms: @@ -51,27 +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 - `, - - *or* + `, or - Use the :method:`Mongo()` constructor to create a database connection with the required AWS :ref:`KMS configuration options `. -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) - `__ +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) `__ -.. admonition:: Implement Seperation of Least Privilege for KMS Access +- ``kms:Decrypt`` + `(reference) + `__ + +.. admonition:: Implement Principle of Least Privilege for KMS Access :class: note Consider configuring IAM user roles such that MongoDB has only the @@ -97,8 +97,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 +`__ 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 +`. + +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) + `__ + +- ``unwrap key`` + `(reference) + `__ + +.. 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 `__ 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 +`. + +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 +`__ +or can be included in a +`Google Cloud custom role +`__. + +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 +193,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: diff --git a/source/core/security-client-side-encryption.txt b/source/core/security-client-side-encryption.txt index 8ba3dda7b07..675834fd68d 100644 --- a/source/core/security-client-side-encryption.txt +++ b/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 ` 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) ` + stores the Customer Master Key (CMK) used to encrypt data encryption + keys. MongoDB supports the following KMS providers: + + - :ref:`Amazon Web Services KMS ` + - :ref:`Azure Key Vault ` + - :ref:`Google Cloud Platform KMS ` + - :ref:`Locally Managed Key ` - 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 ` 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 ` subtype 6 objects. The automatic +decryption process works as follows: 1. Check the :bsontype:`BinData ` 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 + `, :ref:`Azure Key Vault + `, or + :ref:`Google Cloud Platform 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 + `, 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 ` value using the decrypted data encryption key and appropriate algorithm. diff --git a/source/includes/extracts-client-side-field-level-encryption.yaml b/source/includes/extracts-client-side-field-level-encryption.yaml index cb00deb2ee7..3e8959a1fc5 100644 --- a/source/includes/extracts-client-side-field-level-encryption.yaml +++ b/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 ` + - :ref:`Azure Key Vault ` + - :ref:`Google Cloud Platform KMS ` + - :ref:`Locally Managed Key ` *or* - - Use the ``mongo`` shell :ref:`command line options + - Use the :binary:`~bin.mongo` shell :ref:`command line 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 + ` provider for CMK management. --- ref: csfle-keyvault-unique-index content: | diff --git a/source/includes/fact-createkey-returns-uuid.rst b/source/includes/fact-createkey-returns-uuid.rst new file mode 100644 index 00000000000..7925e7df001 --- /dev/null +++ b/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) ` 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 +`, 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`. diff --git a/source/includes/steps-csfle-shell-aws-create-key.yaml b/source/includes/steps-csfle-shell-aws-create-key.yaml new file mode 100644 index 00000000000..3f087351235 --- /dev/null +++ b/source/includes/steps-csfle-shell-aws-create-key.yaml @@ -0,0 +1,154 @@ +--- +title: "Launch the ``mongo`` Shell." +ref: launch-mongo-shell +level: 4 +content: | + + Configuring client-side field level encryption for the AWS KMS + requires an AWS Access Key ID and its associated Secret Access Key. + The AWS Access Key must correspond to an IAM user with all *List* and + *Read* permissions for the KMS service. + + To mitigate the risk of these credentials leaking into logs, the + following procedure passes the values into the :binary:`~bin.mongo` + shell using environment variables. + + First, ensure that you have configured the following environment + variables according to your platform's documentation: + + - ``AWS_ACCESS_KEY_ID`` + - ``AWS_SECRET_ACCESS_KEY`` + + Next, create a :binary:`~bin.mongo` shell session using the + :option:`--eval `, :option:`--shell `, + and :option:`--nodb ` options: + + .. code-block:: shell + + mongo --eval " + var AWS_ACCESS_KEY_ID = '$AWS_ACCESS_KEY_ID' + var AWS_SECRET_ACCESS_KEY = '$AWS_SECRET_ACCESS_KEY' + " \ + --shell --nodb + + This example opens the :binary:`~bin.mongo` shell without a + connection to a MongoDB database. The ``--eval`` option sets the + ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY`` variables in the + :binary:`~bin.mongo` shell to the value of the corresponding + environment variables. The specified variables are also supported by + the `AWS CLI + `__. + +--- +title: "Create the Encryption Configuration." +ref: create-encryption-configuration +level: 4 +content: | + + In the :binary:`~bin.mongo` shell, create a new + :ref:`ClientSideFieldLevelEncryptionOptions` variable for storing the + client-side field level encryption configuration document: + + .. code-block:: javascript + + var ClientSideFieldLevelEncryptionOptions = { + "keyVaultNamespace" : "encryption.__dataKeys", + "kmsProviders" : { + "aws" : { + "accessKeyId" : AWS_ACCESS_KEY_ID, + "secretAccessKey" : AWS_SECRET_ACCESS_KEY + } + } + } + +--- +title: "Connect with Encryption Support." +ref: connect-with-encryption +level: 4 +content: | + + In the :binary:`~bin.mongo` shell, use the :method:`Mongo()` + constructor to establish a database connection to the target cluster. + Specify the :ref:`ClientSideFieldLevelEncryptionOptions` document as + the second parameter to the :method:`Mongo()` constructor to + configure the connection for client-side field level encryption: + + .. code-block:: javascript + + csfleDatabaseConnection = Mongo( + "mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster", + ClientSideFieldLevelEncryptionOptions + ) + + Replace the ``replaceMe.example.net`` :ref:`URI ` with + the connection string for the target cluster. + + Use the ``csfleDatabaseConnection`` object to access + :doc:`client-side field level encryption + ` shell + methods. + + For complete documentation on establishing database connections + configured for client-side field level encryption, see the + :method:`Mongo()` constructor reference. + +--- +title: "Create the Key Vault Object." +ref: create-keyvault-object +level: 4 +content: | + + Use the :method:`getKeyVault()` method on the + ``csfleDatabaseConnection`` database connection object to create the + ``keyVault`` object: + + .. code-block:: javascript + + keyVault = csfleDatabaseConnection.getKeyVault(); + + .. important:: + + Client-side field level encryption depends on server-enforced + uniqueness of key alternate names. :method:`getKeyVault()` + creates a :ref:`unique index ` on + ``keyAltNames`` if one does not exist. Do **not** drop the + :ref:`unique index ` created by + :method:`getKeyVault()`. + +--- +title: "Create the Data Encryption Key." +ref: create-encryption-key +level: 4 +content: | + + Use the :method:`KeyVault.createKey()` method on the ``keyVault`` + object to create a new data encryption key in the key vault: + + .. code-block:: javascript + + keyVault.createKey( + "aws", + "arn:aws:kms:region:account:key/keystring", + [ "keyAlternateName" ] + ) + + Where: + + - The first parameter *must* be ``"aws"`` to specify the configured + Amazon Web Services KMS. + + - The second parameter *must* be the full `Amazon Resource Name (ARN) + `__ + of the Customer Master Key (CMK). MongoDB uses the + specified CMK to encrypt the data encryption key. + + - The third parameter *may* be an array of one or more + ``keyAltNames`` for the data encryption key. Each key alternate + name *must* be unique. :method:`getKeyVault()` creates a + :ref:`unique index ` on ``keyAltNames`` to + enforce uniqueness on the field if one does not already exist. Key + alternate names facilitate data encryption key findability. + + .. include:: /includes/fact-createkey-returns-uuid.rst + +... diff --git a/source/includes/steps-csfle-shell-aws-delete-key.yaml b/source/includes/steps-csfle-shell-aws-delete-key.yaml new file mode 100644 index 00000000000..b9ac86665cb --- /dev/null +++ b/source/includes/steps-csfle-shell-aws-delete-key.yaml @@ -0,0 +1,45 @@ +level: 4 +ref: launch-mongo-shell +title: "Launch the ``mongo`` Shell." +stepnum: 1 +source: + file: steps-csfle-shell-aws-create-key.yaml + ref: launch-mongo-shell +--- +level: 4 +ref: create-encryption-configuration +title: "Create the Encryption Configuration." +stepnum: 2 +source: + file: steps-csfle-shell-aws-create-key.yaml + ref: create-encryption-configuration +--- +level: 4 +ref: connect-with-encryption +title: "Connect with Encryption Support." +stepnum: 3 +source: + file: steps-csfle-shell-aws-create-key.yaml + ref: connect-with-encryption +--- +level: 4 +ref: create-keyvault-object +title: "Create the Key Vault Object." +stepnum: 4 +source: + file: steps-csfle-shell-aws-create-key.yaml + ref: create-keyvault-object +--- +level: 4 +ref: delete-data-key +title: "Delete the Data Encryption Key Using its ``UUID``." +content: | + + Use the :method:`KeyVault.deleteKey()` method on the ``keyVault`` + object to delete a data key from the key vault: + + .. code-block:: javascript + + keyVault.deleteKey(UUID("`, :option:`--shell `, + and :option:`--nodb ` options: + + .. code-block:: shell + + mongo --eval " + var AZURE_TENANT_ID = '$AZURE_TENANT_ID' + var AZURE_CLIENT_ID = '$AZURE_CLIENT_ID' + var AZURE_CLIENT_SECRET = '$AZURE_CLIENT_SECRET' + " \ + --shell --nodb + + This example opens the :binary:`~bin.mongo` shell without a + connection to a MongoDB database. The ``--eval`` option sets the + ``AZURE_TENANT_ID``, and ``AZURE_CLIENT_ID``, and + ``AZURE_CLIENT_SECRET`` variables in the :binary:`~bin.mongo` shell to + the value of the corresponding environment variables. + +--- +title: "Create the Encryption Configuration." +ref: create-encryption-configuration +level: 4 +content: | + + In the :binary:`~bin.mongo` shell, create a new + :ref:`ClientSideFieldLevelEncryptionOptions` variable for storing the + client-side field level encryption configuration document: + + .. code-block:: javascript + + var ClientSideFieldLevelEncryptionOptions = { + "keyVaultNamespace" : "encryption.__dataKeys", + "kmsProviders" : { + "azure" : { + "tenantId" : AZURE_TENANT_ID, + "clientId" : AZURE_CLIENT_ID, + "clientSecret" : AZURE_CLIENT_SECRET + } + } + } + +--- +title: "Connect with Encryption Support." +ref: connect-with-encryption +level: 4 +content: | + + In the :binary:`~bin.mongo` shell, use the :method:`Mongo()` + constructor to establish a database connection to the target cluster. + Specify the :ref:`ClientSideFieldLevelEncryptionOptions` document as + the second parameter to the :method:`Mongo()` constructor to + configure the connection for client-side field level encryption: + + .. code-block:: javascript + + csfleDatabaseConnection = Mongo( + "mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster", + ClientSideFieldLevelEncryptionOptions + ) + + Replace the ``replaceMe.example.net`` :ref:`URI ` with + the connection string for the target cluster. + + Use the ``csfleDatabaseConnection`` object to access + :doc:`client-side field level encryption + ` shell + methods. + + For complete documentation on establishing database connections + configured for client-side field level encryption, see the + :method:`Mongo()` constructor reference. + +--- +title: "Create the Key Vault Object." +ref: create-keyvault-object +level: 4 +content: | + + Use the :method:`getKeyVault()` method on the + ``csfleDatabaseConnection`` database connection object to create the + ``keyVault`` object: + + .. code-block:: javascript + + keyVault = csfleDatabaseConnection.getKeyVault(); + + .. important:: + + Client-side field level encryption depends on server-enforced + uniqueness of key alternate names. :method:`getKeyVault()` + creates a :ref:`unique index ` on + ``keyAltNames`` if one does not exist. Do **not** drop the + :ref:`unique index ` created by + :method:`getKeyVault()`. + +--- +title: "Create the Data Encryption Key." +ref: create-encryption-key +level: 4 +content: | + + Use the :method:`KeyVault.createKey()` method on the ``keyVault`` + object to create a new data encryption key in the key vault: + + .. code-block:: javascript + + keyVault.createKey( + "azure", + { keyName: "keyvaultname", keyVaultEndpoint: "endpointname" }, + [ "keyAlternateName" ] + ) + + Where: + + - The first parameter *must* be ``"azure"`` to specify the configured + Azure Key Vault. + + - The second parameter *must* be a document containing: + + - the name of your `Azure Key Vault + `__ + - the DNS name of the Azure Key Vault to use (e.g. + ``my-key-vault.vault.azure.net``) + + - The third parameter *may* be an array of one or more + ``keyAltNames`` for the data encryption key. Each key alternate + name *must* be unique. :method:`getKeyVault()` creates a + :ref:`unique index ` on ``keyAltNames`` to + enforce uniqueness on the field if one does not already exist. Key + alternate names facilitate data encryption key findability. + + .. include:: /includes/fact-createkey-returns-uuid.rst + +... diff --git a/source/includes/steps-csfle-shell-azure-delete-key.yaml b/source/includes/steps-csfle-shell-azure-delete-key.yaml new file mode 100644 index 00000000000..be54c1b27f8 --- /dev/null +++ b/source/includes/steps-csfle-shell-azure-delete-key.yaml @@ -0,0 +1,45 @@ +level: 4 +ref: launch-mongo-shell +title: "Launch the ``mongo`` Shell." +stepnum: 1 +source: + file: steps-csfle-shell-azure-create-key.yaml + ref: launch-mongo-shell +--- +level: 4 +ref: create-encryption-configuration +title: "Create the Encryption Configuration." +stepnum: 2 +source: + file: steps-csfle-shell-azure-create-key.yaml + ref: create-encryption-configuration +--- +level: 4 +ref: connect-with-encryption +title: "Connect with Encryption Support." +stepnum: 3 +source: + file: steps-csfle-shell-azure-create-key.yaml + ref: connect-with-encryption +--- +level: 4 +ref: create-keyvault-object +title: "Create the Key Vault Object." +stepnum: 4 +source: + file: steps-csfle-shell-azure-create-key.yaml + ref: create-keyvault-object +--- +level: 4 +ref: delete-data-key +title: "Delete the Data Encryption Key Using its ``UUID``." +content: | + + Use the :method:`KeyVault.deleteKey()` method on the ``keyVault`` + object to delete a data key from the key vault: + + .. code-block:: javascript + + keyVault.deleteKey(UUID("` it prior to adding + any key alternate names. + + Use the :method:`KeyVault.addKeyAlternateName()` to add a new + alternate name to a data encryption key: + + .. code-block:: javascript + + keyVault.addKeyAlternateName( + UUID("`, :option:`--shell `, + and :option:`--nodb ` options: + + .. code-block:: shell + + mongo --eval " + var GCP_EMAIL = '$GCP_EMAIL' + var GCP_PRIVATEKEY = '$GCP_PRIVATEKEY' + " \ + --shell --nodb + + This example opens the :binary:`~bin.mongo` shell without a + connection to a MongoDB database. The ``--eval`` option sets the + ``GCP_EMAIL`` and ``GCP_PRIVATEKEY`` variables in the + :binary:`~bin.mongo` shell to the value of the corresponding + environment variables. + +--- +title: "Create the Encryption Configuration." +ref: create-encryption-configuration +level: 4 +content: | + + In the :binary:`~bin.mongo` shell, create a new + :ref:`ClientSideFieldLevelEncryptionOptions` variable for storing the + client-side field level encryption configuration document: + + .. code-block:: javascript + + var ClientSideFieldLevelEncryptionOptions = { + "keyVaultNamespace" : "encryption.__dataKeys", + "kmsProviders" : { + "gcp" : { + "email" : GCP_EMAIL, + "privateKey" : GCP_PRIVATEKEY + } + } + } + +--- +title: "Connect with Encryption Support." +ref: connect-with-encryption +level: 4 +content: | + + In the :binary:`~bin.mongo` shell, use the :method:`Mongo()` + constructor to establish a database connection to the target cluster. + Specify the :ref:`ClientSideFieldLevelEncryptionOptions` document as + the second parameter to the :method:`Mongo()` constructor to + configure the connection for client-side field level encryption: + + .. code-block:: javascript + + csfleDatabaseConnection = Mongo( + "mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster", + ClientSideFieldLevelEncryptionOptions + ) + + Replace the ``replaceMe.example.net`` :ref:`URI ` with + the connection string for the target cluster. + + Use the ``csfleDatabaseConnection`` object to access + :doc:`client-side field level encryption + ` shell + methods. + + For complete documentation on establishing database connections + configured for client-side field level encryption, see the + :method:`Mongo()` constructor reference. + +--- +title: "Create the Key Vault Object." +ref: create-keyvault-object +level: 4 +content: | + + Use the :method:`getKeyVault()` method on the + ``csfleDatabaseConnection`` database connection object to create the + ``keyVault`` object: + + .. code-block:: javascript + + keyVault = csfleDatabaseConnection.getKeyVault(); + + .. important:: + + Client-side field level encryption depends on server-enforced + uniqueness of key alternate names. :method:`getKeyVault()` + creates a :ref:`unique index ` on + ``keyAltNames`` if one does not exist. Do **not** drop the + :ref:`unique index ` created by + :method:`getKeyVault()`. + +--- +title: "Create the Data Encryption Key." +ref: create-encryption-key +level: 4 +content: | + + Use the :method:`KeyVault.createKey()` method on the ``keyVault`` + object to create a new data encryption key in the key vault: + + .. code-block:: javascript + + keyVault.createKey( + "gcp", + { + projectId: "projectid", + location: "locationname", + keyRing: "keyringname", + keyName: "keyname" + }, + [ "keyAlternateName" ] + ) + + Where: + + - The first parameter *must* be ``"gcp"`` to specify the configured + Google Cloud KMS. + + - The second parameter *must* be a document containing + + - ``projectid`` is the name of your GCP project, such as + ``my-project`` + - ``locationname`` is the location of the KMS keyring, such as + ``global`` + - ``keyringname`` is the name of the KMS keyring, such as + ``my-keyring`` + - ``keyname`` is the name of your key. + + - The third parameter *may* be an array of one or more + ``keyAltNames`` for the data encryption key. Each key alternate + name *must* be unique. :method:`getKeyVault()` creates a + :ref:`unique index ` on ``keyAltNames`` to + enforce uniqueness on the field if one does not already exist. Key + alternate names facilitate data encryption key findability. + + .. include:: /includes/fact-createkey-returns-uuid.rst + +... diff --git a/source/includes/steps-csfle-shell-gcp-delete-key.yaml b/source/includes/steps-csfle-shell-gcp-delete-key.yaml new file mode 100644 index 00000000000..8a43f336c36 --- /dev/null +++ b/source/includes/steps-csfle-shell-gcp-delete-key.yaml @@ -0,0 +1,45 @@ +level: 4 +ref: launch-mongo-shell +title: "Launch the ``mongo`` Shell." +stepnum: 1 +source: + file: steps-csfle-shell-gcp-create-key.yaml + ref: launch-mongo-shell +--- +level: 4 +ref: create-encryption-configuration +title: "Create the Encryption Configuration." +stepnum: 2 +source: + file: steps-csfle-shell-gcp-create-key.yaml + ref: create-encryption-configuration +--- +level: 4 +ref: connect-with-encryption +title: "Connect with Encryption Support." +stepnum: 3 +source: + file: steps-csfle-shell-gcp-create-key.yaml + ref: connect-with-encryption +--- +level: 4 +ref: create-keyvault-object +title: "Create the Key Vault Object." +stepnum: 4 +source: + file: steps-csfle-shell-gcp-create-key.yaml + ref: create-keyvault-object +--- +level: 4 +ref: delete-data-key +title: "Delete the Data Encryption Key Using its ``UUID``." +content: | + + Use the :method:`KeyVault.deleteKey()` method on the ``keyVault`` + object to delete a data key from the key vault: + + .. code-block:: javascript + + keyVault.deleteKey(UUID("` it prior to adding + any key alternate names. + + Use the :method:`KeyVault.addKeyAlternateName()` to add a new + alternate name to a data encryption key: + + .. code-block:: javascript + + keyVault.addKeyAlternateName( + UUID("> ~/.profile + + The host operating system may require logging out and back in to + refresh the loaded environment variables. Alternatively, you can use + the command ``source ~/.profile`` to manually refresh the shell. + + .. note:: + + Your specific host operating system or shell may have different + procedures for setting persistent environment variables. Defer to + the documentation for your host OS or shell for a more specific + procedure as appropriate. + +--- +title: "Launch the ``mongo`` Shell." +ref: launch-mongo-shell +level: 4 +content: | + + Create a :binary:`~bin.mongo` shell session using the :option:`--eval + `, :option:`--shell `, and + :option:`--nodb ` options: + + .. code-block:: shell + + mongo --eval "var LOCAL_KEY = '$DEV_LOCAL_KEY' " \ + --shell --nodb + + The example automatically opens a :binary:`~bin.mongo` shell + without a connection to a MongoDB database. The ``--eval`` + option sets the ``LOCAL_KEY`` variable in the :binary:`~bin.mongo` + shell to the value of the corresponding environment variable. + +--- +title: "Create the Encryption Configuration." +ref: create-encryption-configuration +level: 4 +content: | + + In the :binary:`~bin.mongo` shell, create a new + :ref:`ClientSideFieldLevelEncryptionOptions` variable for storing the + client-side field level encryption configuration document: + + .. code-block:: javascript + + var ClientSideFieldLevelEncryptionOptions = { + "keyVaultNamespace" : "encryption.__dataKeys", + "kmsProviders" : { + "local" : { + "key" : BinData(0, LOCAL_KEY) + } + } + } + +--- +title: "Connect with Encryption Support." +ref: connect-with-encryption +level: 4 +content: | + + In the :binary:`~bin.mongo` shell, use the :method:`Mongo()` + constructor to establish a database connection to the target cluster. + Specify the :ref:`ClientSideFieldLevelEncryptionOptions` document as + the second parameter to the :method:`Mongo()` constructor to + configure the connection for client-side field level encryption: + + .. code-block:: javascript + + csfleDatabaseConnection = Mongo( + "mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster", + ClientSideFieldLevelEncryptionOptions + ) + + Replace the ``replaceMe.example.net`` :ref:`URI ` with + the connection string for the target cluster. + + Use the ``csfleDatabaseConnection`` object to access + :doc:`client-side field level encryption + ` shell + methods. + + For complete documentation on establishing database connections + configured for client-side field level encryption, see the + :method:`Mongo()` constructor reference. + +--- +title: "Create the Key Vault Object." +ref: create-keyvault-object +level: 4 +content: | + + Use the :method:`getKeyVault()` method on the + ``csfleDatabaseConnection`` database connection object to create the + ``keyVault`` object: + + .. code-block:: javascript + + keyVault = csfleDatabaseConnection.getKeyVault(); + + .. important:: + + Client-side field level encryption depends on server-enforced + uniqueness of key alternate names. :method:`getKeyVault()` + creates a :ref:`unique index ` on + ``keyAltNames`` if one does not exist. Do **not** drop the + :ref:`unique index ` created by + :method:`getKeyVault()`. + +--- +title: "Create the Data Encryption Key." +ref: create-encryption-key +level: 4 +content: | + + Use the :method:`KeyVault.createKey()` method on the ``keyVault`` + object to create a new data encryption key in the key vault: + + .. code-block:: javascript + + keyVault.createKey( + "local", + [ "keyAlternateName" ] + ) + + Where: + + - The first parameter *must* be ``local`` to specify the configured + locally managed key. + + - The second parameter *may* be an array of one or more + ``keyAltNames`` for the data encryption key. Each key alternate + name *must* be unique. :method:`getKeyVault()` creates a unique + index on ``keyAltNames`` to enforce uniqueness on the field if + one does not already exist. Key alternate names facilitate data + encryption key findability. + + .. note:: + + Prior to MongoDB 4.2.3, creating a local key required + specifying an empty string ``""`` as the second parameter and + the optional array of ``keyAltNames`` as the third parameter. + + .. include:: /includes/fact-createkey-returns-uuid.rst + +... diff --git a/source/includes/steps-csfle-shell-local-delete-key.yaml b/source/includes/steps-csfle-shell-local-delete-key.yaml new file mode 100644 index 00000000000..77ae98b4de4 --- /dev/null +++ b/source/includes/steps-csfle-shell-local-delete-key.yaml @@ -0,0 +1,53 @@ +level: 4 +ref: generate-encryption-key +title: "Generate an Encryption Key." +stepnum: 1 +source: + file: steps-csfle-shell-local-create-key.yaml + ref: generate-encryption-key +--- +level: 4 +ref: launch-mongo-shell +title: "Launch the ``mongo`` Shell." +stepnum: 2 +source: + file: steps-csfle-shell-local-create-key.yaml + ref: launch-mongo-shell +--- +level: 4 +ref: create-encryption-configuration +title: "Create the Encryption Configuration." +stepnum: 3 +source: + file: steps-csfle-shell-local-create-key.yaml + ref: create-encryption-configuration +--- +level: 4 +ref: connect-with-encryption +title: "Connect with Encryption Support." +stepnum: 4 +source: + file: steps-csfle-shell-local-create-key.yaml + ref: connect-with-encryption +--- +level: 4 +ref: create-keyvault-object +title: "Create the Key Vault Object." +stepnum: 5 +source: + file: steps-csfle-shell-local-create-key.yaml + ref: create-keyvault-object +--- +level: 4 +ref: delete-data-key +title: "Delete the Data Encryption Key Using its ``UUID``." +content: | + + Use the :method:`KeyVault.deleteKey()` method on the ``keyVault`` + object to delete a data key from the key vault: + + .. code-block:: javascript + + keyVault.deleteKey(UUID("` it prior to adding + any key alternate names. + + Use the :method:`KeyVault.addKeyAlternateName()` to add a new + alternate name to a data encryption key: + + .. code-block:: javascript + + keyVault.addKeyAlternateName( + UUID("`, - :option:`--shell `, and - :option:`--nodb ` options: - - .. code-block:: shell - - mongo --eval " - var AWS_ACCESS_KEY_ID = '$AWS_ACCESS_KEY_ID' - var AWS_SECRET_ACCESS_KEY = '$AWS_SECRET_ACCESS_KEY' - " \ - --shell --nodb - - The example automatically opens a :binary:`~bin.mongo` - shell without a connection to a MongoDB database. The - ``--eval`` option set the ``AWS_ACCESS_KEY_ID`` and - ``AWS_SECRET_ACCESS_KEY`` variables in the shell to the value - of the corresponding environment variable. The specified - variables are also supported by the - `AWS CLI `__. - - Create a new variable for storing the client-side field level - encryption configuration document: - - .. code-block:: javascript - - var ClientSideFieldLevelEncryptionOptions = { - "keyVaultNamespace" : "encryption.__dataKeys", - "kmsProviders" : { - "aws" : { - "accessKeyId" : AWS_ACCESS_KEY_ID, - "secretAccessKey" : AWS_SECRET_ACCESS_KEY - } - } - } - - .. tab:: Locally Managed Keyfile - :tabid: local - - Configuring client-side field level encryption for a locally - managed key requires specifying a base64-encoded 96-byte string - with no line breaks. To mitigate the risk of the key leaking - into logs, this procedure passes the value into the ``mongo`` - shell using an environment variable. - - The following operation generates a key that meets the - stated requirements and adds it to the users - ``~/.profile``. If the key ``DEV_LOCAL_KEY`` already exists, - skip this operation. - - .. code-block:: shell - - echo "export DEV_LOCAL_KEY=\"$(head -c 96 /dev/urandom | base64 | tr -d '\n')\"" >> ~/.profile - - The host operating system may require logging out and in - to refresh the loaded environment variables. Alternatively, - use ``source ~/.profile`` to manually refresh the shell. - - .. note:: - - The host operating system or shell may have different - procedures for setting persistent environment variables. - Defer to the documentation for the host OS or shell for - a more specific procedure. - - Create a :binary:`~bin.mongo` shell session using the - :option:`--eval `, - :option:`--shell ` and - :option:`--nodb ` options. - - .. code-block:: shell - - mongo --eval "var LOCAL_KEY = '$DEV_LOCAL_KEY' " \ - --shell --nodb - - The example automatically opens a :binary:`~bin.mongo` shell - without a connection to a MongoDB database. The ``--eval`` - option set the ``LOCAL_KEY`` variable in the ``mongo`` shell to - the value of the corresponding environment variable. - - Create a new variable in the ``mongo`` shell for storing the - client-side field level encryption configuration document: - - .. code-block:: javascript - - var ClientSideFieldLevelEncryptionOptions = { - "keyVaultNamespace" : "encryption.__dataKeys", - "kmsProviders" : { - "local" : { - "key" : BinData(0, LOCAL_KEY) - } - } - } - - Use the :method:`Mongo()` constructor in the ``mongo`` shell to - establish a database connection to the target cluster. Configure the - connection for client-side field level encryption by specifying the - ``ClientSideFieldLevelEncryption`` document as the second parameter: - - .. code-block:: javascript - - csfleDatabaseConnection = Mongo( - "mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster", - ClientSideFieldLevelEncryptionOptions - ) - - Replace the ``replaceMe.example.net`` :ref:`URI ` with - the connection string for the target cluster. - - Use the ``csfleDatabaseConnection`` object to access - :doc:`client-side field level encryption - ` shell - methods. - - For complete documentation on establishing database connections - configured for client-side field level encryption, see the - :method:`Mongo()` constructor reference. - ---- -level: 4 -ref: create-key-vault -title: "Create the key vault object." -content: | - - Use the :method:`getKeyVault()` method on the - ``csfleDatabaseConnection`` database connection object to create the - key vault object: - - .. code-block:: javascript - - keyVault = csfleDatabaseConnection.getKeyVault(); - - .. important:: - - Client-side field level encryption depends on server-enforced - uniqueness of key alternate names. :method:`getKeyVault()` - creates a :ref:`unique ` index on - ``keyAltNames`` if one does not exist. Do **not** drop the - :ref:`unique ` index created by - :method:`getKeyVault()`. - ---- -level: 4 -ref: create-data-key -title: "Create the data encryption key." -content: | - - Use the :method:`KeyVault.createKey()` method on the ``keyVault`` - object to create a new data encryption key in the key vault. - - .. tabs:: - - .. tab:: Amazon Web Services KMS - :tabid: aws - - .. code-block:: javascript - - keyVault.createKey( - "aws", - "arn:aws:kms:region:account:key/keystring", - [ "keyAlternateName" ] - ) - - The first parameter *must* be ``"aws"`` to specify the configured - Amazon Web Services KMS. - - The second parameter *must* be the full Amazon Resource Name - (ARN) of the Customer Master Key (CMK). MongoDB uses the - specified CMK to encrypt the data encryption key. - - The third parameter *may* be an array of one or more - ``keyAltNames`` for the data encryption key. Each key alternate - name *must* be unique. :method:`getKeyVault()` creates a unique - index on ``keyAltNames`` to enforce uniqueness on the field if - one does not already exist. Key alternate names facilitate data - encryption key findability. - - .. tab:: Locally Managed Key - :tabid: local - - .. code-block:: javascript - - keyVault.createKey( - "local", - [ "myFirstCSFLEDataKey" ] - ) - - The first parameter *must* be ``local`` to specify the - configured Locally Managed Key. - - The second parameter *may* be an array of one or more - ``keyAltNames`` for the data encryption key. Each key alternate - name *must* be unique. :method:`getKeyVault()` creates a unique - index on ``keyAltNames`` to enforce uniqueness on the field if - one does not already exist. Key alternate names facilitate data - encryption key findability. - - .. versionchanged:: 4.2.3 - - Prior to MongoDB 4.2.3, creating a local key required - specifying an empty string ``""`` as the second parameter and - the optional array of ``keyAltNames`` as the third parameter. - - If successful, :method:`~KeyVault.createKey()` returns the ``UUID`` of - the new data encryption key. The :abbr:`UUID (Universally unique - identifier)` is a BSON :bsontype:`Binary (BinData) ` object - with subtype ``4`` that uniquely identifies the data encryption key. - The ``UUID`` string is the hexadecimal representation of the - underlying binary data. - - Configuring official 4.2-compatible drivers for :ref:`automatic - client-side field level encryption - ` requires specifying the data - encryption key using the ``base64`` representation of the UUID string. - The following operation converts the ``UUID`` hexadecimal string to - its ``base64`` representation: - - .. code-block:: javascript - - UUID("b4b41b33-5c97-412e-a02b-743498346079").base64() - -... \ No newline at end of file diff --git a/source/includes/steps-manage-client-side-encryption-delete-key.yaml b/source/includes/steps-manage-client-side-encryption-delete-key.yaml deleted file mode 100644 index 5d803790d72..00000000000 --- a/source/includes/steps-manage-client-side-encryption-delete-key.yaml +++ /dev/null @@ -1,30 +0,0 @@ -level: 4 -ref: create-database-object -title: "Create the database connection." -stepnum: 1 -source: - file: steps-manage-client-side-encryption-create-key.yaml - ref: create-database-object ---- -level: 4 -ref: create-key-vault -title: "Create the key vault object." -stepnum: 2 -source: - file: steps-manage-client-side-encryption-create-key.yaml - ref: create-key-vault ---- -level: 4 -ref: delete-data-key -title: "Delete the data encryption key using its ``UUID``." -content: | - - Use the :method:`KeyVault.deleteKey()` method on the ``keyVault`` - object to delete a data key from the key vault: - - .. code-block:: javascript - - keyVault.deleteKey(UUID("` to use for retrieving the + Customer Master Key (CMK). Accepts the following parameters: - Specify ``aws`` for :ref:`Amazon Web Service KMS - `. Requires specifying a - Customer Master Key (CMK) to ``customerMasterKey``. + - ``aws`` for :ref:`Amazon Web Services KMS + `. Requires specifying a + Customer Master Key (CMK) string for ``customerMasterKey``. - Specify ``local`` for a - :ref:`locally managed key `. + - ``azure`` for :ref:`Azure Key Vault + `. Requires + specifying a Customer Master Key (CMK) document for + ``customerMasterKey``. + + .. versionadded:: 4.4.5 + + - ``gcp`` for :ref:`Google Cloud Platform KMS + `. Requires specifying a + Customer Master Key (CMK) document for + ``customerMasterKey``. + + .. versionadded:: 4.4.5 + + - ``local`` for a :ref:`locally managed key + `. If the :method:`database connection ` was not - configured with the specified KMS, data encryption key creation fails. + configured with the specified KMS, data encryption key + creation fails. * - ``customerMasterKey`` - - string - - - The identifier for the Customer Master Key (CMK) to use for - encrypting the data encryption key. Required if - ``keyManagementService`` is ``aws``. - - Specify the full `Amazon Resource Name (ARN) - `__ - of the master key. :method:`~KeyVault.createKey()` requests - the AWS KMS encrypt the data encryption key material with the - specified CMK. If the CMK does not exist *or* if the KMS - configuration does not provide access to that CMK, + - string or document + + - The Customer Master Key (CMK) to use for encrypting the data + encryption key. Required if ``keyManagementService`` is + ``aws``, ``azure``, or ``gcp``. + + Provide the CMK as follows depending on your KMS provider: + + - For the :ref:`Amazon Web Services KMS + `, specify the full + `Amazon Resource Name (ARN) + `__ + of the master key as a single string. + + - For the :ref:`Azure Key Vault + ` KMS, specify a + document containing the following key value pairs: + + - ``keyName`` - The `Azure Key Vault Name + `__ + - ``keyVaultEndpoint`` - The DNS name of the Azure Key Vault + to use + - ``keyVersion`` - Optional. The version of the key + specified in ``keyName``, if applicable + + .. versionadded:: 4.4.5 + + - For the :ref:`Google Cloud Platform KMS + `, specify a + document containing the following key value pairs: + + - ``projectId`` - The GCP project name + - ``location`` - The location of the KMS keyring + - ``keyRing`` - The name of the KMS keyring (often 'global') + - ``keyName`` - The name of the key to use + - ``keyVersion`` - Optional. The version of the key + specified in ``keyName``, if applicable + + .. versionadded:: 4.4.5 + + :method:`~KeyVault.createKey()` requests + that the KMS encrypt the data encryption key material + using the specified CMK. If the CMK does not exist *or* if the + :ref:`ClientSideFieldLevelEncryptionOptions` configuration + does not have sufficient privileges to use the CMK, :method:`~KeyVault.createKey()` returns an error. .. versionchanged:: 4.2.3 @@ -82,7 +131,6 @@ KeyVault.createKey() ``local`` and can be safely omitted. Prior to MongoDB 4.2.3, if ``keyManagementService`` is ``local`` this parameter *must* be an empty string ``"``. - * - ``keyAltName`` - array of strings @@ -115,8 +163,9 @@ Example ------- The following example is intended for rapid evaluation of -client-side field level encryption. For more complete examples -appropriate for development and production environments, see +client-side field level encryption. For specific examples of using +:method:`KeyVault.createKey()` with each supported +:abbr:`KMS (Key Management Service)` provider, see :ref:`field-level-encryption-data-key-create`. .. include:: /includes/extracts/csfle-connection-boilerplate.rst diff --git a/source/reference/method/KeyVault.deleteKey.txt b/source/reference/method/KeyVault.deleteKey.txt index d5a10712482..f92673a9bbc 100644 --- a/source/reference/method/KeyVault.deleteKey.txt +++ b/source/reference/method/KeyVault.deleteKey.txt @@ -42,8 +42,9 @@ Example ------- The following example is intended for rapid evaluation of -client-side field level encryption. For more complete examples -appropriate for development and production environments, see +client-side field level encryption. For specific examples of using +:method:`KeyVault.deleteKey()` with each supported +:abbr:`KMS (Key Management Service)` provider, see :ref:`field-level-encryption-data-key-delete`. .. include:: /includes/extracts/csfle-connection-boilerplate.rst diff --git a/source/reference/method/KeyVault.getKey.txt b/source/reference/method/KeyVault.getKey.txt index 59c40f0f369..990e40cf72a 100644 --- a/source/reference/method/KeyVault.getKey.txt +++ b/source/reference/method/KeyVault.getKey.txt @@ -47,8 +47,9 @@ Requires Configuring Client-Side Field Level Encryption on Database Connection Example ------- -The following example uses a locally managed KMS for the client-side -field level encryption configuration. +The following example uses a :ref:`locally managed KMS +` for the client-side field level +encryption configuration. .. include:: /includes/extracts/csfle-connection-boilerplate.rst @@ -61,24 +62,21 @@ a data encryption key using its ``UUID``: keyVault = encryptedClient.getKeyVault() keyVault.getKey(UUID("b4b41b33-5c97-412e-a02b-743498346079")) -:method:`~KeyVault.getKey()` returns the following data encryption key: +:method:`~KeyVault.getKey()` returns the data encryption key, with +output similar to the following: .. code-block:: json { "_id" : UUID("b4b41b33-5c97-412e-a02b-743498346079"), - "keyMaterial" : BinData(0,"PXRsLOAYxhzTS/mFQAI8486da7BwZgqA91UI7NKz/T/AjB0uJZxTvhvmQQsKbCJYsWVS/cp5Rqy/FUX2zZwxJOJmI3rosPhzV0OI5y1cuXhAlLWlj03CnTcOSRzE/YIrsCjMB0/NyiZ7MRWUYzLAEQnE30d947XCiiHIb8a0kt2SD0so8vZvSuP2n0Vtz4NYqnzF0CkhZSWFa2e2yA=="), - "creationDate" : ISODate("2019-08-12T21:21:30.569Z"), - "updateDate" : ISODate("2019-08-12T21:21:30.569Z"), - "status" : 0, - "version" : NumberLong(0), + "keyMaterial" : BinData(0,"E+0jZKzA4YuE1lGmSVIy2mivqH4JxFo0yFATdxYX/s0YtMFsgVXyu7Bbn4IQ2gn7F/9JAPJFOxdQc5lN3AR+oX33ewVZsd63f3DN1zzcukqdR2Y+EeO7ekRxyRjdzMaNNrBNIv9Gn5LEJgWPSYkG8VczF7cNZnc1YmnR0tuDPNYfm0J7dCZuZUNWW3FCGRcdFx6AlXiCtXKNR97hJ216pQ=="), + "creationDate" : ISODate("2021-03-16T18:22:43.733Z"), + "updateDate" : ISODate("2021-03-16T18:22:43.733Z"), + "status" : 0, "version" : NumberLong(0), "masterKey" : { - "provider" : "aws", - "key" : "arn:aws:kms:region:account:key/keystring", - "region" : "region", - "endpoint" : "kms.region.amazonaws.com:443" + "provider" : "local" }, "keyAltNames" : [ - "dataKeyAlternativeName" + "alpha" ] } diff --git a/source/reference/method/KeyVault.getKeys.txt b/source/reference/method/KeyVault.getKeys.txt index 967c8542cda..c9080ce632d 100644 --- a/source/reference/method/KeyVault.getKeys.txt +++ b/source/reference/method/KeyVault.getKeys.txt @@ -42,8 +42,9 @@ Requires Configuring Client-Side Field Level Encryption on Database Connection Example ------- -The following example uses a locally managed KMS for the client-side -field level encryption configuration. +The following example uses a :ref:`locally managed KMS +` for the client-side field level +encryption configuration. .. include:: /includes/extracts/csfle-connection-boilerplate.rst @@ -56,41 +57,33 @@ in the key vault: keyVault.getKeys() :method:`~KeyVault.getKeys()` returns all data encryption keys in the -key vault: +key vault, with output similar to the following: .. code-block:: json { "_id" : UUID("b4b41b33-5c97-412e-a02b-743498346079"), "keyMaterial" : BinData(0,"PXRsLOAYxhzTS/mFQAI8486da7BwZgqA91UI7NKz/T/AjB0uJZxTvhvmQQsKbCJYsWVS/cp5Rqy/FUX2zZwxJOJmI3rosPhzV0OI5y1cuXhAlLWlj03CnTcOSRzE/YIrsCjMB0/NyiZ7MRWUYzLAEQnE30d947XCiiHIb8a0kt2SD0so8vZvSuP2n0Vtz4NYqnzF0CkhZSWFa2e2yA=="), - "creationDate" : ISODate("2019-08-12T21:21:30.569Z"), - "updateDate" : ISODate("2019-08-12T21:21:30.569Z"), - "status" : 0, - "version" : NumberLong(0), + "creationDate" : ISODate("2021-03-15T12:21:13.123Z"), + "updateDate" : ISODate("2021-03-15T12:21:13.123Z"), + "status" : 0, "version" : NumberLong(0), "masterKey" : { - "provider" : "aws", - "key" : "arn:aws:kms:region:account:key/keystring", - "region" : "region", - "endpoint" : "kms.region.amazonaws.com:443" + "provider" : "local" }, "keyAltNames" : [ - "dataKeyAlternativeName_alpha" + "alpha" ] } { - "_id" : UUID("0aa9dc24-2f28-42da-ad87-26e3930e743c"), - "keyMaterial" : BinData(0 "PXRsLOAYxhzTS/mFQAI8486da7BwZgqA91UI7NKz/T/AjB0uJZxTvhvmQQsKbCJYsWVS/cp5Rqy/FUX2zZwxJOJmI3rosPhzV0OI5y1cuXhAlLWlj03CnTcOSRzE/YIrsCjMB0/NyiZ7MRWUYzLAEQnE30d947XCiiHIb8a0kt2SD0so8vZvSuP2n0Vtz4NYqnzF0CkhZSWFa2e2yA=="), - "creationDate" : ISODate("2019-08-12T22:10:44.847Z"), - "updateDate" : ISODate("2019-08-12T22:10:44.847Z"), - "status" : 0, - "version" : NumberLong(0), + "_id" : UUID("f1add015-c7ab-49a2-a071-50b0ca0a8fbc"), + "keyMaterial" : BinData(0,"E+0jZKzA4YuE1lGmSVIy2mivqH4JxFo0yFATdxYX/s0YtMFsgVXyu7Bbn4IQ2gn7F/9JAPJFOxdQc5lN3AR+oX33ewVZsd63f3DN1zzcukqdR2Y+EeO7ekRxyRjdzMaNNrBNIv9Gn5LEJgWPSYkG8VczF7cNZnc1YmnR0tuDPNYfm0J7dCZuZUNWW3FCGRcdFx6AlXiCtXKNR97hJ216pQ=="), + "creationDate" : ISODate("2021-03-16T18:22:43.733Z"), + "updateDate" : ISODate("2021-03-16T18:22:43.733Z"), + "status" : 0, "version" : NumberLong(0), "masterKey" : { - "provider" : "aws", - "key" : "arn:aws:kms:region:account:key/keystring" - "region" : "region", - "endpoint" : "kms.region.amazonaws.com:443" + "provider" : "local" }, "keyAltNames" : [ - "dataKeyAlternativeName_baker" + "baker" ] } diff --git a/source/reference/method/KeyVault.removeKeyAlternateName.txt b/source/reference/method/KeyVault.removeKeyAlternateName.txt index 3f89283e5a5..e71035e0ae2 100644 --- a/source/reference/method/KeyVault.removeKeyAlternateName.txt +++ b/source/reference/method/KeyVault.removeKeyAlternateName.txt @@ -45,8 +45,9 @@ Example ------- The following example is intended for rapid evaluation of -client-side field level encryption. For more complete examples -appropriate for development and production environments, see +client-side field level encryption. For specific examples of using +:method:`KeyVault.removeKeyAlternateName()` with each supported +:abbr:`KMS (Key Management Service)` provider, see :ref:`field-level-encryption-data-key-manage`. .. include:: /includes/extracts/csfle-connection-boilerplate.rst diff --git a/source/reference/method/Mongo.txt b/source/reference/method/Mongo.txt index feafe585aa2..4e9e04dd515 100644 --- a/source/reference/method/Mongo.txt +++ b/source/reference/method/Mongo.txt @@ -142,18 +142,32 @@ following parameters: - document - - *(Required)* The Key Management Service (KMS) used by - client-side field level encryption for managing a Customer Master - Key (CMK). Client-side field level encryption uses the CMK for - encrypting and decrypting data encryption keys. - - Client-side field level encryption either the Amazon Web Services - KMS *or* a Locally Managed Key: + - *(Required)* The :ref:`Key Management Service (KMS) + ` used by client-side field level + encryption for managing a Customer Master Key (CMK). Client-side + field level encryption uses the CMK for encrypting and decrypting + data encryption keys. + + Client-side field level encryption supports the following KMS + providers: + + - :ref:`Amazon Web Services KMS ` + - :ref:`Azure Key Vault ` + - :ref:`Google Cloud Platform KMS ` + - :ref:`Locally Managed Key ` + + If possible, consider defining the credentials provided in + ``kmsProviders`` as environment variables, and then passing them + to the :binary:`~bin.mongo` shell using the :option:`--eval + ` option. This minimizes the chances of credentials + leaking into logs. See + :ref:`field-level-encryption-data-key-create` for examples of + this approach for each supported KMS. Amazon Web Services KMS .. include:: /includes/extracts/csfle-aws-kms-4.2.0-4.2.1-broken.rst - Specify the ``aws`` document to ``kmsProvider`` with the + Specify the ``aws`` document to ``kmsProviders`` with the following fields: .. code-block:: json @@ -168,8 +182,39 @@ following parameters: The specified ``accessKeyId`` must correspond to an IAM user with all ``List`` and ``Read`` permissions for the KMS service. + Azure Key Vault + Specify the ``azure`` document to ``kmsProviders`` with the + following fields: + + .. code-block:: json + + "kmsProviders" : { + "azure" : { + "tenantId" : "AzureTenantId", + "clientId" : "AzureClientId", + "clientSecret" : "AzureClientSecret" + } + } + + .. versionadded:: 4.4.5 + + Google Cloud KMS + Specify the ``gcp`` document to ``kmsProviders`` with the + following fields: + + .. code-block:: json + + "kmsProviders" : { + "gcp" : { + "email" : "GCPEmail", + "privateKey" : "GCPPrivateKey" + } + } + + .. versionadded:: 4.4.5 + Locally Managed Key - Specify the ``local`` document to ``kmsProvider`` with the + Specify the ``local`` document to ``kmsProviders`` with the following field: .. code-block:: json diff --git a/source/reference/security-client-side-automatic-json-schema.txt b/source/reference/security-client-side-automatic-json-schema.txt index 1ed8d89a253..a0ccc1ff2d0 100644 --- a/source/reference/security-client-side-automatic-json-schema.txt +++ b/source/reference/security-client-side-automatic-json-schema.txt @@ -340,11 +340,11 @@ and ``taxid-short`` fields for write or read operations to the The data encryption key *must* exist in the key vault specified as part of the auto encryption :ref:`configuration options `. The specified configuration - options must *also* include appropriate access to the Key Management - Service (KMS) and Customer Master Key (CMK) used to create the data - key. Automatic encryption fails if the data encryption key does not - exist *or* if the client cannot decrypt the key with the specified KMS - and CMK. + options must *also* include appropriate access to the + :ref:`Key Management Service (KMS) ` and + Customer Master Key (CMK) used to create the data key. Automatic + encryption fails if the data encryption key does not exist *or* if the + client cannot decrypt the key with the specified KMS and CMK. Official MongoDB 4.2-compatible drivers have language-specific requirements for specifying the UUID. Defer to the diff --git a/source/tutorial/manage-client-side-encryption-data-keys.txt b/source/tutorial/manage-client-side-encryption-data-keys.txt index 11b7dcdac1b..b072f73e4c4 100644 --- a/source/tutorial/manage-client-side-encryption-data-keys.txt +++ b/source/tutorial/manage-client-side-encryption-data-keys.txt @@ -19,37 +19,88 @@ modifying, and deleting data encryption keys. This page documents client-side field level encryption using the :binary:`~bin.mongo` shell, and does *not* refer to any official MongoDB -4.2-compatible driver. See the relevant :ref:`documentation +4.2+ compatible driver. See the relevant :ref:`documentation ` for driver-specific data encryption key management methods and syntax. .. _field-level-encryption-data-key-create: -Create a data encryption key +Create a Data Encryption Key ---------------------------- The following procedure uses the :binary:`~bin.mongo` shell to create a data encryption key for use with client-side field level encryption and decryption. For guidance on data encryption key management using a -4.2-compatible driver, see the documentation for that driver. +4.2+ compatible driver, see the `driver documentation +`__ instead. -.. include:: /includes/steps/manage-client-side-encryption-create-key.rst +Use the tabs below to select the :abbr:`KMS (Key Management Service)` +appropriate for your deployment: + +.. tabs:: + + .. tab:: Amazon Web Services KMS + :tabid: aws-kms + + .. include:: /includes/steps/csfle-shell-aws-create-key.rst + + .. tab:: Azure Key Vault + :tabid: azure-vault + + .. include:: /includes/steps/csfle-shell-azure-create-key.rst + + .. tab:: Google Cloud KMS + :tabid: gcp-kms + + .. include:: /includes/steps/csfle-shell-gcp-create-key.rst + + .. tab:: Local Keyfile + :tabid: local-keyfile + + .. include:: /includes/steps/csfle-shell-local-create-key.rst .. _field-level-encryption-data-key-manage: -Manage a data encryption key's alternate name +Manage a Data Encryption Key's Alternate Name --------------------------------------------- The following procedure uses the :binary:`~bin.mongo` shell to manage the alternate names of a data encryption key. For guidance on data -encryption key management using a 4.2-compatible driver, see the -documentation for that driver. +encryption key management using a 4.2+ compatible driver, see the +`driver documentation `__ instead. + +If you are still within your configured :binary:`~bin.mongo` shell +session from the :ref:`field-level-encryption-data-key-create` steps +above, you can skip directly to step 5. -.. include:: /includes/steps/manage-client-side-encryption-manage-key-altname.rst +Use the tabs below to select the :abbr:`KMS (Key Management Service)` +appropriate for your deployment: + +.. tabs:: + + .. tab:: Amazon Web Services KMS + :tabid: aws-kms + + .. include:: /includes/steps/csfle-shell-aws-manage-key-altname.rst + + .. tab:: Azure Key Vault + :tabid: azure-vault + + .. include:: /includes/steps/csfle-shell-azure-manage-key-altname.rst + + .. tab:: Google Cloud KMS + :tabid: gcp-kms + + .. include:: /includes/steps/csfle-shell-gcp-manage-key-altname.rst + + .. tab:: Local Keyfile + :tabid: local-keyfile + + .. include:: /includes/steps/csfle-shell-local-manage-key-altname.rst .. _field-level-encryption-data-key-delete: -Remove a data encryption key +Remove a Data Encryption Key ---------------------------- .. warning:: @@ -59,7 +110,65 @@ Remove a data encryption key The following procedure uses the :binary:`~bin.mongo` shell to remove a data encryption key from the key vault. For guidance on data encryption -key management using a 4.2-compatible driver, see the documentation for -that driver. +key management using a 4.2+ compatible driver, see the +`driver documentation `__ instead. + +If you are still within your configured :binary:`~bin.mongo` shell +session from the :ref:`field-level-encryption-data-key-create` steps +above, you can skip directly to step 5. + +Use the tabs below to select the :abbr:`KMS (Key Management Service)` +appropriate for your deployment: + +.. tabs:: + + .. tab:: Amazon Web Services KMS + :tabid: aws-kms + + .. include:: /includes/steps/csfle-shell-aws-delete-key.rst + + .. tab:: Azure Key Vault + :tabid: azure-vault + + .. include:: /includes/steps/csfle-shell-azure-delete-key.rst + + .. tab:: Google Cloud KMS + :tabid: gcp-kms + + .. include:: /includes/steps/csfle-shell-gcp-delete-key.rst + + .. tab:: Local Keyfile + :tabid: local-keyfile + + .. include:: /includes/steps/csfle-shell-local-delete-key.rst + +.. _field-level-encryption-data-key-retrieve: + +Retrieve an Existing Data Encryption Key +---------------------------------------- + +To retrieve an existing data encryption key document from the key vault, +either: + +- Use :method:`getKey() ` to retrieve the created + key by its :abbr:`UUID (Universally unique identifier)`, or +- Use :method:`getKeyByAltName() ` to + retrieve the key by its alternate name, if specified. For more + information on working with alternate names, see + :ref:`field-level-encryption-data-key-manage`. + +If providing the data encryption key to an official 4.2+ compatible +driver in order to configure +:ref:`automatic client-side field level encryption +`, 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() -.. include:: /includes/steps/manage-client-side-encryption-delete-key.rst +Supply the ``UUID`` of your own data encryption key to this command.