Configure Encryption¶

On this page

Overview
Key Manager
Local Key Management

New in version 3.2.

Overview¶

Enterprise Feature

Available in MongoDB Enterprise only.

Important

Available for the WiredTiger Storage Engine Only.

Changed in version 4.0

MongoDB Enterprise on Windows no longer supports AES256-GCM. This cipher is now available only on Linux.

MongoDB Enterprise 3.2 introduces a native encryption option for the WiredTiger storage engine. With storage encryption, the secure management of the encryption keys is critical.

Only the master key is external to the server and requires external management. To manage the master key, MongoDB’s encrypted storage engine supports two key management options:

Integration with a third party key management appliance via the Key Management Interoperability Protocol (KMIP). Recommended
Use of local key management via a keyfile.

The following tutorial outlines the procedures to configure MongoDB for encryption and key management.

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. Any appliance vendor that provides support for KMIP is expected to be compatible.

For a list of MongoDB’s certified partners, refer to the Partners List. To view security partners, select “Security” from the Technology filter, and “Certified” from the Certified filter.

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.
To authenticate MongoDB to a KMIP server, you must have a valid certificate issued by the key management appliance.

Encrypt Using a New Key¶

To create a new key, connect mongod to the key manager by starting mongod with the following options:

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. For more information, see Localhost Binding Compatibility Changes.

The following operation creates a new master key in your key manager which mongod uses to encrypt the keys mongod generates for each database.

copy

mongod --enableEncryption --kmipServerName <KMIP Server HostName> \
  --kmipPort <KMIP server port> --kmipServerCAFile ca.pem \
  --kmipClientCertificateFile client.pem

When connecting to the KMIP server, the 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. [1] If SAN is present, mongod does not match against the CN. If the hostname does not match the SAN (or CN), the mongod will fail to connect.

To verify that the key creation and usage was successful, check the log file. If successful, the process will log the following messages:

copy

[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 your KMIP server created and manages. To use an existing key, connect mongod to the key manager by starting mongod with the following options:

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. For more information, see Localhost Binding Compatibility Changes.

copy

mongod --enableEncryption --kmipServerName <KMIP Server HostName> \
  --kmipPort <KMIP server port> --kmipServerCAFile ca.pem \
  --kmipClientCertificateFile client.pem --kmipKeyIdentifier <UID>

When connecting to the KMIP server, the 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. [1] If SAN is present, mongod does not match against the CN. If the hostname does not match the SAN (or CN), the mongod will fail to connect.

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,
copy
```
openssl rand -base64 32 > mongodb-keyfile
```
Update the file permissions.
copy
```
chmod 600 mongodb-keyfile
```
To use the key file, start mongod with the following options:
- --enableEncryption,
- --encryptionKeyFile <path to keyfile>,
copy
```
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. For more information, see Localhost Binding Compatibility Changes.
Verify if the encryption key manager successfully initialized with the keyfile. If the operation was successful, the process will log the following message:
copy
```
[initandlisten] Encryption key manager initialized with key file: <path to keyfile>
```