Rotate Encryption Keys¶

On this page

Most regulatory requirements mandate that a managed key used to decrypt sensitive data must be rotated out and replaced with a new key once a year.

MongoDB provides two options for key rotation. You can rotate out the binary with a new instance that uses a new key. Or, if you are using a KMIP server for key management, you can rotate the master key.

Rotate a Member of Replica Set¶

For a replica set, to rotate out a member:

Start a new mongod instance, configured to use a new key. Include the --replSet option with the name of the replica set as well as any other options specific to your configuration, such as --dbpath.
```
mongod --replSet myReplSet --enableEncryption --kmipServerName
<KMIP Server HostName> \ --kmipServerCAFile ca.pem
--kmipClientCertificateFile client.pem
```
Connect a mongo shell to the replica set’s primary.
Add the instance to the replica set.
```
rs.add("<hostname>:<port>")
```
During the initial sync process, the re-encryption of the data with an entirely new set of database keys as well as a new system key occurs.
Once the new node completes its initial sync process, remove the old node from the replica set and delete all its data. For instructions, see Remove Members from Replica Set

KMIP Master Key Rotation¶

If you are using a KMIP server for key management, you can rotate the master key, the only externally managed key. With the new master key, the internal keystore will be re-encrypted but the database keys will be otherwise left unchanged. This obviates the need to re-encrypt the entire data set.

Rotate the master key for the secondary members of the replica set one at a time.
1. Restart the secondary, including the --kmipRotateMasterKey parameter. Include any other options specific to your configuration. If the member already includes the --kmipKeyIdentifier option, either update the --kmipKeyIdentifier option with the new key to use or omit to request a new key from the KMIP server:
```
mongod --enableEncryption --kmipRotateMasterKey \
  --kmipServerName <KMIP Server HostName> \
  --kmipServerCAFile ca.pem --kmipClientCertificateFile client.pem
```
  If using a configuration file, include the security.kmip.rotateMasterKey.
2. Upon successful completion of the master key rotation and re-encryption of the database keystore, the mongod will exit.
3. Restart the secondary without the --kmipRotateMasterKey parameter. Include any other options specific to your configuration.
```
mongod --enableEncryption --kmipServerName <KMIP Server HostName> \
  --kmipServerCAFile ca.pem --kmipClientCertificateFile client.pem
```
  If using a configuration file, remove the security.kmip.rotateMasterKey setting.
Step down the replica set primary.

Connect a mongo shell to the primary and use rs.stepDown() to step down the primary and force an election of a new primary:
```
rs.stepDown()
```
When rs.status() shows that the primary has stepped down and another member has assumed PRIMARY state, rotate the master key for the stepped down member:
1. Restart the stepped-down member, including the --kmipRotateMasterKey parameter. Include any other options specific to your configuration. If the member already includes the --kmipKeyIdentifier option, either update the --kmipKeyIdentifier option with the new key to use or omit.
```
mongod --enableEncryption --kmipRotateMasterKey \
  --kmipServerName <KMIP Server HostName> \
  --kmipServerCAFile ca.pem --kmipClientCertificateFile client.pem
```
  If using a configuration file, include the security.kmip.rotateMasterKey.
2. Upon successful completion of the master key rotation and re-encryption of the database keystore, the mongod will exit.
3. Restart the stepped-down member without the --kmipRotateMasterKey parameter. Include any other options specific to your configuration.
```
mongod --enableEncryption --kmipServerName <KMIP Server HostName> \
  --kmipServerCAFile ca.pem --kmipClientCertificateFile client.pem
```
  If using a configuration file, remove the security.kmip.rotateMasterKey setting.

← Configure Encryption Auditing →