Configure Encryption

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. Thiscipher is now available only on Linux.

MongoDB Enterprise 3.2 introduces a native encryption option for theWiredTiger storage engine. With storage encryption, the securemanagement of the encryption keys is critical.

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

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

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

Key Manager

MongoDB Enterprise supports secure transfer of keys with compatible keymanagement appliances. Using a key manager allows for the keys to bestored in the key manager.

MongoDB Enterprise supports secure transfer of keys with Key ManagementInteroperability Protocol (KMIP) compliant key management appliances.Any appliance vendor that provides support for KMIP is expectedto be compatible.

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

Recommended

Using a key manager meets regulatory key management guidelines, suchas HIPAA, PCI-DSS, and FERPA, and is recommended over the local keymanagement.

Prerequisites

  • Your key manager must support the KMIP communication protocol.
  • To authenticate MongoDB to a KMIP server, you must have a validcertificate issued by the key management appliance.

Encrypt Using a New Key

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

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

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

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

When connecting to the KMIP server, the mongod verifiesthat the specified —kmipServerNamematches the Subject Alternative Name SAN (or, if SAN is notpresent, the Common Name CN) in the certificate presented by theKMIP server. [1] If SAN is present, mongod doesnot match against the CN. If the hostname does not match theSAN (or CN), the mongod will fail to connect.

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

  1. [initandlisten] Created KMIP key with id: <UID>
  2. [initandlisten] Encryption key manager initialized using master key with id: <UID>

See also

Encryption Key Management Options

Encrypt Using an Existing Key

You can use an existing master key your KMIP server created andmanages. To use an existing key, connect mongod to thekey manager by starting mongod with the following options:

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

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

When connecting to the KMIP server, the mongod verifiesthat the specified —kmipServerNamematches the Subject Alternative Name SAN (or, if SAN is notpresent, the Common Name CN) in the certificate presented by theKMIP server. [1] If SAN is present, mongod does notmatch against the CN. If the hostname does not match the SAN(or CN), the mongod will fail to connect.

See also

Encryption Key Management Options

[1](1, 2) Starting in MongoDB 4.2, when performing comparison of SAN, MongoDBsupports comparison of DNS names or IP addresses. In previous versions,MongoDB only supports comparisons of DNS names.

Local Key Management

Important

Using the keyfile method does not meet most regulatory keymanagement guidelines and requires users to securely manage theirown keys.

The safe management of the keyfile is critical.

To encrypt using a keyfile, you must have a base64 encoded keyfile thatcontains a single 16 or 32 character string. The keyfile must only beaccessible by the owner of the mongod process.

  • Create the base64 encoded keyfile with the 16 or 32 characterstring. You can generate the encoded keyfile using any method youprefer. For example,
  1. openssl rand -base64 32 > mongodb-keyfile
  • Update the file permissions.
  1. chmod 600 mongodb-keyfile

  • To use the key file, start mongod with the followingoptions:

    • —enableEncryption,
    • —encryptionKeyFile <path to keyfile>,
  1. mongod --enableEncryption --encryptionKeyFile  mongodb-keyfile

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

  • Verify if the encryption key manager successfully initialized withthe keyfile. If the operation was successful, the process will log thefollowing message:
  1. [initandlisten] Encryption key manager initialized with key file: <path to keyfile>

See also

Encryption Key Management Options