Chapter 1: About This Manual

Using AKM to encrypt data in MongoDB

MongoDB Enterprise supports KMIP integration at the database level. Alliance Key Manager supports KMIP 1.0. Customers using MongoDB can retrieve an existing encryption key from AKM or create a new key on AKM using the KMIP interface. They can then use this encryption key as a MongoDB “master key” to encrypt MongoDB database keys.

Who is this for?

This guide is designed to help MongoDB administrators and project managers use an external encryption key stored on Alliance Key Manager as the MongoDB “master key”. An existing encryption key on AKM may be retrieved, or a new encryption key can be created from MongoDB and stored on AKM for later retrieval.

Other resources

The following documents provide additional information on the installation and use of Alliance Key Manager:

Notices

This product and documentation is covered by U.S. and International copyright law. This product may incorporate software licensed under one or more open source license agreements. Government users please note that this product is provided under restricted government use license controls. Please refer to the AKM End User License Agreement for more information.

Change log

The following table provides information on the changes to this documentation:

Version Date Description
4.0.0.001 5/24/2016 Initial release.
4.5.0.001 2/6/2017 Expanded HA section
4.5.0.002 2/20/2017 Fixed UID secion
4.6.0.000 9/25/2018 Added load balancing failover scenarios

Chapter 2: Preparation

You will need to complete the following steps before continuing:

  • Review pre-requisites

  • Install and set up the primary AKM server (instructions are located in platform specific deployment guides)

  • Create encryption keys (available as an option during AKM server setup, or, through the AKM Administrative Console application)

  • Download authentication certificates from the AKM server

  • Know the hostname assigned to the AKM server during initialization, the IP address of the AKM server, and KMIP port number (the default is 5696)

See below for more information.

Pre-requisites

  • MongoDB Enterprise Edition (version 3.2+).

  • Alliance Key Manager (version 3.0.0+)

MongoDB data directory must be empty

The MongoDB data directory must be empty to enable encryption. This means that if you have preexisting data, you must export/backup your data and clear out the data directory, then import it after setup is complete. Please contact MongoDB if support is needed.

Certificates

MongoDB and the AKM server use certificate and private keys to establish a secure TLS connection and perform authentication. You will need to install the following certificates and private keys on MongoDB in order to authenticate with the AKM server:

  • The primary AKM’s certificate authority (CA) certificate in .pem format (AKMRootCACertificate.pem)

  • Key client certificate (AKMClientCertificate.pem) and private key (AKMClientPrivateKey.pem) in .pem format (if retrieving a pre-existing encryption key from AKM)

  • Admin (Crypto Officer) certificate (AKMAdminCertificate.pem) and private key (AKMAdminPrivateKey) in .pem format (if creating a new encryption key on AKM)

These certificates and private keys are generated on initialization and stored on the AKM server. See your platform specific AKM deployment guide for instructions on downloading these certificates.

The client certificate and private key PEM files will need to be concatenated, for example:

Client certificate and private key:

 $ cat AKMClientCertificate.pem AKMClientPrivateKey.pem > AKMClientCertandKey.pem

Admin certificate and private key:

 $ cat AKMAdminCertificate.pem AKMAdminPrivateKey.pem > AKMAdminCertandKey.pem

The two PEM files should be placed within a dedicated directory, for example: /etc/mongodb-kmip. Care should be taken to protect this directory using native MongoDB access controls.

SECURITY ALERT: Private key files must be protected during creation, distribution, and storage to prevent loss. The loss of these files will compromise the security of the AKM server. Depending on the file format, the private key files may be bundled with a certificate or they may be separate files. Transfer the private key files by sharing them over a secure network, placing them in a password-protected zip file, sending them using SFTP, or another secure method. Use the same level of care you would employ to protect encryption keys, including encryption. In the event the private keys are compromised or lost, you should immediately replace the certificate authority on the AKM server and all client certificates in that chain of trust. See the AKM Certificate Manager Guide for more information.

Server information

You will need the following server information before continuing:

  • The hostname and IP address of the AKM server

  • The port number that AKM has been configured to use for KMIP (the default is 5696)

Encryption keys

