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.
-
Edit the
installed.properties
file and set theencryption.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:
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.
You can also use the./keyrotate --product-home "/opt/launch/server" --change-database
--workers N
argument. It sets the number of concurrent workers. The default value is2
, and the minimum required value is1
. The database must accept N+1 concurrent connections. Values greater than8
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.