MongoDB

MongoDB has a mode that allows encrypting its data. This mode utilizes a UKCUnbound Key Control - The name of Unbound's key management product. 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 UKCUnbound Key Control - The name of Unbound's key management product. 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 UKCUnbound Key Control - The name of Unbound's key management product.:

  • 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 UKC Partition and Client

Create a UKCUnbound Key Control - The name of Unbound's key management product. 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. Copy the client .pfx file and server-ca.p7b, located in C:\ProgramData\Dyadic\ekm\, to the client.
  4. Put the certificate in 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.

  5. Extract the certificate from the .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.

  6. Generate the AES key:

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

  7. Save the UID created in the previous command.
  8. Create the default directory for MongoDB:

    mkdir c:\data\db

UKC Integration with MongoDB

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 UKCUnbound Key Control - The name of Unbound's key management product./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 <UKC EP server>\
--kmipPort <kmip_port> \
--kmipServerCAFile ca.pem \
--kmipClientCertificateFile client_cert.pem \
--kmipClientCertificatePassword <pfx_pass> \
--kmipKeyIdentifier 0x00<keyid> \
--enableEncryption

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] Created KMIP key with id: <UID>
[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 UKCUnbound Key Control - The name of Unbound's key management product. 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 UKCUnbound Key Control - The name of Unbound's key management product..

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 UKCUnbound Key Control - The name of Unbound's key management product. keys, you can rotate the encryption keys.