MongoDB has a mode that allows encrypting its data. This mode utilizes a UKC Entry Point as a KMIPClosedKey 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.

Set up the UKC Partition and Client

Create a UKC partition on the EP server and certificate for its client with the following commands:

  1. Create a partition on the EP.

    ucl partition create -p <partition_name> -w <root_so_password> -s <so_password>

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

  3. 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]

    For example:

    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.

  4. Retrieve the root certificate.

    ucl root_ca -o server-ca.cer

  5. Convert the server-ca.cer to pem format.

    openssl x509 -inform der -in server-ca.cer -out server-ca.pem

  6. Put the client_cert.pem and server-ca.pem files into the MongoDB bin folder, located in:
  7. C:\Progra~1\MongoDB\Server\3.6\bin\

    This path is relevant for MongoDB running on a Windows machine. For Linux, you should copy the certificate into the corresponding bin directory.

  8. Generate the AES key:

    ucl generate -t aes -s 256 -p <partition_name> --exportable

  9. Save the UID created in the previous command.

UKC Integration with MongoDB

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/KMIPClosedKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server server.

mongod \
--enableEncryption \
--kmipServerName <UKC EP server>\
--kmipPort <kmip_port> \
--kmipServerCAFile ca.pem \
--kmipClientCertificateFile client_cert.pem \
--kmipClientCertificatePassword <pfx_pass> \
--kmipKeyIdentifier 0x00<keyid>

The parameters in the previous command are defined as follows:

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>

Migrating an Existing MongoDB Database

Use the following procedure to move an existing MongoDB database to a MongoDB database that uses UKC for encryption.

  1. Run mongodump from the system command-line. This utility creates a directory called dump in the working folder containing the backup files.

  2. Stop the mongod service from the command-line.

    mongod --shutdown

  3. Delete the data/db folder.

  4. Follow the instructions in Set up the UKC Partition and Client

  5. Follow the instructions in UKC Integration with MongoDB.
  6. Run mongorestore from the system command-line. This utility restores the database from the dump folder 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.