AWS kms documentation change
Summary
Updated key rotation documentation with clarified terminology, added details about manual/on-demand rotation support, external key material management, and reorganization of content.
Security assessment
The changes enhance documentation about key rotation best practices (e.g., clarifying that rotation doesn't mitigate compromised data keys, adding guidance for external key material management). While these updates improve security documentation, there's no evidence they address a specific disclosed vulnerability.
Diff
diff --git a/kms/latest/developerguide/rotate-keys.md b/kms/latest/developerguide/rotate-keys.md index 3c068ec1e..8b27b3ac5 100644 --- a//kms/latest/developerguide/rotate-keys.md +++ b//kms/latest/developerguide/rotate-keys.md @@ -13 +13 @@ By default, when you enable _automatic key rotation_ for a KMS key, AWS KMS gene -AWS KMS saves all previous versions of the cryptographic material in perpetuity so you can decrypt any data encrypted with that KMS key. AWS KMS does not delete any rotated key material until you [delete the KMS key](./deleting-keys.html). You can track the rotation of key material for your KMS keys in Amazon CloudWatch, AWS CloudTrail, and the AWS Key Management Service console. You can also use [GetKeyRotationStatus](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.html) operation to verify whether automatic rotation is enabled for a KMS key and identify any in progress on-demand rotations. You can use [ListKeyRotations](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeyRotations.html) operation to view the details of completed rotations. +You can track the rotation of key material for your KMS keys in Amazon CloudWatch, AWS CloudTrail, and the AWS Key Management Service console. You can also use [GetKeyRotationStatus](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.html) operation to verify whether automatic rotation is enabled for a KMS key and identify any in progress on-demand rotations. You can use [ListKeyRotations](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeyRotations.html) operation to view the details of completed rotations. @@ -15 +15 @@ AWS KMS saves all previous versions of the cryptographic material in perpetuity -When you use a rotated KMS key to encrypt data, AWS KMS uses the current key material. When you use the rotated KMS key to decrypt ciphertext, AWS KMS uses the version of the key material that was used to encrypt it. You cannot select a particular version of the key material for decrypt operations, AWS KMS automatically chooses the correct version. Because AWS KMS transparently decrypts with the appropriate key material, you can safely use a rotated KMS key in applications and AWS services without code changes. +Key rotation changes only the _current key material_ , which is the cryptographic secret that is used in encryption operations. When you use the rotated KMS key to decrypt ciphertext, AWS KMS uses the key material that was used to encrypt it. You cannot select a particular key material for decrypt operations, AWS KMS automatically chooses the correct key material. Because AWS KMS transparently decrypts with the appropriate key material, you can safely use a rotated KMS key in applications and AWS services without code changes. @@ -17 +17 @@ When you use a rotated KMS key to encrypt data, AWS KMS uses the current key mat -However, automatic key rotation has no effect on the data that the KMS key protects. It does not rotate the [data keys](./data-keys.html) that the KMS key generated or re-encrypt any data protected by the KMS key, and it will not mitigate the effect of a compromised data key. +The KMS key is the same logical resource, regardless of whether or how many times its key material changes. The properties of the KMS key do not change, as shown in the following image. @@ -19,5 +19 @@ However, automatic key rotation has no effect on the data that the KMS key prote -AWS KMS supports automatic and on-demand key rotation only for [symmetric encryption KMS keys](./symm-asymm-choose-key-spec.html#symmetric-cmks) with key material that AWS KMS creates. Automatic rotation is optional for customer managed KMS keys. AWS KMS always rotates the key material for AWS managed KMS keys every year. Rotation of AWS owned KMS keys is managed by the AWS service that owns the key. - -###### Note - -The rotation period for AWS managed keys changed in May 2022. For details, see AWS managed keys. + @@ -25 +21 @@ The rotation period for AWS managed keys changed in May 2022. For details, see A -Key rotation changes only the _key material_ , which is the cryptographic secret that is used in encryption operations. The KMS key is the same logical resource, regardless of whether or how many times its key material changes. The properties of the KMS key do not change, as shown in the following image. +You might decide to create a new KMS key and use it in place of the original KMS key. This has the same effect as rotating the key material in an existing KMS key, so it's often thought of as [manually rotating the key](./rotate-keys-manually.html). Manual rotation is a good choice when you want to rotate KMS keys that are not eligible for automatic or on-demand key rotation, including [asymmetric KMS keys](./symmetric-asymmetric.html), [HMAC KMS keys](./hmac.html), KMS keys in [custom key stores](./key-store-overview.html#custom-key-store-overview), and multi-Region KMS keys with [imported key material](./importing-keys.html). @@ -27 +23 @@ Key rotation changes only the _key material_ , which is the cryptographic secret - +###### Note @@ -29 +25 @@ Key rotation changes only the _key material_ , which is the cryptographic secret -You might decide to create a new KMS key and use it in place of the original KMS key. This has the same effect as rotating the key material in an existing KMS key, so it's often thought of as [manually rotating the key](./rotate-keys-manually.html). Manual rotation is a good choice when you want to rotate KMS keys that are not eligible for automatic key rotation, including [asymmetric KMS keys](./symmetric-asymmetric.html), [HMAC KMS keys](./hmac.html), KMS keys in [custom key stores](./key-store-overview.html#custom-key-store-overview), and KMS keys with [imported key material](./importing-keys.html). +Key rotation has no effect on the data that the KMS key protects. It does not rotate the data keys that the KMS key generated or re-encrypt any data protected by the KMS key. Key rotation will not mitigate the effect of a compromised data key. @@ -58,0 +55,2 @@ For detailed information about key material and rotation, see [AWS Key Managemen + * [List rotations and key materials](./list-rotations.html) + @@ -68 +66 @@ For detailed information about key material and rotation, see [AWS Key Managemen -Cryptographic best practices discourage extensive reuse of keys that encrypt data directly, such as the [data keys](./data-keys.html) that AWS KMS generates. When 256-bit data keys encrypt millions of messages they can become exhausted and begin to produce ciphertext with subtle patterns that clever actors can exploit to discover the bits in the key. To avoid this key exhaustion, it's best to use data keys once, or just a few times, which effectively rotates the key material. +Cryptographic best practices discourage extensive reuse of keys that encrypt data directly, such as the [data keys](./data-keys.html) that AWS KMS generates. When 256-bit data keys encrypt millions of messages they can become exhausted and begin to produce ciphertext with subtle patterns that clever actors can exploit to discover the bits in the key. It's best to use data keys once, or just a few times, to mitigate this key exhaustion. @@ -72 +70 @@ However, KMS keys are most often used as _wrapping keys_ , also known as _key-en -Despite this very low exhaustion risk, you might be required to rotate your KMS keys due to business or contract rules or government regulations. When you are compelled to rotate KMS keys, we recommend that you use automatic key rotation where it is supported, and manual key rotation when automatic key rotation is not supported. +Despite this very low exhaustion risk, you might be required to rotate your KMS keys due to business or contract rules or government regulations. When you are compelled to rotate KMS keys, we recommend that you use automatic key rotation where it is supported, use on-demand rotation if automatic rotation is not supported, and manual key rotation when neither automatic nor on-demand key rotation is supported. @@ -74 +72 @@ Despite this very low exhaustion risk, you might be required to rotate your KMS -You might consider performing on-demand rotations to demonstrate key material rotation capabilities or to validate automation scripts. We recommend using on-demand rotations for unplanned rotations, and using automatic key rotation with with a custom rotation period whenever possible. +You might consider performing on-demand rotations to demonstrate key material rotation capabilities or to validate automation scripts. We recommend using on-demand rotations for unplanned rotations, and using automatic key rotation with a custom rotation period whenever possible. @@ -86,0 +85,4 @@ AWS KMS rotates the KMS key automatically on the next rotation date defined by y +Automatic key rotation is supported only on symmetric encryption KMS keys with key material that AWS KMS generates (`AWS_KMS` origin). + +Automatic rotation is optional for customer managed KMS keys. AWS KMS always rotates the key material for AWS managed KMS keys every year. Rotation of AWS owned KMS keys is managed by the AWS service that owns the key. + @@ -93,0 +96,20 @@ Immediately initiate rotation of the key material associated with your KMS key, +On-demand key rotation is supported on symmetric encryption KMS keys with key material that AWS KMS generates (`AWS_KMS` origin) and single-Region, symmetric encryption KMS keys with imported key material (`EXTERNAL` origin). + +** + +Manual rotation** + + +Neither automatic nor on-demand key rotation is supported for the following types of KMS keys, but you can [rotate these KMS keys manually](./rotate-keys-manually.html). + + * [Asymmetric KMS keys](./symmetric-asymmetric.html) + + * [HMAC KMS keys](./hmac.html) + + * KMS keys in [custom key stores](./key-store-overview.html#custom-key-store-overview) + + * Multi-Region KMS keys with [imported key material](./importing-keys.html) + + + + @@ -97 +119,3 @@ Immediately initiate rotation of the key material associated with your KMS key, -AWS KMS retains all key material for a KMS key, even if key rotation is disabled. AWS KMS deletes key material only when you delete the KMS key. +AWS KMS retains all key material for a KMS key with `AWS_KMS` origin, even if key rotation is disabled. AWS KMS deletes key material only when you delete the KMS key. + +You manage the key materials for symmetric encryption keys with `EXTERNAL` origin. You can delete any key material using the [DeleteImportedKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteImportedKeyMaterial.html) operation or set an expiration time when importing the material. The KMS key becomes unusable as soon as any of its materials expires or is deleted. @@ -112,0 +137,7 @@ You can use the [kms:RotationPeriodInDays](./conditions-kms.html#conditions-kms- +** + +Rotation date** + + +Rotation date reflects the date when the current key material for a KMS key was updated either as a result of automatic (scheduled) rotation or an on-demand key rotation. + @@ -147,4 +177,0 @@ In May 2022, AWS KMS changed the rotation schedule for AWS managed keys from eve -New AWS managed keys are automatically rotated one year after they are created, and approximately every year thereafter. - -Existing AWS managed keys are automatically rotated one year after their most recent rotation, and every year thereafter. - @@ -156,18 +182,0 @@ You cannot enable or disable key rotation for AWS owned keys. The [key rotation] -**Supported KMS key types** - - -Automatic key rotation is supported only on [symmetric encryption KMS keys](./symm-asymm-choose-key-spec.html#symmetric-cmks) with key material that AWS KMS generates (Origin = AWS_KMS). - -Automatic key rotation is _not_ supported on the following types of KMS keys, but you can [rotate these KMS keys manually](./rotate-keys-manually.html). - - * [Asymmetric KMS keys](./symmetric-asymmetric.html) - - * [HMAC KMS keys](./hmac.html) - - * KMS keys in [custom key stores](./key-store-overview.html#custom-key-store-overview) - - * KMS keys with [imported key material](./importing-keys.html) - - - - @@ -179 +188 @@ Rotating multi-Region keys** -You can enable and disable automatic rotation and perform on-demand rotation of the key material in symmetric encryption [multi-Region keys](./multi-region-keys-overview.html). Key rotation is a [shared property](./multi-region-keys-overview.html#mrk-sync-properties) of multi-Region keys. +You can enable and disable automatic rotation and perform on-demand rotation of the key material in symmetric encryption [multi-Region keys](./multi-region-keys-overview.html) with `AWS_KMS` origin. Key rotation is a [shared property](./multi-region-keys-overview.html#mrk-sync-properties) of multi-Region keys.