AWS kms medium security documentation change
Summary
Added documentation for key material rotation capabilities, new ImportType parameter options (NEW_KEY_MATERIAL), key material descriptions, and clarified reimport procedures for different key types.
Security assessment
The changes introduce on-demand rotation for imported key material in symmetric encryption keys, a security feature that allows replacing cryptographic material without key deletion. This addresses key rotation limitations - a security best practice to mitigate long-term key compromise risks. Specific security evidence includes the new PENDING_ROTATION state, RotateKeyOnDemand API reference, and restrictions preventing rotation for asymmetric/HMAC keys where inappropriate.
Diff
diff --git a/kms/latest/developerguide/importing-keys-import-key-material.md b/kms/latest/developerguide/importing-keys-import-key-material.md index fbf8b6da1..71f4b3be3 100644 --- a//kms/latest/developerguide/importing-keys-import-key-material.md +++ b//kms/latest/developerguide/importing-keys-import-key-material.md @@ -5 +5 @@ -Setting an expiration time (optional)Reimport key materialImport key material (console)Import key material (AWS KMS API) +Setting an expiration time (optional)Set key material descriptionReimport key materialImport new key materialImport key material (console)Import key material (AWS KMS API) @@ -11 +11,7 @@ After you [encrypt your key material](./importing-keys-encrypt-key-material.html -When you import key material, you can set an optional expiration time for the key material. When the key material expires, AWS KMS deletes the key material and the KMS key becomes unusable. To use the KMS key in cryptographic operations, you must reimport the same key material. After you import your key material, you cannot set, change, or cancel the expiration date for the current import. To change these values, you must [delete](./importing-keys-delete-key-material.html) and reimport the same key material. +When you import key material, you can set an optional expiration time for the key material. When the key material expires, AWS KMS deletes the key material and the KMS key becomes unusable. After you import your key material, you cannot set, change, or cancel the expiration date for the current import. To change these values, you must reimport the same key material. + +For all KMS keys with `EXTERNAL` origin, the first key material imported into it becomes current and permanently associated with it. Single-Region, symmetric encryption keys with `EXTERNAL` origin support on-demand rotation. You can associate multiple key materials with imported keys that support on-demand rotation. You must set the `importType` parameter to `NEW_KEY_MATERIAL` with the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) action to associate new key material with a KMS key. This key material is not permanently associated with the key until you perform the [RotateKeyOnDemand](https://docs.aws.amazon.com/kms/latest/APIReference/API_RotateKeyOnDemand.html) action. Until then, this key material is in `PENDING_ROTATION` state. The default value of the optional `ImportType` parameter is `EXISTING_KEY_MATERIAL`. When you omit the `ImportType` parameter or specify it as `EXISTING_KEY_MATERIAL`, you must import a key material that is previously associated with the KMS key. + +For asymmetric, HMAC or multi-Region KMS keys with `EXTERNAL` origin, only one key material can ever be associated with the key. AWS KMS will reject [ ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) API requests with the `ImportType` parameter. + +When all key materials permanently associated with a KMS key are imported, the KMS key is available for use in cryptographic operations. If any one of these key materials is deleted or allowed to expire, the KMS key state changes to `PendingImport` and the key is unusable for cryptographic operations. @@ -25 +31,3 @@ To mitigate this risk, make sure that your copy of the imported key material is -You cannot import different key material into the KMS key, and AWS KMS cannot restore, recover, or reproduce the deleted key material. Instead of setting an expiration time, you can programmatically [delete](./importing-keys-delete-key-material.html) and reimport the imported key material periodically, but the requirements for retaining a copy of the original key material are the same. +AWS KMS cannot restore, recover, or reproduce the deleted key material. Instead of setting an expiration time, you can programmatically [delete](./importing-keys-delete-key-material.html) and reimport the imported key material periodically, but the requirements for retaining a copy of the original key material are the same. + +You determine whether and when imported key material expires when you import the key material. However you can turn expiration on and off, or set a new expiration time by reimporting the key material. Use the `ExpirationModel` parameter of [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) to turn expiration on (`KEY_MATERIAL_EXPIRES`) and off (`KEY_MATERIAL_DOES_NOT_EXPIRE`) and the `ValidTo` parameter to set the expiration time. The maximum time is 365 days from the import data; there is no minimum, but the time must be in the future. @@ -27 +35,3 @@ You cannot import different key material into the KMS key, and AWS KMS cannot re -You determine whether and when imported key material expires when you import the key material. But you can turn expiration on and off, or set a new expiration time by deleting and reimporting the key material. Use the `ExpirationModel` parameter of [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) to turn expiration on (`KEY_MATERIAL_EXPIRES`) and off (`KEY_MATERIAL_DOES_NOT_EXPIRE`) and the `ValidTo` parameter to set the expiration time. The maximum time is 365 days from the import data; there is no minimum, but the time must be in the future. +## Set key material description + +Single-Region, symmetric encryption keys with `EXTERNAL` origin can have multiple key materials associated with them. You can specify an optional key material description when importing key material into such keys. The description can be used to keep track of where the corresponding key material is durably maintained outside AWS KMS. @@ -33,2 +42,0 @@ If you manage a KMS key with imported key material, you might need to reimport t -When you import key material into a KMS key, the KMS key is permanently associated with that key material. You can reimport the same key material, but you cannot import different key material into that KMS key. You cannot rotate the key material and AWS KMS cannot create key material for a KMS key with imported key material. - @@ -37 +45 @@ You can reimport key material at any time, on any schedule that meets your secur -The procedures to reimport key material are the same the same procedure that you use to import the key material the first time, with the following exceptions. +The procedure to reimport key material is the same procedure that you use to import the key material the first time, with the following exceptions. @@ -47,0 +56,4 @@ Each time you import key material to a KMS key, you need to [download and use a +## Import new key material + +To perform on-demand rotation on a symmetric encryption KMS key with imported key material, you'll first need to import new key material, not previously associated with the key. Use the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) operation with the `ImportType` parameter set to `NEW_KEY_MATERIAL` to accomplish this task. Key material imported in this manner will be in `PENDING_ROTATION` state until you perform the [RotateKeyOnDemand](https://docs.aws.amazon.com/kms/latest/APIReference/API_RotateKeyOnDemand.html) operation or rotate the key in the AWS Management Console. A KMS key can have at most one key material in `PENDING_ROTATION` state at any time. + @@ -66 +78 @@ You can only import key material into KMS keys with an **Origin** of **External - 7. Choose the **Key material** tab and then choose **Import key material**. The **Key material** tab appears only for KMS keys with an **Origin** value of **External (Import key material)**. + 7. For asymmetric, HMAC and multi-Region keys, choose the **Key material** tab and then choose **Import key material**. For single-Region, symmetric encryption keys, choose the **Key material and rotations** tab. Then, choose either **Import initial key material** or **Import new key material** or **Reimport key material**. The **Reimport key material** option is available in the `Actions` menu in the key materials table. @@ -78 +90,3 @@ If you downloaded the key material, import token, and encrypted the key material - 10. Choose **Upload key material**. + 10. For symmetric encryption keys, you can optionally specify a description for the key material being imported. + + 11. Choose **Import key material**. @@ -109,0 +124,11 @@ If you do not want the imported key material to expire, set the value of the `ex + 5. If you want to import new key material, not previously associated with the KMS key, set the `ImportType` parameter to `NEW_KEY_MATERIAL`. This option can only be used with single-Region symmetric encryption keys. For these keys, you can also use the optional `KeyMaterialDescription` parameter to set a description for the imported key material in the following command line example: + + $ aws kms import-key-material --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ + --encrypted-key-material fileb://EncryptedKeyMaterial.bin \ + --import-token fileb://ImportToken.bin \ + --expiration-model KEY_MATERIAL_EXPIRES \ + --valid-to 2023-06-17T12:00:00-08:00 \ + --import-type NEW_KEY_MATERIAL \ + --key-material-description "Q2 2025 Rotation" + +