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.1. Customers using MongoDB will create a new key on AKM using the KMIP interface. This encryption key is then used 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”. Administrative certificates allow the database to create and retrieve keys using the KMIP interface.

Client applications and SDKs

Townsend Security provides the following applications and SDKs to assist with client-side key retrieval or remote encryption:

  • Key Connection for SQL Server: Microsoft Extensible Key Management Provider for Transparent Data Encryption (TDE) and cell level encryption
  • Windows SDK for .NET applications
  • SQL Server UDF for all editions of SQL Server
  • Key Connection for Drupal
  • Key Connection for Encryptionizer

In addition to these offerings, Townsend Security provides software libraries and code samples to assist with custom implementations. Visit this page for a current list of client applications, software libraries, and code samples.

Other resources

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


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 5/24/2016 Initial release. 2/6/2017 Expanded HA section 2/20/2017 Fixed UID secion 9/25/2018 Added load balancing failover scenarios 11/8/2019 Updated links and references to technical information. 8/14/2020 Updated preparation and integration process.

Chapter 2: Preparation

You will need to complete the following steps before continuing:

  • Ensure that MongoDB is at least MongoDB Enterprise Edition (version 3.2+).

  • Install and set up Alliance Key Manager (version 4.6+) (instructions are located in platform specific deployment guides)

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

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.


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)

  • Admin (Crypto Officer) certificate and private key (AKMAdminCertificateAndPrivateKey.pem)

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.

NOTE: You may get a “host name does not match SAN” error when using the default generated certificates. If you see this error you will need to manually generate a new set of admin certificates that include the host name in the subject alterantive name (SAN). To generate new certificates see the Server Management Guide

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)


Chapter 3: 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,,,,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/*


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:

   enableEncryption: true                                                                        
     serverName: akmmongo                                                                        
     port: 5696                                                                                  
     serverCAFile: /etc/mongodb-kmip/AKMRootCACertificate.pem                                    
     clientCertificateFile: /etc/mongodb-kmip/AKMAdminCertificateAndPrivateKey.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 using the following command.

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

Once you have run this command, 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,,,,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


Chapter 4: Rolling the Master Key

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

   enableEncryption: true                                                                        
     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.