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.

Dry-run the keyrotate command and verify that the encryption key is rotating.

You can use the following supported arguments with the keyrotate command:

Supported arguments Description

--workers N 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.

Supported arguments	Description
`--workers N`	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.
`--status-interval-secs N`	Prints the status of keyrotation every `N` seconds. The default is `5` seconds. You can set the interval to `0` to disable printing. Changes are logged into the stdout file. To troubleshoot errors, check the stderr log file.
`--batch-sizes`	Reduces the memory requirements for tables with large rows , such as `wf_workflow_trace` and `vc_persistent_record` tables. For example, you can use the argument as follows: `--batch-sizes "vc_persistent_record=15,wf_workflow_trace=10"` The argument value is a comma-separated list of table names with their reduced batch size. The default batch size for all tables is 50. Note: You may need to quote the argument depending on your shell. The quotes used in the example command are not part of the syntax.

--status-interval-secs N

Prints the status of keyrotation every N seconds. The default is 5 seconds. You can set the interval to 0 to disable printing.

Changes are logged into the stdout file. To troubleshoot errors, check the stderr log file.

--batch-sizes

Reduces the memory requirements for tables with large rows , such as wf_workflow_trace and vc_persistent_record tables. For example, you can use the argument as follows:

--batch-sizes "vc_persistent_record=15,wf_workflow_trace=10"

The argument value is a comma-separated list of table names with their reduced batch size. The default batch size for all tables is 50.

Note: You may need to quote the argument depending on your shell. The quotes used in the example command are not part of the syntax.

The output demonstrates the changes without making actual changes to the database.

For a real-run execution, run keyrotate with the --change-database argument to rotate the encryption keys.
Running the keyrotate tool with the --change-database flag enables modification of the database.
```
./keyrotate --product-home "/opt/devops-deploy/server" --change-database
```
Note: Use the same arguments for both the steps to ensure that the dry-run is as close as the real run.
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
```
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.