Rotating an encryption key

The keyrotate tool uses the primary encryption key to re-encrypt database secure data that was encrypted with other keys.

By default, the tool runs in a dry-run mode such that the database is not modified, and the tool only demonstrates the changes.

An extra flag is required to cause the tool to carry out the changes. This tool requires a significant amount of time to run. Running the tool in the mode that carries out changes might take much longer than the dry-run mode.

The keyrotate tool can run while the server is online. In an HA cluster, you must run the tool on only one cluster member.

The tool cannot detect if all members of an HA cluster are using the same primary key. If some servers are using different keys, the tool cannot guarantee that all data has been re-encrypted with the current primary key. To resolve this, update the misconfigured cluster members and re-run the tool by using the following procedure:

Edit the installed.properties file and set the encryption.keystore.alias property to the correct alias.

In an HA cluster, each member has its own installed.properties file, so each must be edited individually.
Restart the updated server.

The server loads keys and the primary key setting only at startup. In an HA cluster, you must restart each updated member.

To rotate a secure property encryption key:

Create and configure a new primary encryption key. See Creating an encryption key for the procedure.
Run the keyrotate command without the --change-database argument to verify that the encryption key is rotating.
Running the keyrotate tool without any argument only demonstrates the changes without completing the action. It takes some time. In an HA cluster, all members share the same database, so you must run the keyrotate tool on only one cluster member.
Run keyrotate again with the --change-database argument to rotate the encryption key.
Running the keyrotate tool with the --change-database flag enables modification of the database. This might take much longer than the previous step as writes are typically slower than reads. In an HA cluster, all members share the same database, so you must run the keyrotate tool on only one cluster member.

You can also use the --workers N argument. It sets the number of concurrent workers. The default value is 2, and the minimum required value is 1. The database must accept N+1 concurrent connections. Values greater than 8 might not reduce tool execution time.
Note: For best results, do not delete previous keys. You might require them to decrypt older data that was encrypted with the previous keys. See Deleting an encryption key for the procedure and an explanation for why this is not recommended.