AWS kms documentation change
Summary
Restructured documentation to clarify key material import processes by key type (symmetric, asymmetric, HMAC, multi-Region). Added specific procedures for multi-Region keys, key material states, and expanded options for key material descriptions.
Security assessment
The changes enhance documentation about key material management processes but contain no evidence of addressing a specific security vulnerability. They clarify operational procedures for importing key material across different key types, which improves security feature documentation but does not indicate a security incident or weakness being patched.
Diff
diff --git a/kms/latest/developerguide/importing-keys-import-key-material.md b/kms/latest/developerguide/importing-keys-import-key-material.md index 71f4b3be3..db9059461 100644 --- a//kms/latest/developerguide/importing-keys-import-key-material.md +++ b//kms/latest/developerguide/importing-keys-import-key-material.md @@ -13 +13,26 @@ When you import key material, you can set an optional expiration time for the ke -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. +###### + +Key material import considerations by key type + +_Symmetric encryption keys_ + + +For all KMS keys with `EXTERNAL` origin, the first key material imported into it becomes current and permanently associated with it. 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. + +_Asymmetric and HMAC keys_ + + +For asymmetric, or HMAC 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. + +_ + +Multi-Region keys_ + + +You can import new key materials into multi-Region symmetric keys. To do so, you must create the primary and replica Region keys. Then you must import the new key material to the primary Region key. You cannot directly import new key materials to replica Region keys. After importing new key material into the primary Region key, you can import the same key material into the replica Region keys. + +If a key material in a primary or replica Region key is deleted or expires, only that specific key is affected. Replica Region keys that have all their permanently associated key materials imported can be used in cryptographic operations. + +You can only set or change the key material description for the primary Region key with multi-Region keys. + +_Key states when importing key material_ @@ -15 +39,0 @@ For all KMS keys with `EXTERNAL` origin, the first key material imported into it -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. @@ -37 +61,3 @@ You determine whether and when imported key material expires when you import the -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. +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. + +You can only set or change the key material description for the primary Region key with multi-Region keys. @@ -49 +75,3 @@ The procedure to reimport key material is the same procedure that you use to imp - * When you reimport key material, you can change the expiration model and expiration date. + * When you reimport key material, you can change the expiration model, expiration date, and key material description. + +You can only set or change the key material description for the primary Region key with multi-Region keys. @@ -58 +86,16 @@ Each time you import key material to a KMS key, you need to [download and use a -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. +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. + + * **Single Region keys** + + * 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. + + * **Multi-Region keys** + + * To import key material into a multi-Region key, you must first import the new key material to the primary Region key. You cannot directly import new key materials to replica Region keys. After importing new key material to the primary Region key, you can import the same key materials into the replica Region keys. + + * Use the [`ImportKeyMaterial`](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) operation with the `ImportType` parameter set to `NEW_KEY_MATERIAL` for the primary Region key to accomplish this task. For the replica Region key, use the `EXISTING_KEY_MATERIAL` parameter for `ImportType` for the `ImportKeyMaterial` operation. + + * The key material for multi-Region keys must be imported into all the replica Region keys and primary Region keys before the key material state changes to `PENDING_ROTATION` state. Until then, the state of the new key material is `PENDING_MULTI_REGION_IMPORT_AND_ROTATION`. A KMS key can have at most one key material in `PENDING_ROTATION` or `PENDING_MULTI_REGION_IMPORT_AND_ROTATION`state at any time. + + + @@ -78 +121 @@ You can only import key material into KMS keys with an **Origin** of **External - 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. + 7. For asymmetric and HMAC keys, choose the **Key material** tab and then choose **Import key material**. For 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. @@ -81,0 +125,4 @@ If you downloaded the key material, import token, and encrypted the key material +###### Note + +For Multi-Region keys, you must first import the new key material into the primary Region key. Then you can import the same key material into the replica Region keys. + @@ -102,0 +150,2 @@ To use this example: +You can only set or change the key material description for the primary Region key with multi-Region keys. + @@ -124 +173 @@ 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: + 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 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: