AWS kms documentation change
Summary
Updated documentation for on-demand key rotation to clarify permissions (kms:RotateKeyOnDemand and kms:GetKeyRotationStatus required), expanded supported key types (single-Region keys with imported material), added details about rotation status visibility via ListKeyRotations API, updated console navigation steps, and added examples for different rotation scenarios.
Security assessment
The changes primarily improve clarity around security controls (permissions required for rotation) and expand documentation for secure key management practices. However, there is no evidence of addressing a specific security vulnerability. The additions about required permissions and rotation conditions enhance security documentation but don't fix a disclosed issue.
Diff
diff --git a/kms/latest/developerguide/rotating-keys-on-demand.md b/kms/latest/developerguide/rotating-keys-on-demand.md index 5047f8a19..21e3d71bb 100644 --- a//kms/latest/developerguide/rotating-keys-on-demand.md +++ b//kms/latest/developerguide/rotating-keys-on-demand.md @@ -13 +13 @@ You can perform on-demand key rotation a maximum of 10 times per KMS key. You ca -On-demand key rotation is supported only on [symmetric encryption KMS keys](./symm-asymm-choose-key-spec.html#symmetric-cmks). You cannot perform on-demand rotation of [asymmetric KMS keys](./symmetric-asymmetric.html), [HMAC KMS keys](./hmac.html), KMS keys with [imported key material](./importing-keys.html), or KMS keys in a [custom key store](./key-store-overview.html#custom-key-store-overview). To perform on-demand rotation of a set of related [multi-Region keys](./rotate-keys.html#multi-region-rotate), invoke the on-demand rotation on the primary key. +On-demand key rotation is supported only on [symmetric encryption KMS keys](./symm-asymm-choose-key-spec.html#symmetric-cmks). You cannot perform on-demand rotation of [asymmetric KMS keys](./symmetric-asymmetric.html), [HMAC KMS keys](./hmac.html), multi-Region KMS keys with [imported key material](./importing-keys.html), or KMS keys in a [custom key store](./key-store-overview.html#custom-key-store-overview). To perform on-demand rotation of a set of related [multi-Region keys](./rotate-keys.html#multi-region-rotate), invoke the on-demand rotation on the primary key. @@ -15 +15 @@ On-demand key rotation is supported only on [symmetric encryption KMS keys](./sy -Authorized users can use the AWS KMS console and the AWS KMS API to initiate on-demand key rotation and view the key rotation status. +Authorized users with `kms:RotateKeyOnDemand` and `kms:GetKeyRotationStatus` permissions can use the AWS KMS console and the AWS KMS API to initiate on-demand key rotation and view the key rotation status. Use [ListKeyRotations](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeyRotations.html) to view completed rotations for a KMS key. @@ -36 +36 @@ Authorized users can use the AWS KMS console and the AWS KMS API to initiate on- - 5. Choose the **Key rotation** tab. + 5. Choose the **Key material and rotations** tab. @@ -38 +38 @@ Authorized users can use the AWS KMS console and the AWS KMS API to initiate on- -The **Key rotation** tab appears only on the detail page of symmetric encryption KMS keys with key material that AWS KMS generated (the **Origin** is **AWS_KMS**), including [multi-Region](./rotate-keys.html#multi-region-rotate) symmetric encryption KMS keys. +The **Key material and rotations** tab appears only on the detail page of symmetric encryption KMS keys that support automatic or on-demand rotation. This includes KMS keys with key material that AWS KMS generated (**AWS_KMS** origin) and single-Region KMS keys with imported key material (**EXTERNAL** origin). @@ -40 +40 @@ The **Key rotation** tab appears only on the detail page of symmetric encryption -You cannot perform on-demand rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with [imported key material](./importing-keys.html), or KMS keys in [custom key stores](./key-store-overview.html#custom-key-store-overview). However, you can [rotate them manually](./rotate-keys-manually.html). +You cannot perform on-demand rotation of asymmetric KMS keys, HMAC KMS keys, multi-Region KMS keys with [imported key material](./importing-keys.html), or KMS keys in [custom key stores](./key-store-overview.html#custom-key-store-overview). However, you can [rotate them manually](./rotate-keys-manually.html). @@ -42 +42 @@ You cannot perform on-demand rotation of asymmetric KMS keys, HMAC KMS keys, KMS - 6. In the **On-demand key rotation** section, choose **Rotate key**. + 6. Choose **Rotate now**. For single-Region, symmetric encryption keys with imported key material, the **Rotate now** option is available only if you have previously [imported new key material](./importing-keys-import-key-material.html#import-new-key-material) and it is in **Pending rotation** state. @@ -44 +44 @@ You cannot perform on-demand rotation of asymmetric KMS keys, HMAC KMS keys, KMS - 7. Read and consider the warning and the information about the number of remaining on-demand rotations for the key. If you decide that you do not want to proceed with the on-demand rotation, choose **Cancel**. + 7. Read and consider the warning and the information about the number of remaining on-demand rotations for the key. You will also see information such as the ID, description, and expiration time of the key material that will become current after rotation. If you decide that you do not want to proceed with the on-demand rotation, choose **Cancel**. @@ -61 +61 @@ The [RotateKeyOnDemand](https://docs.aws.amazon.com/kms/latest/APIReference/API_ -The following example initiates on-demand key rotation on the specified symmetric encryption KMS key and uses the [GetKeyRotationStatus](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.html) operation to verify that the on-demand rotation is in progress. The `OnDemandRotationStartDate` in the `kms:GetKeyRotationStatus` response identifies the date and time that an in progress on-demand rotation was initiated. +The following example initiates on-demand key rotation on the specified symmetric encryption KMS key and uses the [GetKeyRotationStatus](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.html) operation to verify that the on-demand rotation is in progress. The `OnDemandRotationStartDate` in the `kms:GetKeyRotationStatus` response identifies the date and time that an in progress on-demand rotation was initiated. In this example, the KMS key also has automatic rotation enabled with a period of 365 days. @@ -78,0 +79,16 @@ The following example initiates on-demand key rotation on the specified symmetri +If the KMS key does not support automatic rotation or does not have automatic rotation enabled, the `kms:GetKeyRotationStatus` response would have fewer fields as shown in the following example: + + + $ aws kms rotate-key-on-demand --key-id 1234abcd-12ab-34cd-56ef-1234567890ab + { + "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab" + } + + $ aws kms get-key-rotation-status --key-id 1234abcd-12ab-34cd-56ef-1234567890ab + { + "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", + "KeyRotationEnabled": false, + "OnDemandRotationStartDate": "2024-02-24T18:44:48.587000+00:00" + } + + @@ -87 +103 @@ Disable automatic key rotation -Rotate keys manually +List rotations and key materials