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
Warning
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, orUse
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.