Rotate Encryption Keys
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.
Note
Disambiguation
To roll over database keys configured with AES256-GCM cipher afer a
filesystem restore, see --eseDatabaseKeyRollover
instead.
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
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 as a 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, during its initial sync, the secondary still counts as a voting member even though it cannot serve reads nor become primary because its data is not yet consistent.This can lead to a case where a majority of the voting members are online but no primary can be elected. To avoid such situations, consider adding the new secondary initially with
priority :0
andvotes :0
. Then, once the member has transitioned intoSECONDARY
state, users.reconfig()
to update its priority and votes.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.
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, use
rs.reconfig()
to update the newly added secondary's vote and priority settings. See Add a Secondary to an Existing Replica Set for details: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 current primary to step down, which causes an election. When the primary steps down, themongod
closes all client connections. While this typically takes 10-20 seconds, try to make these changes during scheduled maintenance periods.Avoid reconfiguring replica sets that contain members of different MongoDB 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 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.
Restart the secondary, including the
--kmipRotateMasterKey
option. Include any other options specific to your configuration, such as--bind_ip
. 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
.Upon successful completion of the master key rotation and re-encryption of the database keystore, the
mongod
will exit.Restart the secondary without the
--kmipRotateMasterKey
parameter. Include any other options specific 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 the
security.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 an election of a new primary:rs.stepDown() When
rs.status()
shows that the primary has stepped down and another member has assumedPRIMARY
state, rotate the master key for the stepped down member:Restart the stepped-down member, including the
--kmipRotateMasterKey
option. Include any other options specific to your configuration, such as--bind_ip
. 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
.Upon successful completion of the master key rotation and re-encryption of the database keystore, the
mongod
will exit.Restart the stepped-down member without the
--kmipRotateMasterKey
option. Include any other options specific 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 the
security.kmip.rotateMasterKey
setting.