Key Rotation
The key rotation operation generates a new version of a key with same key name and attributes, but with new key material. The operation provides an easy way to rotate keys in bulk periodically at the specified time.
Note
Scheduler itself is a generic service, so it provides granularity of a minute. A job configuration should take the nature of operation information into consideration. For example, rotating the same set of multiple keys every minute is a highly unlikely use case.
Scheduling Key Rotation
The CipherTrust Manager can periodically run key rotation jobs in the background. This can be achieved by creating scheduler configurations for key rotation.
This section provides examples of key rotation scheduler configurations using the ksctl utility. Refer to the ksctl or API documentation for details.
To create a scheduler configuration for key rotation, run the command:
ksctl scheduler configs create key-rotation --name <config-name> --run-at "<cron-expression-format>"
Here,
<config-name>: Name for the job configuration.<cron-expression-format>: Time when the job runs. The format must have five fields. If the number of fields is not equal to five, the format becomes invalid. Refer to Time Specification for details.
Optionally, you can specify the following:
--key-query-json: Query used for determining the keys to be rotated. By default, all keys are rotated. The query should be specified as a JSON blob. Refer to the API documentation for the JSON schema associated with the key query.--metadata-json: Metadata for the key that is replaced by the key rotation operation. The metadata should be specified as a JSON blob. The key metadata is also a JSON blob. The supplied metadata is added to the key metadata (existing data is overwritten). For example, this provides a mechanism to change the NAE state of a key by supplying{"naeState": "Restricted"}.--deactivate-replaced-key: Time interval in seconds (>=0) after which the key that is replaced by the key rotation procedure is deactivated. By default, the key is not deactivated.Note
Refer to the ksctl or API documentation for the complete list of parameters needed for scheduling key rotation operations.
Examples
To schedule a key rotation everyday at 9 AM, and modify the metadata of the key that is replaced, run the command:
ksctl scheduler configs create key-rotation --name change-meta --run-at "0 9 * * *" --metadata-json '{"naeState": "Restricted"}'
To rotate all AES keys every Monday at 9 AM:
ksctl scheduler configs create key-rotation --name rotate-aes --run-at "0 9 * * 1" --key-query-json '{"algorithm": "AES"}'
To activate the above key rotation on May 8, 2021 at 5:57:51 PM:
ksctl scheduler configs create key-rotation --name rotate-aes --run-at "0 9 * * 1" --start-time "May 8, 2021 5:57:51 PM"
To schedule a key rotation everyday at 9 PM, and rotate keys that were created at least a year ago:
ksctl scheduler configs create key-rotation --name rotate-old-keys --run-at "0 21 * * *" --metadata-json '{"createdBefore": "-1y"}'
