MongoDB

MongoDB has a mode that allows encrypting its data. This mode utilizes a CORE 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 CORE configured.

More information about MongoDB databases can be found here:

https://www.mongodb.com

Information about using encryption with MongoDB can be found here:

https://docs.mongodb.com/manual/tutorial/configure-encryption/index.html

Prerequisites

You need the following prerequisites for integration with CORE:

• Mongo DB version 3.2 and newer
• MongoDB Enterprise required
• WiredTiger Storage Engine required

Note
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 CORE Partition and Client

Create a CORE 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!

   Note
   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:

C:\Progra~1\MongoDB\Server\3.6\bin\

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

7. Generate the AES key:

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

8. Save the UID created in the previous command.

CORE Integration with MongoDB

Note
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 CORE/KMIPKey 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 <CORE 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:

• kmipServerName - The EP server name.

  Note
  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 CORE key to be used by MongoDB.

  Note
  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>

Migrating an Existing MongoDB Database

Use the following procedure to move an existing MongoDB database to a MongoDB database that uses CORE 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 CORE Partition and Client

5. Follow the instructions in CORE 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 CORE.

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

 

Note
If you currently use one type of encryption key and you want to switch to CORE keys, you can rotate the encryption keys.