You have two options with MongoDB and KMIP: to encrypt data using a pre-existing key already created on AKM, or to create a new encryption key on AKM using the KMIP protocol from MongoDB. If using the first option, you will need to know the current instance name of the key on AKM you would like to use.

AKM setup and initialization includes the option to generate an initial set of encryption keys. See your platform-specific AKM deployment guide for key names of keys available for use, if that option was selected. Then use the AKM Administrative Console to look up the key instance.

If needed, new encryption keys can also be created using the AKM Administrative Console application. See the AKM Administrative Console Guide for more information.

Checklist

Before continuing, you will need the following items:

  • AKM’s CA certificate in .pem format

  • A key client certificate/private key in .pem format (if retrieving a pre-existing encryption key from AKM), OR an admin (Crypto Officer) client certificate/private key in .pem format (if creating a new encryption key on AKM) and associated password

  • The IP address or DNS name of the AKM server and the port number it will use for KMIP

  • The current instance name of one or more encryption keys on the AKM server

 

Chapter 3: Retrieve a Pre-Existing Encryption Key

This chapter describes how to retrieve an existing encryption key from AKM in MongoDB. The key must be a 256-bit symmetric encryption key which by default will be used for CBC mode encryption.

Configuration

The MongoDB configuration file is located at /etc/mongod.conf. To use a pre-existing encryption key on AKM you must specify the server name, certificate details and the UID (see more info about deriving the UID below):

security:                                                                                       
   enableEncryption: true                                                                        
   kmip:                                                                                         
     serverName: akmmongo                                                                        
     port: 5696                                                                                  
     serverCAFile: /etc/mongodb-kmip/AKMRootCACertificate.pem                                    
     clientCertificateFile: /etc/mongodb-kmip/AKMClientCertandKey.pem                           
     keyIdentifier: <UID>

