Deleting an encryption key

The keydelete command removes a key for secure property encryption.

About this task

You can run the tool in dry-run mode such that the keystore is not modified and the tool only demonstrates the change. The --change-keystore argument is required to cause the tool to complete the change.

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

Note:

The keydelete tool cannot remove the primary encryption key.
The tool can only determine the primary key for the local server member in an HA cluster. It cannot detect if other members have configured a different primary key. For best results, set up the cluster so that all members use the same primary key.

Note: Do not delete keys unless you have a compelling reason to do so. Only the primary key is used for encrypting new secure data. After the previous data is re-encrypted with the new key by using the keyrotate tool, previous keys are not used in normal operation. In some scenarios, you might require previous keys, such as decrypting data that you restore from a backup that used previous keys or when importing configurations that were created with a previous key. Retain previous keys for these kinds of scenarios.

To delete an encryption key:

Procedure

Confirm that the server is configured to use a different key as its primary.
The tool cannot delete the primary key. View the installed.properties file and check that the value of the encryption.keystore.alias property is not the alias of the key that you are targeting for deletion. In an HA cluster, each member has its own installed.properties file, so each must be checked individually.
Update servers that use the targeted key.

Edit the installed.properties and set the encryption.keystore.alias property to the alias of another key. In an HA cluster, each member has its own installed.properties file, so you must edit each member individually. For best results, set up the cluster so that all members use the same primary key.
Restart any updated servers.

The server loads keys and the primary key setting only at startup. In an HA cluster, each updated member must be restarted.
Run the keydelete command without the --change-keystore argument to verify the action.
In an HA cluster, all members share the same keystore file, so you must run the keydelete command on only one cluster member. For example, run the following command:
```
keydelete --target-key <key>
```
Here, the --target-key <key> flag is required. The <key> variable is the name of the key you are targeting for deletion. The key is not deleted unless --change-keystore is also specified.
Run the keydelete command again with the --change-keystore argument to complete the action.
In an HA cluster, all members share the same keystore file, so you must run the keydelete command on only one cluster member:
```
keydelete --target-key <key> [--change-keystore]
```
Note that the --change-keystore argument is optional. It enables the modification of the keystore. Unless this flag is specified, the tool only demonstrates the change without completing the action.
Restart the server.

The server never unloads a key. In an HA cluster, you must restart each member.