Skip to content

Commit ef12269

Browse files
author
awstools
committed
feat(client-kms): Support for on-demand rotation of AWS KMS Multi-Region keys with imported key material
1 parent 3f003f8 commit ef12269

File tree

7 files changed

+84
-37
lines changed

7 files changed

+84
-37
lines changed

‎clients/client-kms/src/commands/DeleteImportedKeyMaterialCommand.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,20 @@ export interface DeleteImportedKeyMaterialCommandOutput extends DeleteImportedKe
3434
* <p>When the specified KMS key is in the <code>PendingDeletion</code> state, this operation
3535
* does not change the KMS key's state. Otherwise, it changes the KMS key's state to
3636
* <code>PendingImport</code>.</p>
37+
* <p class="title">
38+
* <b>Considerations for multi-Region symmetric encryption keys</b>
39+
* </p>
40+
* <ul>
41+
* <li>
42+
* <p>When you delete the key material of a primary Region key that is in
43+
* <code>PENDING_ROTATION</code> or <code>PENDING_MULTI_REGION_IMPORT_AND_ROTATION</code>state,
44+
* you'll also be deleting the key materials for the replica Region keys.</p>
45+
* </li>
46+
* <li>
47+
* <p>If you delete any key material of a replica Region key, the primary Region key and
48+
* other replica Region keys remain unchanged.</p>
49+
* </li>
50+
* </ul>
3751
* <p>The KMS key that you use for this operation must be in a compatible key state. For
3852
* details, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html">Key states of KMS keys</a> in the <i>Key Management Service Developer Guide</i>.</p>
3953
* <p>

‎clients/client-kms/src/commands/ImportKeyMaterialCommand.ts‎

Lines changed: 30 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,28 @@ export interface ImportKeyMaterialCommandOutput extends ImportKeyMaterialRespons
3434
* generate and import your own key material. For more information about importing key material,
3535
* see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html">Importing key
3636
* material</a>.</p>
37-
* <p>For asymmetric, HMAC and multi-Region keys, you cannot change the key material after the
38-
* initial import. You can import multiple key materials into single-Region, symmetric encryption
39-
* keys and rotate the key material on demand using <code>RotateKeyOnDemand</code>.</p>
37+
* <p>For asymmetric and HMAC keys, you cannot change the key material after the initial import.
38+
* You can import multiple key materials into symmetric encryption keys and rotate the key
39+
* material on demand using <code>RotateKeyOnDemand</code>.</p>
40+
* <p>You can import new key materials into multi-Region symmetric encryption keys. To do so, you must
41+
* import the new key material into the primary Region key. Then you can import the same key
42+
* materials into the replica Region keys. You cannot directly import new key material into
43+
* the replica Region keys.</p>
44+
* <p>To import new key material for a multi-Region symmetric key, you’ll need to complete the
45+
* following:</p>
46+
* <ol>
47+
* <li>
48+
* <p>Call <code>ImportKeyMaterial</code> on the primary Region key with the
49+
* <code>ImportType</code>set to <code>NEW_KEY_MATERIAL</code>.</p>
50+
* </li>
51+
* <li>
52+
* <p>Call <code>ImportKeyMaterial</code> on the replica Region key with the
53+
* <code>ImportType</code> set to <code>EXISTING_KEY_MATERIAL</code> using the same key
54+
* material imported to the primary Region key. You must do this for every replica
55+
* Region key before you can perform the <a>RotateKeyOnDemand</a> operation
56+
* on the primary Region key.</p>
57+
* </li>
58+
* </ol>
4059
* <p>After you import key material, you can <a href="https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-import-key-material.html#reimport-key-material">reimport
4160
* the same key material</a> into that KMS key or, if the key supports on-demand rotation,
4261
* import new key material. You can use the <code>ImportType</code> parameter to indicate whether
@@ -68,15 +87,15 @@ export interface ImportKeyMaterialCommandOutput extends ImportKeyMaterialRespons
6887
* your key material.</p>
6988
* </li>
7089
* </ul>
71-
* <p> Then, in an <code>ImportKeyMaterial</code> request, you submit your encrypted key
90+
* <p>Then, in an <code>ImportKeyMaterial</code> request, you submit your encrypted key
7291
* material and import token. When calling this operation, you must specify the following
7392
* values:</p>
7493
* <ul>
7594
* <li>
7695
* <p>The key ID or key ARN of the KMS key to associate with the imported key material. Its
7796
* <code>Origin</code> must be <code>EXTERNAL</code> and its <code>KeyState</code> must be
78-
* <code>PendingImport</code>. You cannot perform this operation on a KMS key in a
79-
* <a href="https://docs.aws.amazon.com/kms/latest/developerguide/key-store-overview.html">custom key store</a>, or on a KMS key in a different Amazon Web Services account. To get the
97+
* <code>PendingImport</code> or <code>Enabled</code>. You cannot perform this operation on
98+
* a KMS key in a <a href="https://docs.aws.amazon.com/kms/latest/developerguide/key-store-overview.html">custom key store</a>, or on a KMS key in a different Amazon Web Services account. To get the
8099
* <code>Origin</code> and <code>KeyState</code> of a KMS key, call <a>DescribeKey</a>.</p>
81100
* </li>
82101
* <li>
@@ -96,12 +115,11 @@ export interface ImportKeyMaterialCommandOutput extends ImportKeyMaterialRespons
96115
* time you reimport, you can eliminate or reset the expiration time.</p>
97116
* </li>
98117
* </ul>
99-
* <p>When this operation is successful, the key state of the KMS key changes from
100-
* <code>PendingImport</code> to <code>Enabled</code>, and you can use the KMS key in
101-
* cryptographic operations. For single-Region, symmetric encryption keys, you will need to
102-
* import all of the key materials associated with the KMS key to change its state to
103-
* <code>Enabled</code>. Use the <code>ListKeyRotations</code> operation to list the ID and
104-
* import state of each key material associated with a KMS key.</p>
118+
* <p>When this operation is successful, the state of the KMS key changes to <code>Enabled</code>,
119+
* and you can use the KMS key in cryptographic operations. For symmetric encryption keys, you will
120+
* need to import all of the key materials associated with the KMS key to change its state to
121+
* <code>Enabled</code>. Use the <code>ListKeyRotations</code> operation to list the ID and import
122+
* state of each key material associated with a KMS key.</p>
105123
* <p>If this operation fails, use the exception to help determine the problem. If the error is
106124
* related to the key material, the import token, or wrapping key, use <a>GetParametersForImport</a> to get a new public key and import token for the KMS key
107125
* and repeat the import procedure. For help, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-conceptual.html">Create a KMS key with imported key

