Configure Encryption
Overview
This page discusses server configuration to support encryption at rest. If you use MongoDB Atlas, your data is already encrypted. MongoDB manages Atlas encryption at the cloud provider level, but you can also use your own key management solution. See the Atlas key management documentation for details.
MongoDB Enterprise 3.2 introduces a native encryption option for the WiredTiger storage engine. Outside Atlas, encryption is only available for enterprise installations that use 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, other keys can be stored with your MongoDB instance.
MongoDB's encrypted storage engine supports two key management options for the master key:
Integration with a third party key management appliance via the Key Management Interoperability Protocol (KMIP). Recommended
Use of local key management via a keyfile.
Important
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.
Key Manager
MongoDB Enterprise supports secure transfer of keys with compatible key management appliances. Using a key manager allows for the keys to be stored in the key manager.
MongoDB Enterprise supports secure transfer of keys with Key Management Interoperability Protocol (KMIP) compliant key management appliances.
For a list of MongoDB's certified partners, refer to the Partners List.
Tip
Recommended
Using a key manager meets regulatory key management guidelines, such as HIPAA, PCI-DSS, and FERPA, and is recommended over the local key management.
Prerequisites
Your key manager must support the KMIP communication protocol.
The default KMIP protocol version is 1.2. You can configure MongoDB to use KMIP version 1.0 or 1.1 in the MongoDB server configuration file.
For an integration with a third-party key management appliance using the KMIP, you should allow the following KMIP operations:
Create (
operation_create
)Get (
operation_get
)Activate (
operation_activate
)
To authenticate MongoDB to a KMIP server, you must have a valid certificate issued by the key management appliance.
Note
MongoDB Enterprise on Windows no longer supports AES256-GCM
as a
block cipher for encryption at rest. This usage is only supported on Linux.
Encrypt Using a New Key
To create a new key when you connect to the key manager, use the
following options to start mongod
:
To connect to a version 1.0 or 1.1 KMIP server, use the
--kmipUseLegacyProtocol
option.
Include additional options as required for your configuration. For
instance, if you wish remote clients to connect to your deployment
or your deployment members are run on different hosts, specify the
--bind_ip
.
Important
Enabling encryption using a KMIP server on Windows fails when using
--kmipClientCertificateFile
and the KMIP server enforces TLS 1.2.
To enable encryption at rest with KMIP on Windows, you must:
Import the client certificate into the Windows Certificate Store.
Use the
--kmipClientCertificateSelector
option.
The following operation creates a new master key in your key manager.
mongod
uses the master key to encrypt the keys that mongod
generates for each database.
mongod --enableEncryption \ --kmipServerName <KMIP Server HostName> \ --kmipPort <KMIP server port> \ --kmipServerCAFile ca.pem \ --kmipClientCertificateFile client.pem
mongod
verifies the connection to the KMIP server on startup.
The server name specified in --kmipServerName
must match either the Subject Alternative
Name SAN
or the Common Name CN
on the certificate presented by
the KMIP server. SAN
can be a system name or an IP address.
If SAN
is present, mongod
does not try to match against CN
.
If the hostname or IP address of the KMIP server does does not match
either SAN
or CN
, mongod
does not start.
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>
Encrypt Using an Existing Key
You can use an existing master key that your KMIP server already
manages. To use an existing key, use these options when you start
mongod
to connect mongod
to the key manager:
To connect to a version 1.0 or 1.1 KMIP server, use the
--kmipUseLegacyProtocol
option.
Include additional options as required for your configuration. For
instance, if you wish remote clients to connect to your deployment
or your deployment members are run on different hosts, specify the
--bind_ip
.
mongod --enableEncryption \ --kmipServerName <KMIP Server HostName> \ --kmipPort <KMIP server port> \ --kmipServerCAFile ca.pem \ --kmipClientCertificateFile client.pem \ --kmipKeyIdentifier <UID>
mongod
verifies the connection to the KMIP server on startup.
The server name specified in --kmipServerName
must match either the Subject Alternative
Name SAN
or the Common Name CN
on the certificate presented by
the KMIP server. SAN
can be a system name or an IP address.
If SAN
is present, mongod
does not try to match against CN
.
If the hostname or IP address of the KMIP server does does not match
either SAN
or CN
, mongod
does not start.
Local Key Management
Important
Using the keyfile method does not meet most regulatory key management guidelines and requires users to securely manage their own keys.
The safe management of the keyfile is critical.
To encrypt using a keyfile, you must have a base64 encoded keyfile that
contains a single 16 or 32 character string. The keyfile must only be
accessible by the owner of the mongod
process.
Create the base64 encoded keyfile with the 16 or 32 character string. You can generate the encoded keyfile using any method you prefer. For example,
openssl rand -base64 32 > mongodb-keyfile Update the file permissions.
chmod 600 mongodb-keyfile To use the key file, start
mongod
with the following options:--enableEncryption
,--encryptionKeyFile <path to keyfile>
,
mongod --enableEncryption --encryptionKeyFile mongodb-keyfile Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the
--bind_ip
.Verify if the encryption key manager successfully initialized with the keyfile. If the operation was successful, the process will log the following message:
[initandlisten] Encryption key manager initialized with key file: <path to keyfile>
Encrypt Existing Data at Rest
MongoDB cannot encrypt existing data. When you enable encryption with a new key, the MongoDB instance cannot have any pre-existing data.
If you are using a replica set that does have existing data, use a rolling initial sync to encrypt the data.
For example, consider a replica set with three members. The replica set is in use and holds data that you want to encrypt. These are the steps you would take to encrypt the data at rest:
Prepare a server.
Follow these steps to prepare the server:
Pick one of the secondary servers.
Stop
mongod
on the secondary server.Optional: Backup the data in
dbPath
. If a full backup is not required, consider backing up just thediagnostic.data
directory to preserve potentially-useful troubleshooting data in the event of an issue. See Full Time Diagnostic Data Capture for more information.Remove the files and directories in the
dbPath
.
Enable encryption.
Start the secondary server with encryption enabled. The mongod
instance creates
a new keystore.
Synchronize the data.
Import the data from the primary. Start the mongod process, specifying Replication Options as appropriate.
mongod
performs an initial sync and encrypts the data
during the sync up process.
Repeat the process on the secondaries.
When the first secondary has finished importing and encrypting the
data, repeat the process on the other secondary
mongod
instances.
Encrypt the primary.
When the all the secondaries have been encrypted, step down
the primary. Eligible secondaries will elect a new
primary.
The old primary is now a secondary. Repeat the steps to remove the unencrypted data and then run an initial sync.