Manage Data Encryption Keys
On this page
New in version 4.2.
Client-side field level encryption uses data encryption keys for
encryption and decryption. The mongo shell
getKeyVault() method returns a key vault object for creating,
modifying, and deleting data encryption keys.
This page documents client-side field level encryption using the
mongo shell, and does not refer to any official MongoDB
4.2+ compatible driver. See the relevant documentation for driver-specific data encryption
key management methods and syntax.
Create a Data Encryption Key
The following procedure uses the 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 driver documentation instead.
Use the tabs below to select the KMS appropriate for your deployment:
Manage a Data Encryption Key's Alternate Name
The following procedure uses the 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
driver documentation instead.
If you are still within your configured mongo shell
session from the Create a Data Encryption Key steps
above, you can skip directly to step 5.
Use the tabs below to select the KMS appropriate for your deployment:
Remove a Data Encryption Key
Deleting a data encryption key renders all fields encrypted using that key as permanently unreadable.
The following procedure uses the 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
driver documentation instead.
If you are still within your configured mongo shell
session from the Create a Data Encryption Key steps
above, you can skip directly to step 5.
Use the tabs below to select the KMS appropriate for your deployment:
Retrieve an Existing Data Encryption Key
To retrieve an existing data encryption key document from the key vault, either:
- Use
getKey()to retrieve the created key by its UUID, or - Use
getKeyByAltName()to retrieve the key by its alternate name, if specified. For more information on working with alternate names, see Manage a Data Encryption Key's Alternate Name.
If providing the data encryption key to an official 4.2+ compatible
driver in order to configure
automatic client-side field level encryption, you must use the base64
representation of the UUID string.
You can run the following operation in the mongo
shell to convert a UUID hexadecimal string to its base64
representation:
UUID("b4b41b33-5c97-412e-a02b-743498346079").base64()
Supply the UUID of your own data encryption key to this command.