‎clients/client-kms/src/commands/ListKeyRotationsCommand.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ export interface ListKeyRotationsCommandOutput extends ListKeyRotationsResponse,
9999
* // KeyMaterialId: "STRING_VALUE",
100100
* // KeyMaterialDescription: "STRING_VALUE",
101101
* // ImportState: "IMPORTED" || "PENDING_IMPORT",
102-
* // KeyMaterialState: "NON_CURRENT" || "CURRENT" || "PENDING_ROTATION",
102+
* // KeyMaterialState: "NON_CURRENT" || "CURRENT" || "PENDING_ROTATION" || "PENDING_MULTI_REGION_IMPORT_AND_ROTATION",
103103
* // ExpirationModel: "KEY_MATERIAL_EXPIRES" || "KEY_MATERIAL_DOES_NOT_EXPIRE",
104104
* // ValidTo: new Date("TIMESTAMP"),
105105
* // RotationDate: new Date("TIMESTAMP"),

‎clients/client-kms/src/commands/RotateKeyOnDemandCommand.ts‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -46,15 +46,14 @@ export interface RotateKeyOnDemandCommandOutput extends RotateKeyOnDemandRespons
4646
* on-demand rotations were performed. You can monitor rotation of the key material for your KMS
4747
* keys in CloudTrail and Amazon CloudWatch.</p>
4848
* <p>On-demand key rotation is supported only on symmetric encryption KMS keys. You cannot
49-
* perform on-demand rotation of <a href="https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html">asymmetric KMS keys</a>, <a href="https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html">HMAC KMS keys</a>, multi-Region KMS
50-
* keys with <a href="https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html">imported key
51-
* material</a>, or KMS keys in a <a href="https://docs.aws.amazon.com/kms/latest/developerguide/key-store-overview.html">custom key store</a>. When you initiate on-demand key
52-
* rotation on a symmetric encryption KMS key with imported key material, you must have already
53-
* imported <a href="https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-import-key-material.html">new key material</a> and that
49+
* perform on-demand rotation of <a href="https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html">asymmetric KMS keys</a>, <a href="https://docs.aws.amazon.com/kms/latest/developerguide/hmac.html">HMAC KMS keys</a>, or KMS keys in a
50+
* <a href="https://docs.aws.amazon.com/kms/latest/developerguide/key-store-overview.html">custom key store</a>. When you initiate on-demand key rotation on a symmetric encryption KMS key
51+
* with imported key material, you must have already imported <a href="https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-import-key-material.html">new key material</a> and that
5452
* key material's state should be <code>PENDING_ROTATION</code>. Use the
5553
* <code>ListKeyRotations</code> operation to check the state of all key materials associated
56-
* with a KMS key. To perform on-demand rotation of a set of related <a href="https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#multi-region-rotate">multi-Region keys</a>, invoke
57-
* the on-demand rotation on the primary key.</p>
54+
* with a KMS key. To perform on-demand rotation of a set of related <a href="https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#multi-region-rotate">multi-Region keys</a>, import
55+
* new key material in the primary Region key, import the same key material in each replica
56+
* Region key, and invoke the on-demand rotation on the primary Region key.</p>
5857
* <p>You cannot initiate on-demand rotation of <a href="https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-key">Amazon Web Services managed KMS keys</a>. KMS
5958
* always rotates the key material of Amazon Web Services managed keys every year. Rotation of <a href="https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-key">Amazon Web Services owned KMS
6059
* keys</a> is managed by the Amazon Web Services service that owns the key.</p>

