Rotating Keys on AWS KMS
Use the post /v1/cckm/aws/keys/{id}/rotate API to rotate a key on the AWS KMS.
Specify the following details for HYOK Keys:
source_key_tierandsource_key_idare the only params applicable for AWS HYOK Key, wheresource_key_idshould contain the ID of Luna HSM symmetric key.
Specify the following details for BYOK Keys.
Source Key Identifier of the key
Whether to disable encryption
Description of the key
Whether to enable key expiration
Key expiration time
Whether to retain alias along with timestamp on archived key
Specify the following details for CloudHSM Keys.
Whether to disable encryption
Description of the key
Whether to retain alias along with timestamp on archived key
Syntax
curl -k '<IP>/api/v1/cckm/aws/keys/{id}/rotate' -H 'Authorization: Bearer AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n "source_key_tier": "<source key tier>",\n "source_key_id": "<source key>",\n "disable_encrypt": <boolean>,\n "description": "<description>",\n "key_expiration": <boolean>,\n "valid_to": "<key validity>"\n "retain_alias": <true|false>\n}' --compressed
Here, {id} represents the key ID.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| description | string | Description for the new key (created during rotation). |
| disable_encrypt | boolean | Flag to disable encryption on key which is getting rotated. |
| key_expiration | boolean | Flag to enable key expiration of the newly rotated key. |
| source_key_tier | string | Tier of the source. Possible options are: • local for CipherTrust Manager (default)• dsm for Data Security Manager (DSM)• external-cm for external CipherTrust Manager• hsm-luna for Luna HSM (FM-enabled Luna HSM is not supported as a key source) |
| source_key_id | string | Name or ID of the key created on the CipherTrust Manager. • If source_key_tier is dsm, this is the ID of the DSM key to be uploaded. source_key_id is a mandatory parameter for dsm.• If source_key_tier is hsm-luna, this is the ID of the Luna HSM key to be uploaded. source_key_id is a mandatory parameter for hsm-luna.• If source_key_tier is external-cm, this is the ID the external CipherTrust Manager key to be uploaded.• If source_key_tier is local, this is the ID the CipherTrust Manager key to be uploaded. By default, a new CipherTrust Manager key would be generated automatically. |
| valid_to | string | Key expiration time of the newly rotated key, must be formatted as per RFC3339. |
| retain_alias | boolean | Whether to retain the key alias with timestamp on the archived key after rotation. Set "retain_alias": true to retain the alias. If set to false, the alias is not retained after rotation. |
| disable_encrypt_on_all_accounts (optional) | boolean | Indicates whether to disable encryption permissions on the old key for all the accounts (after key rotation). Parameters disable_encrypt and disable_encrypt_on_all_accounts are mutually exclusive. Specify either disable_encrypt or disable_encrypt_on_all_accounts. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/aws/keys/baf58871-2503-4d13-a84a-339aeb8fdfaf/rotate' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJjNWMwZGJlNC1lMmJmLTQ3M2MtODY4MC01NWVkMWIzMDEzMmEiLCJzdWIiOiJsb2NhbHxhNjdjMzc0OC05YTRiLTRhZGQtYjNkOS0wNTRiYTIwYmUzYWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiMDhkNDI5ZjktNDgzYi00ODdlLWJjOTQtNGE1Mjc2ZDI2ZjZjIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjZlZWE0NWJlLTc5NTMtNGUzZS1iNWJjLWZlZDEwMmZhNGNiYSIsImlhdCI6MTYwNDU1OTMxOSwiZXhwIjoxNjA0NTU5NjE5fQ.8BNfjt82PmwBoIzFsUk2eh4AvWwrjZxRiewK9Hyp67A' -H 'Content-Type: application/json' --data-binary $'{\n "source_key_id": "test-key",\n "disable_encrypt": false,\n "description": "rotate",\n "key_expiration": true,\n "valid_to": "2020-12-04T06:51:18.505860192Z"\n}' --compressed
Example Response
{
"id": "9c91d0b3-0da7-4580-b21c-f4dce82e8d0d",
"uri": "kylo:kylo:cckm:aws-key:9c91d0b3-0da7-4580-b21c-f4dce82e8d0d",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2020-11-05T06:56:47.698148721Z",
"updatedAt": "2020-11-05T06:56:48.683047459Z",
"kms_id": "0b90f8de-8617-498d-ad63-ca18eb717ae7",
"kms": "kms",
"rotated_at": "2020-11-05T06:56:48.681156311Z",
"rotated_from": "baf58871-2503-4d13-a84a-339aeb8fdfaf",
"synced_at": "2020-11-05T06:56:47.692074257Z",
"rotation_status": "ACTIVE",
"local_key_id": "361d928ac7e340d093e7d231c80ca934acc62528601647ce86a219c9a82f4f93",
"local_key_name": "test-key",
"cloud_name": "aws",
"key_type": "symmetric",
"basic_view_enabled": true,
"region": "ap-south-1",
"gone": false,
"key_material_origin": "cckm",
"aws_param": {
"AWSAccountId": "123456789012",
"Arn": "arn:aws:kms:ap-south-1:123456789012:key/d60940e6-5c78-46e5-9905-c14aa9543b40",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Description": "rotate",
"Enabled": true,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyID": "d60940e6-5c78-46e5-9905-c14aa9543b40",
"KeyManager": "CUSTOMER",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"Origin": "EXTERNAL",
"CreationDate": "2020-11-05T06:56:35Z",
"Policy": {
"Version": "2012-10-17",
"Id": "key-consolepolicy-3",
"Statement": [
{
"Sid": "Enable IAM UserName Permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:root"
},
"Action": "kms:*",
"Resource": "*"
}
]
},
"Alias": [
"alias/aws-test-key"
],
"Tags": [
{
"TagKey": "key",
"TagValue": "value"
}
],
"ValidTo": "2020-12-04T06:51:18.505860192Z",
"KeyRotationEnabled": false,
"ExpirationModel": "KEY_MATERIAL_EXPIRES"
}
}
The sample output shows that the key on the AWS KMS is rotated successfully.
To know more about response parameters, refer to Response Parameters of Key Life Cycle Management APIs.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
