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.

You must be in the Key Admins group, and logged into the root domain to manage key rotation job configurations.

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"}'

Replaced Key State

On KeySecure, the rotated key state can be one of the following: restricted, active, or retired. After migration from KeySecure to the CipherTrust Manager, the rotated key state can only be moved to retired.

Therefore, to perform decryption operations on the previous version of the key after key rotation was not possible on the previous versions of the CipherTrust Manager.

There is a provision to set the state of the previous version of the key after rotation using the replaced-key-state parameter.

An optional string to set the state of the previous key version to "Deactivated" or "ProtectStop" after key rotation. This parameter should only be used with the "change_state_after_time" parameter. Also, ensure not to use "replaced_key_state" parameter when "deactivate_replaced_key" is used. The value of the replaced-key-state can be "Deactivated" or "ProtectStop" after key rotation.

Example Request 1 (replaced-key-state is set to ProtectStop)

ksctl scheduler configs create key-rotation --name "test1" --run-at "0 1 * * *" --replaced-key-state "ProtectStop" --change-state-after-time 3

Example Response 1

{
    "id": "0c316329-9b81-4da5-8041-74271252552d",
    "uri": "kylo:kylo:scheduler:job_configs:0c316329-9b81-4da5-8041-74271252552d",
    "account": "kylo:kylo:admin:accounts:kylo",
    "application": "ncryptify:gemalto:admin:apps:kylo",
    "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
    "createdAt": "2023-04-27T04:37:55.984758701Z",
    "name": "test1",
    "updatedAt": "2023-04-27T04:37:55.984758701Z",
    "description": "",
    "operation": "key_rotation",
    "run_at": "0 1 * * *",
    "run_on": "any",
    "disabled": false,
    "job_config_params": {
        "replaced_key_state": "ProtectStop",
        "change_state_after_time": 3
    }
}

The change_state_after_time parameter represents the time (number of seconds >= 0) after which the replaced key will change its state to the value defined in the replaced_key_state parameter.

Example Request 2 (replaced-key-state is set to Deactivated)

ksctl scheduler configs create key-rotation --name "test2" --run-at "0 1 * * *" --replaced-key-state "Deactivated" --change-state-after-time 3

Example Response 2

{
    "id": "d0c48426-f5cc-416b-b935-e91b5872db8a",
    "uri": "kylo:kylo:scheduler:job_configs:d0c48426-f5cc-416b-b935-e91b5872db8a",
    "account": "kylo:kylo:admin:accounts:kylo",
    "application": "ncryptify:gemalto:admin:apps:kylo",
    "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
    "createdAt": "2023-04-27T04:39:57.848220415Z",
    "name": "test2",
    "updatedAt": "2023-04-27T04:39:57.848220415Z",
    "description": "",
    "operation": "key_rotation",
    "run_at": "0 1 * * *",
    "run_on": "any",
    "disabled": false,
    "job_config_params": {
        "replaced_key_state": "Deactivated",
        "change_state_after_time": 3
    }
}