‎clients/client-kms/src/models/enums.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -427,6 +427,7 @@ export type IncludeKeyMaterial = (typeof IncludeKeyMaterial)[keyof typeof Includ
427427
export const KeyMaterialState = {
428428
CURRENT: "CURRENT",
429429
NON_CURRENT: "NON_CURRENT",
430+
PENDING_MULTI_REGION_IMPORT_AND_ROTATION: "PENDING_MULTI_REGION_IMPORT_AND_ROTATION",
430431
PENDING_ROTATION: "PENDING_ROTATION",
431432
} as const;
432433
/**

‎clients/client-kms/src/models/models_0.ts‎

Lines changed: 20 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1292,11 +1292,10 @@ export interface KeyMetadata {
12921292

12931293
/**
12941294
* <p>Identifies the current key material. This value is present for symmetric encryption keys
1295-
* with <code>AWS_KMS</code> origin and single-Region, symmetric encryption keys with
1296-
* <code>EXTERNAL</code> origin. These KMS keys support automatic or on-demand key rotation and
1297-
* can have multiple key materials associated with them. KMS uses the current key material for
1298-
* both encryption and decryption, and the non-current key material for decryption operations
1299-
* only.</p>
1295+
* with <code>AWS_KMS</code> or <code>EXTERNAL</code> origin. These KMS keys support automatic
1296+
* or on-demand key rotation and can have multiple key materials associated with them. KMS uses
1297+
* the current key material for both encryption and decryption, and the non-current key material
1298+
* for decryption operations only.</p>
13001299
* @public
13011300
*/
13021301
CurrentKeyMaterialId?: string | undefined;
@@ -3511,6 +3510,10 @@ export interface ImportKeyMaterialRequest {
35113510
* parameter defaults to <code>NEW_KEY_MATERIAL</code>. After the first key material is imported,
35123511
* if this parameter is omitted then the parameter defaults to
35133512
* <code>EXISTING_KEY_MATERIAL</code>.</p>
3513+
* <p>For multi-Region keys, you must first import new key material into
3514+
* the primary Region key. You should use the <code>NEW_KEY_MATERIAL</code> import type when importing key
3515+
* material into the primary Region key. Then, you can import the same key material into the replica Region
3516+
* key. The import type for the replica Region key should be <code>EXISTING_KEY_MATERIAL</code>.</p>
35143517
* @public
35153518
*/
35163519
ImportType?: ImportType | undefined;
@@ -3897,14 +3900,20 @@ export interface RotationsListEntry {
38973900
ImportState?: ImportState | undefined;
38983901

38993902
/**
3900-
* <p>There are three possible values for this field: <code>CURRENT</code>,
3901-
* <code>NON_CURRENT</code> and <code>PENDING_ROTATION</code>. KMS uses <code>CURRENT</code>
3903+
* <p>There are four possible values for this field: <code>CURRENT</code>,
3904+
* <code>NON_CURRENT</code>, <code>PENDING_MULTI_REGION_IMPORT_AND_ROTATION</code> and
3905+
* <code>PENDING_ROTATION</code>. KMS uses <code>CURRENT</code>
39023906
* key material for both encryption and decryption and <code>NON_CURRENT</code> key material only
39033907
* for decryption. <code>PENDING_ROTATION</code> identifies key material that has been imported
3904-
* for on-demand key rotation but the rotation hasn't completed. Key material in
3905-
* <code>PENDING_ROTATION</code> is not permanently associated with the KMS key. You can delete
3906-
* this key material and import different key material in its place. The
3907-
* <code>PENDING_ROTATION</code> value is only used in symmetric encryption keys with imported
3908+
* for on-demand key rotation but the rotation hasn't completed. The key material state
3909+
* <code>PENDING_MULTI_REGION_IMPORT_AND_ROTATION</code> is unique to multi-region,
3910+
* symmetric encryption keys with imported key material. It indicates key material that has
3911+
* been imported into the primary Region key but not all of the replica Region keys. When this key material
3912+
* is imported in to all of the replica Region keys, the key material state will change to
3913+
* <code>PENDING_ROTATION</code>. Key material in <code>PENDING_MULTI_REGION_IMPORT_AND_ROTATION</code>
3914+
* or <code>PENDING_ROTATION</code> state is not permanently associated with the KMS key. You can delete
3915+
* this key material and import different key material in its place. The <code>PENDING_MULTI_REGION_IMPORT_AND_ROTATION</code>
3916+
* and <code>PENDING_ROTATION</code> values are only used in symmetric encryption keys with imported
39083917
* key material. The other values, <code>CURRENT</code> and <code>NON_CURRENT</code>, are used
39093918
* for all KMS keys that support automatic or on-demand key rotation.</p>
39103919
* @public

0 commit comments

Comments
 (0)