Warning: Avoid inline comments (#), as they will get processed anyway.

The serverName is the name assigned to the primary AKM server during the initialization process, which is also used as the CN in the primary’s server certificate.

You will need to add the primary AKM server’s hostname to your DNS or the /etc/hosts file on your MongoDB server so that the name can be resolved to the IP address of the AKM server.

NOTE: If you want to specify the IP address of the server for this option, you must add the IP address to /etc/hosts and specify the AKM server name as a hostname there.

The port must be the KMIP port on AKM, which by default is 5696.

The serverCAFile lists the directory location and name of AKM’s root CA certificate.

The clientCertificateFile lists the directory location and name of the client certificate/private key file.

The keyIdentifier is the UID of a preexisting 256-bit AES key on AKM. This can be determined using the steps in the next section.

Get the UID of a preexisting 256-bit key on AKM

Using the AKM Administrative Console execute the “Display Key Instance List” command to obtain the most current instance (version) of the key, which is listed on the highest numbered line at the bottom of the key instance list. Commonly this is ‘line 1’ unless the key has been rolled, in which case it would be ‘line 2’ and so forth.

To derive the UID from the key instance, use a tool such as this to convert the Base64 string to hex (B16). Then add hyphens manually, grouping characters into sets of 8, 4, 4, 4, and 12, separated by hyphens. For example, a hex value of 9ca7ed9f09ba66127f8ed30baba8900c should look like this afterwards: 9ca7ed9f-09ba-6612-7f8e-d30baba8900c. The UID must be lowercase.

Verify successful configuration

After modifying the MongoDB configuration file, start MongoDB with these options:

mongod --enableEncryption --kmipServerName <KMIP Server HostName> 
--kmipServerCAFile /etc/mongodb-kmip/AKMRootCACertificate.pem --kmipClientCertificateFile /etc/mongodb-kmip/AKMAdminCertandKey.pem 
--kmipKeyIdentifier <UID> --dbpath /var/lib/mongodb/

The --kmipServerName must match the name assigned to the AKM server during the initialization process.

The --kmipServerCAFile is the directory location and name of AKM’s root CA certificate.

The --kmipClientCertificateFile is the directory location and name of the client certificate/private key file.

The --keyIdentifier is the UID of the pre-existing encryption key.

IMPORTANT: If data has previously been encrypted with a key, you must specify that key’s for the `--kmipKeyIdentifier` when starting MongoDB. Otherwise, MongoDB will not start and log an error.

The dbpath lists the package location. Depending on the platform this may be different than in this example. Check the mongod.conf file for the correct path.

View the MongoDB log file at /var/log/mongodb/mongod.log. If the operation was successful, the MongoDB log will show:

[initandlisten] Encryption key manager initialized using KMIP key with id:<UID>. 

View the AKM Audit log on the AKM server using the steps in the AKM Server Management Guide. If successful, the log will show:

2016-04-13,18:14:44,Get,akm,4.0.0.1549.1,192.168.99.140:5696,192.168.99.139:54363,Operation <0000000a> Unique Identifier <3f206787-0cde-84a8-684b-556b4cc9fd81> y-Instance <PyBnhwzehKhoS1VrTMn9gQ==>,user,group,Kmip,N,5,EFe8jpT1/hGhV/6t+zzXuPZYfgwJW1vbBX4ykv9Y2FU=

Example encryption

This example creates some data to be encrypted:

MongoDB Enterprise > show dbs
local  0.000GB
MongoDB Enterprise > use mydb
switched to db mydb
MongoDB Enterprise > db.mydb.insert( { x: 1 } );
WriteResult({ "nInserted" : 1 })
MongoDB Enterprise > db.mydb.find().pretty()
{ "_id" : ObjectId("56de8bb21ded2e500ad9c2c0"), "x" : 1 }
MongoDB Enterprise > ^C
bye

 

Chapter 4: Create a New Encryption Key with MongoDB

This chapter describes how to create a new key on AKM from MongoDB. These procedures create a 256-bit AES symmetric key which by default is used for CBC mode.

This operation requires an admin (Crypto Officer) certificate.

NOTE: KMIP does not ensure complete separation of duties between key client and crypto officer. Key clients can only retrieve keys (but not create/manage them), however, Crypto Officers may both create/manage keys and retrieve keys. If you wish to enforce clear separation of duties follow the steps in Chapter 3 to create keys exclusively using the AKM Administrative Console.

Start MongoDB and create a key

Start MongoDB manually, using the following parameters to create an encryption key:

mongod --enableEncryption --kmipServerName akmmongo --kmipServerCAFile /etc/mongodb-kmip/AKMRootCACertificate.pem --kmipClientCertificateFile /etc/mongodb-kmip/AKMAdminCertificate.pem --dbpath /var/lib/mongodb/

The kmipServerName must match the name assigned to the AKM server during the initialization process (this also matches the issuer CN name in the CA certificate).

The kmipServerCAFile lists the directory location and name of AKM’s root CA certificate.

The kmipClientCertificateFile lists the directory location and name of the client certificate/private key file.

Check the output for success:

[initandlisten] Created KMIP key with id:<UID>
[initandlisten] Encryption key manager initialized using KMIP key with id: <UID>

Note the UID to paste into the mongod.conffile (see next section).

View the AKM Audit log on the AKM server using the steps in the AKM Server Management Guide to verify successful key creation:

2016-04-13,18:01:03,Create,akm,4.0.0.1549.1,192.168.99.140:5696,192.168.99.139:54361,Operation <00000001> Unique Identifier <9ca7ed9f-09ba-6612-7f8e-d30baba8900c> y-Instance <nKftnwm6ZhJ/jtMLq6iQDA==>,admin1,akm_admin,Kmip,N,2,jy5bbg6W+ZunBKwl5dAnDycqhpHhsu1arSdHv401Rj4=

If after running MongoDB manually your permissions may be incorrect. If so execute the following:

chown -R mongodb:mongodb /var/lib/mongodb/ /etc/mongodb-kmip/
sudo chmod -R 600 /etc/mongodb-kmip/*

Configuration

The MongoDB configuration file is located at /etc/mongod.conf. After creating the key, you must specify the server name, certificate details and the UID from the previous step to continue using the key:

security:                                                                                       
   enableEncryption: true                                                                        
   kmip:                                                                                         
     serverName: akmmongo                                                                        
     port: 5696                                                                                  
     serverCAFile: /etc/mongodb-kmip/AKMRootCACertificate.pem                                    
     clientCertificateFile: /etc/mongodb-kmip/AKMAdminCertificate.pem                           
     keyIdentifier: <UID>

Warning: Avoid inline comments (#), as they will get processed anyway.

The serverName is the name assigned to the AKM server during the initialization process, which is also used as the CN in the server certificate.

You will need to add the AKM server’s name (hostname) to your DNS or the /etc/hosts file on your MongoDB server so that the name can be resolved to the IP address of the AKM server.

NOTE: If you want to specify the IP address of the server for this option, you must add the IP address to /etc/hosts and specify the AKM server name as a hostname there.

The port must be the KMIP port on AKM, which by default is 5696.

The serverCAFile is the directory location and name of AKM’s root CA certificate.

The clientCertificateFile is the directory location and name of the admin certificate/private key file.

The keyIdentifier is the UID of the key created in the previous step. The UID must be lowercase.

After modifying the MongoDB configuration file, start MongoDB. View the MongoDB log file at /var/log/mongodb/mongod.log. If the operation was successful, the MongoDB log will show:

I STORAGE  [initandlisten] Encryption key manager initialized using KMIP key with id: 3f206787-0cde-84a8-684b-556b4cc9fd81.

View the AKM Audit log to verify a successful key retrieval of the recently created key:

2016-03-08,05:26:13,Get,akm,4.0.0.1549.1,192.168.99.140:5696,192.168.99.139:54347,Operation <0000000a> Unique Identifier <3f206787-0cde-84a8-684b-556b4cc9fd81> y-Instance <PyBnhwzehKhoS1VrTMn9gQ==>,user,group,Kmip,N,26,0DpCNcjDUgqA99gr89UbANXlsFKiMI96oe2e0XsYwL0=

Example encryption

This example creates some data to be encrypted:

MongoDB Enterprise > show dbs
local  0.000GB
MongoDB Enterprise > use mydb
switched to db mydb
MongoDB Enterprise > db.mydb.insert( { x: 1 } );
WriteResult({ "nInserted" : 1 })
MongoDB Enterprise > db.mydb.find().pretty()
{ "_id" : ObjectId("56de8bb21ded2e500ad9c2c0"), "x" : 1 }
MongoDB Enterprise > ^C
bye

Chapter 5: Key Rollover

Key rollover is an important component of a security strategy. See the AKM User Guide for more information.

Automatic key rollover (also known as “key rotation” as used in MongoDB documentation) of the AKM encryption key is not supported in MongoDB; however, you can manually roll the key using one of two methods depending on whether you are retrieving an existing AKM encryption key or creating a new encryption key on AKM from MongoDB.

Roll the key when retrieving an existing encryption key

When retrieving an existing encryption key from the AKM server as described in Chapter 3, you can manually rotate the key using the “Rollover” command in the AKM Administrative Console application (available on the AKM Supplemental). You will need to know the name of the key to roll.

After rolling the key, copy the key instance from the output of the command and then follow the steps in Chapter 3 again to derive the new UID to use when retrieving the key.

Roll the key when creating a new encryption key on AKM

The --kmipRotateMasterKey option rolls the AKM encryption key and re-encrypts the internal keystore. This operation requires a Crypto Officer (admin) certificate as described in Chapter 4.

This option is also set in the configuration:

security:                                                                                       
   enableEncryption: true                                                                        
   kmip:                                                                                         
     serverName: akmmongo  
     rotateMasterKey: true                                                                      
     port: 5696                                                                                  
     serverCAFile: /etc/mongodb-kmip/AKMRootCACertificate.pem                                    
     clientCertificateFile: /etc/mongodb-kmip/AKMAdminCertandKey.pem                           
     keyIdentifier: <UID>

See MongoDB documentation for more information on rolling the master key.

Chapter 6: Failover

AKM failover

MongoDB Enterprise Advanced does not support failover of the AKM server on the client side, as only one KMIP server may be added to the configuration. In order to support high availability failover of key servers, one option is to load balance a pair of mirrored AKM servers using a network load balancer.

There are a few compulsory prerequisites to using a load balancer:

NOTE: It is recommended that you configure bidirectional mirroring between all AKM servers to ensure key replication and availability. Please reference your platform specific deployment guide on how to configure bidirectional mirroring.

First initialize bidirectional mirroring between the primary and secondary AKM servers, You must use the bundled CA certificates that are created after initializing a secondary mirror server in your MongoDB installation.

Copy the AKM server certificate and private key from the primary AKM server to secondary and replace the server certificate and private key that already exist there. The server certificate can be found in /etc/akm/Certs and the server private key can be found in /etc/akm/PrivateKeys. Once in place, restart AKM on the secondary so that it loads the new server certificate. This will allow MongoDB to properly authenticate with both servers.

Once you have verified proper operation, you will need to edit your /etc/hosts and change the IP address (not hostname!) of your AKM server to the IP address of the load balancer and not the AKM server itself.

MongoDB failover and encryption

When employing a replica set, master keys (and database keys) are not replicated. See MongoDB documentation for more information.

Load Balancing

The following are some example scenarios that use a load balancer to allow connection to the failover key server. Load balancers are available in all platforms where MongoDB is supported (VMware, cloud, etc.). The goal of this section is to configure load balancing with AKM to eliminate business interruption in the event the primary node fails or, the key server for the primary node fails.

Scenario 1: A primary and one local secondary replication set

Shown below is a simple implementation of MongoDB that involves one primary node and one secondary node to provide for data recovery and high availability. In this scenario the secondary MongoDB node is deployed locally to the primary node. However, many MongoDB customers deploy the secondary node in a remote location to improve business recovery.

image alt text

NOTE: Redundancy and failover of the MongoDB should be handled by MongoDB itself.

The primary MongoDB node has a KMIP configuration that points to the load balancer. The load balancer itself is configured to connect to the primary key server and a failover key server. Here the failover key server is acting as the primary key server for the secondary MongoDB node. Meaning each key server functions as the primary key server for the local node, and as the failover key server for the other node. In the event the primary key server cannot be reached due to a network failure or a key server failure, the load balancer uses the secondary key server.

The result of this type of implementation is a fully redundant key server deployment to protect both the primary MongoDB node as well as a fully redundant key server deployment for the secondary MongoDB node.

Scenario 2: A primary and multiple secondary replication sets

This example outlines a more complex implementation with multiple secondary replication sets. This might be done to provide high performance for data ingestion (writes) into the primary node, while secondary nodes provide high performance query support and data redundancy. This type of scenario involves multiple nodes each with its own availability and recovery requirements. There can be many key managers involved in supporting this environment.

image alt text

This scenario also leverages the use of load balancers to provide for automatic failover to a secondary key server. See the notes above about load balancers.

Primary and secondary MongoDB nodes have KMIP configurations that point to a load balancer. The load balancers are configured to connect to the defined failover key server when needed. Note that the failover key server is a different key server on another MongoDB node. In this scenario each key server functions as the primary key server for the local node, and as the failover key server for the other node. In the event the primary key server cannot be reached due to a network failure or a key server failure, the load balancer uses the secondary key server.

The result of this type of implementation is a fully redundant key server deployment to protect both of the MongoDB nodes.

Scenario 3: Complex, geographically distributed nodes

In complex MongoDB deployments that involve many geographically dispersed nodes, the same principles can be used to create highly redundant and resilient key management services. In this case the key managers are mirroring encryption keys and access policy across geographically dispersed locations. An encryption key management server and its backup mirrored server are available in all regions.

image alt text

Here, the primary MongoDB node runs a primary and secondary server in order to ensure a high level of hot failover support. The remote MongoDB nodes also run a primary and secondary key server for the same reason - to provide the maximum availability of the secondary MongoDB databases. It is also important to note that this key server deployment leverages the ability of Alliance Key Manager to replicate keys to more than one additional key server.

In this example there may be many geographic regions that participate in the MongoDB replication group. Note that it is possible that multiple MongoDB nodes can share one set of key servers. There is no requirement that each MongoDB node needs to have its own key server.