Rotating an encryption key

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

About this task

You can run the keyrotate tool in dry-run mode such that the database is not modified, and the tool only demonstrates the changes. The --change-database argument is required if you want to carry out the changes in the database. You must take a backup of the database before you use the --change-database argument.

The keyrotate tool can be run while the server is online. In an HA cluster, all members share the same database, so you must run the keyrotate tool on only one cluster member.

The keytool 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.

Runtime

Generally, the keyrotate tool in dry-run mode requires a significant amount of time to run. Running the tool with --change-database argument might take much longer than the dry-run mode as writes are typically slower than reads. It's important to note that the run times involved with rotating and deleting the keys depends on the resources available in the database, and the amount of data that needs to be processed.

Rotating 3DES keys

When rotating encryption keys, the keyrotate tool displays below error when a 3DES key is found:

Cannot upgrade the server: a 3DES property encryption key was detected. 3DES keys are no longer supported. Before you can upgrade the server, you must first upgrade to a 7.2.3 release and use the 'keyrotate' tool to replace references to 3DES keys in your database. Then remove those keys from your property encryption keystore with 'keydelete' or with your JVM 'keytool' utility.

To rotate a secure property encryption key:

Procedure

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.
The output demonstrates the changes without making actual changes to the database.
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.
```
./keyrotate --product-home "/opt/launch/server" --change-database
```
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.
The keyrotate tool lists the keys in keystore, the keynames, and their rotation status. An example output is shown below:
```
key=[desedekey<key1>] refs=0 replaced=0
key=[aes128key<key2>] refs=2 replaced=2
key=[aes128key<key3>] refs=0 replaced=0
key=[aes128key<key4>] refs=12953555 replaced=0
key=[desedekey<key5>] refs=0 replaced=0
unknown=[desedekey<key6> refs=10
unknown=[desedekey<key7>] refs=4
```
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. However, you must delete any 3DES keys to be able to use 7.3.0 or newer versions. The keyname in output can be used to delete the 3DES keys.