Configure encryption in MongoDB
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.
To integrate by using a new key, perform the following instructions to enable encryption and confirm the master key on the KMES.
Run the following command to create the directory /data/db to store the data directory files:
Run the following command to set the current user as the owner of the /data/db directory.
Run the following command to remove the MongoDB .sock file from the /tmp directory if one exists.
Run the following command to create a new master key on the KMES Series 3, which mongod uses to encrypt the keys mongod generates for each database.
The file you specify in the --kmipClientCertificateFile flag must contain both the signed MongoDB certificate and its associated private key.
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:
Log in to the KMES Series 3 application interface with the default admin identities.
Go to Key Management > Keys.
Select the default key group to view the AES-256 key that MongoDB created through KMIP.
To integrate by using an existing key, perform the following instructions to generate a master key and enable encryption.
Log in to the KMES Series 3 application interface with the default admin identities.
Go to Key Management > Keys.
Select [ Create ] in the Key Groups section.
Select Symmetric as the Key Type and HSM Protected for the Storage Location.
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 ].
Select the key group you just created and, in the Keys section, select [ Create ] and select [ Random ].
Specify a name for the key and select [ OK ].
Run the following command to create the directory /data/db to store the data directory files:
Run the following command to set the current user as the owner of the /data/db directory:
Run the following command to remove the MongoDB .sock file from the /tmp directory if one exists:
Run the following command to start MongoDB by using the existing key on the KMES Series 3, which mongod uses to encrypt the keys mongod generates for each database:
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.
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: