MongoDB has a mode that allows encrypting its data. This mode utilizes a UKC Entry Point as a KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server server. Instructions are provided for the case when your MongoDB database already exists and just needs to have UKC configured.
More information about MongoDB databases can be found here:
Information about using encryption with MongoDB can be found here:
You need the following prerequisites for integration with UKC:
- Mongo DB version 3.2 and newer
- MongoDB Enterprise required
- WiredTiger Storage Engine required
The process in the following sections assume that you are setting up MongoDB for the first time. If you have an existing MongoDB database, see Migrating an Existing MongoDB Database.
Create a UKC partition on the EP server and certificate for its client with the following commands:
- Create a partition on the EP.
ucl partition create -p <partition_name> -w <root_so_password> -s <so_password>
Create the client (in full mode):
ucl client create -p <partition_name> -m full -n client1 --output <pfx_name>.pfx --pfx_password <pfx_password> -w <so_password>
Extract the certificate from the client .pfx file using openssl, with the following command:
openssl pkcs12 -in <pfx_name>.pfx -out client_cert.pem -nodes -clcerts -passin pass:[pfx_password]
openssl pkcs12 -in C:\ProgramData\Dyadic\ekm\client.pfx -out C:\Progra~1\MongoDB\Server\3.6\bin\client1.pem -nodes -clcerts -passin pass:password1!
Specifying a password on the pfx creation is only possible if the client was created in full mode.
Retrieve the root certificate.
ucl root_ca -o server-ca.cer
Convert the server-ca.cer to pem format.
openssl x509 -inform der -in server-ca.cer -out server-ca.pem
- Put the client_cert.pem and server-ca.pem files into the MongoDB bin folder, located in:
- Generate the AES key:
ucl generate -t aes -s 256 -p <partition_name> --exportable
- Save the UID created in the previous command.
This path is relevant for MongoDB running on a Windows machine. For Linux, you should copy the certificate into the corresponding
If MongoDB is in your path, then you need to use full paths for the pem files specified in the commands below.
If you run
mongod from the MongoDB bin directory, then you do not need full path names for those files (as in the following commands).
Once you have a MongoDB database running, use the following command to connect
mongod to the key manager. You use the existing master key from your UKC/KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server server.
--kmipServerName <UKC EP server>\
--kmipPort <kmip_port> \
--kmipServerCAFile ca.pem \
--kmipClientCertificateFile client_cert.pem \
--kmipClientCertificatePassword <pfx_pass> \
The parameters in the previous command are defined as follows:
- kmipServerName - The EP server name.
MongoDB 4.2.1 and newer supports multiple KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server hosts for high availability. See this link for more information.
- kmipPort - use the default of 5696.
- kmipServerCAFile - The server CA certificate in pem format.
- kmipClientCertificateFile - The client certificate is a pem file containing the key and certificate extracted from the partition .pfx file from the previous section.
- kmipClientCertificatePassword - The password for the partition PFXAn archive file format for storing cryptography objects using Base64 encoding, which is the same password specified in the above openssl command.
- kmipKeyIdentifier - The name (“0x00”+uid) of the UKC key to be used by MongoDB.
The key must be an exportable symmetric 256 bits key.
To verify that the key creation and usage was successful, check the log file. If successful, the process will log the following messages:
[initandlisten] Encryption key manager initialized using master key with id: <UID>
Use the following procedure to move an existing MongoDB database to a MongoDB database that uses UKC for encryption.
Run mongodump from the system command-line. This utility creates a directory called
dumpin the working folder containing the backup files.
Stop the mongod service from the command-line.
Delete the data/db folder.
Follow the instructions in Set up the UKC Partition and Client
- Follow the instructions in UKC Integration with MongoDB.
Run mongorestore from the system command-line. This utility restores the database from the
dumpfolder created in the first step.
You now have the original database restored into a database encrypted with UKC.
These instructions are based on a single instance of the database. For high-availability implementations, which Mongo refers to as replication, the backup and restore process is recommended using the Mongo Cloud Manager.
If you currently use one type of encryption key and you want to switch to UKC keys, you can rotate the encryption keys.