Skip to main content
This section discusses server configuration to support encryption at rest in MongoDB. MongoDB Enterprise 3.2 introduces a native encryption option for the WiredTiger storage engine. Secure management of the encryption keys is a critical requirement for storage encryption. MongoDB uses a master key that is not stored with the MongoDB installation. Only the master key is externally managed, and you can store other keys with your MongoDB instance. The MongoDB encrypted storage engine supports two key management options for the master key:
  • Use of local key management through a key file.
  • Integration with a third-party key management appliance (such as the KMES Series 3) through the Key Management Interoperability Protocol (KMIP). Recommended
MongoDB cannot encrypt existing data. When you enable encryption with a new key, the MongoDB instance cannot have any pre-existing data. If your MongoDB installation already has existing data, see Encrypt Existing Data at Rest for additional steps.
Changed in version 4.0:MongoDB Enterprise on Windows no longer supports AES256-GCM. This cipher is now available only on Linux.
The following sections cover integration with either a new key or an existing key.

​
Integrate by using a new key

To integrate by using a new key, perform the following instructions to enable encryption and confirm the master key on the KMES.

​
Start the MongoDB server and enable encryption

Perform the following steps to start the MongoDB server and enable encryption by generating a new key on the KMES through KMIP:
1
Run the following command to create the directory /data/db to store the data directory files:
Shell
sudo mkdir -p /data/db/
2
Run the following command to set the current user as the owner of the /data/db directory.
Shell
sudo chown -R $USER:$USER /data/db
3
Run the following command to remove the MongoDB .sock file from the /tmp directory if one exists.
Shell
sudo rm /tmp/mongodb-27017.sock
4
Run the following command to create a new master key on the KMES Series 3, which the command (www.mongodb.com/docs/manual/reference/program/mongod/#mongodb-binary-bin.mongod) uses to encrypt the keys it generates for each database.
Shell
mongod --dbpath /data/db --enableEncryption --kmipServerName <KMES-IP> --kmipPort 5696 --kmipServerCAFile root-ca-cert.pem --kmipClientCertificateFile mongodb-cert-and-privatekey.pem --port 27018
The file you specify in the —kmipClientCertificateFile flag must contain both the signed MongoDB certificate and its associated private key.
5
When connecting to the KMIP server, mongod verifies that the specified --kmipServerName matches the Subject Alternative Name (SAN) (or, if SAN is not present, the Common Name (CN)) in the certificate presented by the KMIP server. If SAN is present, mongod does not match against the CN. If the hostname does not match the SAN (or CN), mongod fails to connect.To verify that the key creation and usage succeeded, check the log file. If successful, the process logs the following messages:
Shell
[initandlisten] Created KMIP key with id: <UID>
[initandlisten] Encryption key manager initialized using master key with id: <UID>

​
View the master key MongoDB created on the KMES

1
Log in to the KMES Series 3 application interface with the default admin identities.
2
Go to Key Management > Keys.
3
Select the default key group to view the AES-256 key that MongoDB created through KMIP.

​
Integrate using an existing key

To integrate by using an existing key, perform the following instructions to generate a master key and enable encryption.

​
Generate a key

Perform the following steps to generate a key on the KMES for MongoDB to use as its master key:
1
Log in to the KMES Series 3 application interface with the default admin identities.
2
Go to Key Management > Keys.
3
Select [ Create ] in the Key Groups section.
4
Select Symmetric as the Key Type and HSM Protected for the Storage Location.
5
In the HSM Protected Key Group window, specify a name for the Key Group. In the Service drop-down menu, select Key Management Interoperability Protocol. Change the Key Length to AES-256 and select [ OK ].
6
Select the key group you just created and, in the Keys section, select [ Create ] and select [ Random ].
7
Specify a name for the key and select [ OK ].

​
Start the MongoDB server and enable encryption

Perform the following steps to start the MongoDB server and enable encryption by using the existing key on the KMES:
1
Run the following command to create the directory /data/db to store the data directory files:
Shell
sudo mkdir -p /data/db/
2
Run the following command to set the current user as the owner of the /data/db directory:
Shell
sudo chown -R $USER:$USER /data/db
3
Run the following command to remove the MongoDB .sock file from the /tmp directory if one exists:
Shell
sudo rm /tmp/mongodb-27017.sock
4
Run the following command to start MongoDB by using the existing key on the KMES Series 3, which the command (www.mongodb.com/docs/manual/reference/program/mongod/#mongodb-binary-bin.mongod) uses to encrypt the keys it generates for each database:
Shell
mongod --dbpath /data/db --enableEncryption --kmipServerName <KMES-IP> --kmipPort 5696 --kmipServerCAFile root-ca-cert.pem --kmipClientCertificateFile mongodb-cert-and-privatekey.pem --port 27018 --kmipKeyIdentifier <UID>
The file you specify in the --kmipClientCertificateFile flag must contain both the signed MongoDB certificate and its associated private key.The UID value you specify in the --kmipKeyIdentifier flag needs to be the name of the key that was created on the KMES in the previous subsection.
5
When connecting to the KMIP server,mongod verifies that the specified --kmipServerName matches the Subject Alternative Name (SAN) (or, if SAN is not present, the Common Name (CN)) in the certificate presented by the KMIP server. If SAN is present, mongod does not match against the CN. If the hostname does not match the SAN (or CN), mongod fails to connect.To verify that the key usage succeeds, check the log file. If successful, the process logs the following message:
Shell
[initandlisten] Encryption key manager initialized using master key with id: <UID>