Data Encryption in Percona Server for MongoDB

Percona Server for MongoDB supports Transparent Data Encryption (TDE) — all data written to disk is automatically encrypted. This protects data against physical disk access and helps meet HIPAA, PCI-DSS, GDPR, and FIPS requirements.

info

Data-at-rest encryption was first introduced in Percona Server for MongoDB 3.6 and is fully compatible with the MongoDB Enterprise encryption interface. See the official Percona documentation for details.

How Encryption Works

Percona Server for MongoDB uses a two-level key hierarchy:

1. Database keys — each data file is encrypted with a separate key. Keys are stored in an internal "key database" alongside the data.
2. Master key — encrypts the key database. Stored separately from data and managed through an external key management system (KMS).

Each replica set member uses the same master key to encrypt the key database.

caution

Encryption can only be enabled on an empty database during the first mongod startup. You cannot enable or disable encryption on a server with existing data.

If you need to add encryption to a running database, use replication-based migration — a new server is set up with encryption, syncs data, and replaces the old one. The full procedure is described in Migration from MongoDB Community to Percona Server.

Key Management Options

Percona Server for MongoDB supports the following key management systems (KMS):

System	Description	Recommendation
HashiCorp Vault	External key server with KV Secrets Engine v2 support	✅ Recommended for production
Local keyfile	Key file stored on the server itself	For testing and small deployments

Only one key management option can be used at a time. Switching between options is possible — for example, from local keyfile to Vault. See the Percona Vault documentation for details.

Configuring Encryption with Local Keyfile

Local keyfile is suitable for testing and small deployments. The key is stored in a file on the server.

Key Generation

Generate a random key (32 bytes, base64-encoded) and save it to a file:

openssl rand -base64 32 > /etc/mongodb-encryption-keyfile
chown mongod:mongod /etc/mongodb-encryption-keyfile
chmod 600 /etc/mongodb-encryption-keyfile

info

Make sure the key owner matches the user running mongod. If mongod runs as a different user, replace mongod:mongod with the appropriate value.

tip

Store the mongodb-encryption-keyfile in a protected location, such as an encrypted partition or encrypted container, and restrict access with 600 permissions.

Configuration

Add encryption parameters to /etc/mongod.conf:

security:
  enableEncryption: true
  encryptionKeyFile: /etc/mongodb-encryption-keyfile

For a full list of local keyfile parameters, see the Percona documentation.

Starting the Server

systemctl enable mongod.service
systemctl start mongod.service
systemctl status mongod.service

Configuring Encryption with HashiCorp Vault

HashiCorp Vault is the recommended option for production deployments. Vault stores the master key separately from database servers and supports key rotation.

Requirements

• HashiCorp Vault (version 1.9+)
• KV Secrets Engine v2 with versioning enabled
• TLS certificate for secure connection

Vault Setup

Create an access policy for Percona Server for MongoDB on the Vault server:

path "secret/data/*" {
  capabilities = ["create", "read", "update", "delete"]
}
path "secret/metadata/*" {
  capabilities = ["read"]
}
path "secret/config" {
  capabilities = ["read"]
}

Generate a Vault token with this policy and save it to a file:

echo "<vault-token>" > /etc/mongodb-vault-token
chown mongod:mongod /etc/mongodb-vault-token
chmod 600 /etc/mongodb-vault-token

Configuration

Instead of the local encryptionKeyFile, specify Vault parameters in /etc/mongod.conf:

security:
  enableEncryption: true
  vault:
    serverName: <vault-server>
    port: 8200
    tokenFile: /etc/mongodb-vault-token
    secret: secret/data/mongodb/<node-name>
    serverCAFile: /etc/ssl/certs/vault-ca.crt

Vault Parameters

Parameter	Description
security.vault.serverName	IP address or hostname of the Vault server
security.vault.port	Vault port (default 8200)
security.vault.tokenFile	Path to the Vault token file
security.vault.secret	Secret path in Vault: <mount_path>/data/<custom_path>
security.vault.serverCAFile	Path to the Vault TLS certificate
security.vault.secretVersion	(Optional) Secret version in Vault

Starting the Server

On first startup, Percona Server for MongoDB generates a master key and stores it in Vault:

systemctl start mongod.service

Key Rotation

Key rotation replaces the old master key with a new one. This helps meet regulatory requirements.

caution

Master key rotation is only supported with HashiCorp Vault. With a local keyfile, rotation is not possible — replacing the key will make the database unreadable.

Rotation with HashiCorp Vault

For a standalone node:

1. Stop mongod:

   systemctl stop mongod

2. Add the rotation parameter to /etc/mongod.conf:

   security:
     vault:
       rotateMasterKey: true

3. Start mongod — the process performs rotation and exits:

   systemctl start mongod

4. Remove rotateMasterKey from the configuration.
5. Start mongod again:

   systemctl start mongod

Rotation in a Replica Set

In a replica set, perform rotation in order:

1. Rotate on each secondary node one at a time.
2. Step down the primary and wait for a new primary election.
3. Rotate on the former primary node.

info

The rotation process re-encrypts the key database with the new master key. The entire dataset is not re-encrypted.

Verifying Encryption

Check startup parameters:

mongosh --eval "db.serverCmdLineOpts()" | grep -A 5 encryption

Parameters should include enableEncryption: true.

Check the key file:

ls -la /etc/mongodb-encryption-keyfile

If using Vault, check Vault parameters:

mongosh --eval "db.serverCmdLineOpts()" | grep -A 10 vault

Ensure there are no encryption-related errors in the logs:

grep -i encryption /var/log/mongodb/mongod.log