Data at Rest Encryption¶
Data at rest encryption for the WiredTiger storage engine in MongoDB was introduced in MongoDB Enterprise version 3.2 to ensure that encrypted data files can be decrypted and read by parties with the decryption key.
- MongoDB Documentation: Encryption at Rest
Differences from Upstream
The data encryption at rest in Percona Server for MongoDB is introduced in version 3.6 to be compatible with data encryption at rest interface in MongoDB. In the current release of Percona Server for MongoDB, the data encryption at rest does not include support for KMIP, or Amazon AWS key management services.
HashiCorp Vault Integration
Starting from version 4.0.10, Percona Server for MongoDB provides HashiCorp Vault integration. We only support the HashiCorp Vault backend with KV Secrets Engine - Version 2 (API) with versioning enabled.
How to configure the KV Engine: https://www.vaultproject.io/api/secret/kv/kv-v2.html
|command line||config file||Type|
The vault token file consists of the raw vault token and does not include any additional strings or parameters.
On start server tries to read the master key from the Vault. If the configured secret does not exist, Vault responds with HTTP 404 error. During the first run of the Percona Server for MongoDB the process generates a secure key and writes the key to the vault.
Encrypting Rollback Files
Starting from version 3.6, Percona Server for MongoDB also encrypts rollback files when data at rest encryption is enabled. To inspect the contents of these files, use perconadecrypt. This is a tool that you run from the command line as follows:
$ perconadecrypt --encryptionKeyFile FILE --inputPath FILE --outputPath FILE [--encryptionCipherMode MODE]
When decrypting, the cipher mode must match the cipher mode which was used for
the encryption. By default, the
--encryptionCipherMode option uses the
Parameters of perconadecrypt
|–encryptionKeyFile||The path to the encryption key file|
|–encryptionCipherMode||The cipher mode for decryption. The supported values are AES256-CBC or AES256-GCM|
|–inputPath||The path to the encrypted rollback file|
|–outputPath||The path to save the decrypted rollback file|
Important Configuration Options
Percona Server for MongoDB supports the
encryptionCipherMode option where you choose one of the
following cipher modes:
By default, the AES256-CBC cipher mode is applied. The following example demonstrates how to apply the AES256-GCM cipher mode when starting the mongod service:
$ mongod ... --encryptionCipherMode AES256-GCM
- MongoDB Documentation: encryptionCipherMode Option
Percona Server for MongoDB also supports the options exposed by the upstream solution:
--enableEncryptionto enable data at rest encryption
--encryptionKeyFileto specify the path to a file that contains the encryption key
$ mongod ... --enableEncryption --encryptionKeyFile <fileName>
The key file must contain a 32 character string encoded in base64. You can generate a random key and save it to a file by using the openssl command:
$ openssl rand -base64 32 > mongodb-keyfile
Then, as the owner of the
mongod process, update the file permissions: only
the owner should be able to read and modify this file. The effective permissions
specified with the
chmod command can either be 600 (only the owner may
read and modify the file) or 400 (only the owner may read the file.)
$ chmod 600 mongodb-keyfile
mongod is started with the
--relaxPermChecks option and the key file
is owned by
mongod can read the file based on the
group bit set accordingly. The effective key file permissions in this
case are either 440 (both the owner and the group can only read the file) or
640 (only the owner can read and the change the file, the group can only
read the file).
- MongoDB Documentation: Configure Encryption
All these options can be specified in the configuration file:
security: enableEncryption: <boolean> encryptionCipherMode: <string> encryptionKeyFile: <string> relaxPermChecks: <boolean> .. admonition:: Key Rotation
To rotate the keys for a single mongod instance, do the following:
- Stop mongod process
--vaultRotateMasterKeyto the command line options or
security.vault.rotateMasterKeyto the config file.
- Run the mongod process with the selected option, the process will perform the key rotation and exit.
- Remove the selected option from the startup command or the config file.
- Start mongod again.
Rotating the master key process also re-encrypts the keystore using the new master key. The new master key is stored in the vault. The entire dataset is not re-encrypted.
For a replica set, do the following steps:
- Rotate the master key for the secondary nodes one by one.
- Step down the primary and wait for another primary to be elected.
- Rotate the master key for the previous primary node.
- MongoDB Documentation: How to set options in a configuration file