Rotate Encryption Keys
- Rotate a Member of Replica Set
- KMIP Master Key Rotation

Rotate Encryption Keys

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

Disambiguation

To roll over database keys configured with AES256-GCM cipher afer afilesystem restore, see —eseDatabaseKeyRollover instead.

MongoDB provides two options for key rotation. You can rotate out thebinary with a new instance that uses a new key. Or, if you are using aKMIP 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 aswell as any other options specific to your configuration, such as—dbpath and —bind_ip.

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, initially adding the member asa non-voting, priority 0 member:

rs.add( { host: <host:port>, priority: 0, votes: 0 } )

Tip

When a newly added secondary has its votes andpriority settings greater than zero, duringits initial sync, the secondary still counts as a voting member eventhough it cannot serve reads nor become primary because its data isnot yet consistent.

This can lead to a case where a majority of the voting members areonline but no primary can be elected. To avoid such situations,consider adding the new secondary initially withpriority :0 and votes :0. Then, once the member has transitioned intoSECONDARY state, use rs.reconfig() to update itspriority and votes.

During the initial sync process, the re-encryption of the data withan entirely new set of database keys as well as a new system keyoccurs.

Ensure that the new member has reached SECONDARY state.To check the state of the replica set members, runrs.status():

rs.status()

Once the new node completes its initial sync process, users.reconfig() to update the newly added secondary’s vote andpriority settings. See Add a Secondary to an Existing Replica Set fordetails:

var cfg = rs.conf();
 
cfg.members[n].priority = 1;  // Substitute the correct array index for the new member
cfg.members[n].votes = 1;     // Substitute the correct array index for the new member
 
rs.reconfig(cfg)

where n is the array index of the new member in themembers array.

Warning

The rs.reconfig() shell method can force the currentprimary to step down, which causes an election. When the primary steps down, themongod closes all client connections. While thistypically takes 10-20 seconds, try to make these changes duringscheduled maintenance periods.
Avoid reconfiguring replica sets that contain members of differentMongoDB versions as validation rules may differ across MongoDB versions.

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 rotatethe master key, the only externally managed key. With the newmaster key, the internal keystore will be re-encrypted but thedatabase keys will be otherwise left unchanged. This obviates the needto re-encrypt the entire data set.

Rotate the master key for the secondary members of the replica set one at atime.
- Restart the secondary, including the—kmipRotateMasterKey option. Include any otheroptions specific to your configuration, such as —bind_ip. Ifthe member already includes the —kmipKeyIdentifieroption, either update the —kmipKeyIdentifier optionwith the new key to use or omit to request a new key from theKMIP server:

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

If using a configuration file, include thesecurity.kmip.rotateMasterKey.

Upon successful completion of the master key rotation andre-encryption of the database keystore, the mongodwill exit.
Restart the secondary without the —kmipRotateMasterKeyparameter. Include any other options specific to yourconfiguration, such as —bind_ip.

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

If using a configuration file, remove thesecurity.kmip.rotateMasterKey setting.

Step down the replica set primary.

Connect a mongo shell to the primary and users.stepDown() to step down the primary and force anelection of a new primary:

rs.stepDown()

When rs.status()shows that the primary has stepped down and another memberhas assumed PRIMARY state, rotate the master key for the stepped down member:
- Restart the stepped-down member, including the—kmipRotateMasterKey option. Include any otheroptions specific to your configuration, such as —bind_ip. If the member alreadyincludes the —kmipKeyIdentifier option, either updatethe —kmipKeyIdentifier option with the new key to useor omit.

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

If using a configuration file, include thesecurity.kmip.rotateMasterKey.

Upon successful completion of the master key rotation andre-encryption of the database keystore, the mongodwill exit.
Restart the stepped-down member without the—kmipRotateMasterKey option. Include any other optionsspecific to your configuration, such as —bind_ip.

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

If using a configuration file, remove thesecurity.kmip.rotateMasterKey setting.