2021/06/16 - AWS Key Management Service - 2 new 3 updated api methods
Changes Adds support for multi-Region keys
Replicates a multi-Region key into the specified Region. This operation creates a multi-Region replica key based on a multi-Region primary key in a different Region of the same AWS partition. You can create multiple replicas of a primary key, but each must be in a different Region. To create a multi-Region primary key, use the CreateKey operation.
This operation supports multi-Region keys , an AWS KMS feature that lets you create multiple interoperable CMKs in different AWS Regions. Because these CMKs have the same key ID, key material, and other metadata, you can use them to encrypt data in one AWS Region and decrypt it in a different AWS Region without making a cross-Region call or exposing the plaintext data. For more information about multi-Region keys, see Using multi-Region keys in the AWS Key Management Service Developer Guide .
A replica key is a fully-functional CMK that can be used independently of its primary and peer replica keys. A primary key and its replica keys share properties that make them interoperable. They have the same key ID and key material. They also have the same key spec, key usage, key material origin, and automatic key rotation status. AWS KMS automatically synchronizes these shared properties among related multi-Region keys. All other properties of a replica key can differ, including its key policy, tags, aliases, and key state. AWS KMS pricing and quotas for CMKs apply to each primary key and replica key.
When this operation completes, the new replica key has a transient key state of Creating . This key state changes to Enabled (or PendingImport ) after a few seconds when the process of creating the new replica key is complete. While the key state is Creating , you can manage key, but you cannot yet use it in cryptographic operations. If you are creating and using the replica key programmatically, retry on KMSInvalidStateException or call DescribeKey to check its KeyState value before using it. For details about the Creating key state, see Key state: Effect on your CMK in the AWS Key Management Service Developer Guide .
The AWS CloudTrail log of a ReplicateKey operation records a ReplicateKey operation in the primary key's Region and a CreateKey operation in the replica key's Region.
If you replicate a multi-Region primary key with imported key material, the replica key is created with no key material. You must import the same key material that you imported into the primary key. For details, see Importing key material into multi-Region keys in the AWS Key Management Service Developer Guide .
To convert a replica key to a primary key, use the UpdatePrimaryRegion operation.
Note
ReplicateKey uses different default values for the KeyPolicy and Tags parameters than those used in the AWS KMS console. For details, see the parameter descriptions.
Cross-account use : No. You cannot use this operation to create a CMK in a different AWS account.
Required permissions :
kms:ReplicateKey on the primary CMK (in the primary CMK's Region). Include this permission in the primary CMK's key policy.
kms:CreateKey in an IAM policy in the replica Region.
To use the Tags parameter, kms:TagResource in an IAM policy in the replica Region.
Related operations
CreateKey
UpdatePrimaryRegion
See also: AWS API Documentation
Request Syntax
client.replicate_key(
KeyId='string',
ReplicaRegion='string',
Policy='string',
BypassPolicyLockoutSafetyCheck=True|False,
Description='string',
Tags=[
{
'TagKey': 'string',
'TagValue': 'string'
},
]
)
string
[REQUIRED]
Identifies the multi-Region primary key that is being replicated. To determine whether a CMK is a multi-Region primary key, use the DescribeKey operation to check the value of the MultiRegionKeyType property.
Specify the key ID or key ARN of a multi-Region primary key.
For example:
Key ID: mrk-1234abcd12ab34cd56ef1234567890ab
Key ARN: arn:aws:kms:us-east-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab
To get the key ID and key ARN for a CMK, use ListKeys or DescribeKey.
string
[REQUIRED]
The Region ID of the AWS Region for this replica key.
Enter the Region ID, such as us-east-1 or ap-southeast-2 . For a list of AWS Regions in which AWS KMS is supported, see AWS KMS service endpoints in the Amazon Web Services General Reference .
The replica must be in a different AWS Region than its primary key and other replicas of that primary key, but in the same AWS partition. AWS KMS must be available in the replica Region. If the Region is not enabled by default, the AWS account must be enabled in the Region.
For information about AWS partitions, see Amazon Resource Names (ARNs) in the Amazon Web Services General Reference. For information about enabling and disabling Regions, see Enabling a Region and Disabling a Region in the Amazon Web Services General Reference .
string
The key policy to attach to the CMK. This parameter is optional. If you do not provide a key policy, AWS KMS attaches the default key policy to the CMK.
The key policy is not a shared property of multi-Region keys. You can specify the same key policy or a different key policy for each key in a set of related multi-Region keys. AWS KMS does not synchronize this property.
If you provide a key policy, it must meet the following criteria:
If you don't set BypassPolicyLockoutSafetyCheck to true, the key policy must give the caller kms:PutKeyPolicy permission on the replica CMK. This reduces the risk that the CMK becomes unmanageable. For more information, refer to the scenario in the Default Key Policy section of the AWS Key Management Service Developer Guide .
Each statement in the key policy must contain one or more principals. The principals in the key policy must exist and be visible to AWS KMS. When you create a new AWS principal (for example, an IAM user or role), you might need to enforce a delay before including the new principal in a key policy because the new principal might not be immediately visible to AWS KMS. For more information, see Changes that I make are not always immediately visible in the AWS Identity and Access Management User Guide .
The key policy size quota is 32 kilobytes (32768 bytes).
boolean
A flag to indicate whether to bypass the key policy lockout safety check.
Warning
Setting this value to true increases the risk that the CMK becomes unmanageable. Do not set this value to true indiscriminately.
For more information, refer to the scenario in the Default Key Policy section in the AWS Key Management Service Developer Guide .
Use this parameter only when you intend to prevent the principal that is making the request from making a subsequent PutKeyPolicy request on the CMK.
The default value is false.
string
A description of the CMK. Use a description that helps you decide whether the CMK is appropriate for a task. The default value is an empty string (no description).
The description is not a shared property of multi-Region keys. You can specify the same description or a different description for each key in a set of related multi-Region keys. AWS KMS does not synchronize this property.
list
Assigns one or more tags to the replica key. Use this parameter to tag the CMK when it is created. To tag an existing CMK, use the TagResource operation.
Note
Tagging or untagging a CMK can allow or deny permission to the CMK. For details, see Using ABAC in AWS KMS in the AWS Key Management Service Developer Guide .
To use this parameter, you must have kms:TagResource permission in an IAM policy.
Tags are not a shared property of multi-Region keys. You can specify the same tags or different tags for each key in a set of related multi-Region keys. AWS KMS does not synchronize this property.
Each tag consists of a tag key and a tag value. Both the tag key and the tag value are required, but the tag value can be an empty (null) string. You cannot have more than one tag on a CMK with the same tag key. If you specify an existing tag key with a different tag value, AWS KMS replaces the current tag value with the specified one.
When you assign tags to an AWS resource, AWS generates a cost allocation report with usage and costs aggregated by tags. Tags can also be used to control access to a CMK. For details, see Tagging Keys.
(dict) --
A key-value pair. A tag consists of a tag key and a tag value. Tag keys and tag values are both required, but tag values can be empty (null) strings.
For information about the rules that apply to tag keys and tag values, see User-Defined Tag Restrictions in the AWS Billing and Cost Management User Guide .
TagKey (string) -- [REQUIRED]
The key of the tag.
TagValue (string) -- [REQUIRED]
The value of the tag.
dict
Response Syntax
{
'ReplicaKeyMetadata': {
'AWSAccountId': 'string',
'KeyId': 'string',
'Arn': 'string',
'CreationDate': datetime(2015, 1, 1),
'Enabled': True|False,
'Description': 'string',
'KeyUsage': 'SIGN_VERIFY'|'ENCRYPT_DECRYPT',
'KeyState': 'Creating'|'Enabled'|'Disabled'|'PendingDeletion'|'PendingImport'|'PendingReplicaDeletion'|'Unavailable'|'Updating',
'DeletionDate': datetime(2015, 1, 1),
'ValidTo': datetime(2015, 1, 1),
'Origin': 'AWS_KMS'|'EXTERNAL'|'AWS_CLOUDHSM',
'CustomKeyStoreId': 'string',
'CloudHsmClusterId': 'string',
'ExpirationModel': 'KEY_MATERIAL_EXPIRES'|'KEY_MATERIAL_DOES_NOT_EXPIRE',
'KeyManager': 'AWS'|'CUSTOMER',
'CustomerMasterKeySpec': 'RSA_2048'|'RSA_3072'|'RSA_4096'|'ECC_NIST_P256'|'ECC_NIST_P384'|'ECC_NIST_P521'|'ECC_SECG_P256K1'|'SYMMETRIC_DEFAULT',
'EncryptionAlgorithms': [
'SYMMETRIC_DEFAULT'|'RSAES_OAEP_SHA_1'|'RSAES_OAEP_SHA_256',
],
'SigningAlgorithms': [
'RSASSA_PSS_SHA_256'|'RSASSA_PSS_SHA_384'|'RSASSA_PSS_SHA_512'|'RSASSA_PKCS1_V1_5_SHA_256'|'RSASSA_PKCS1_V1_5_SHA_384'|'RSASSA_PKCS1_V1_5_SHA_512'|'ECDSA_SHA_256'|'ECDSA_SHA_384'|'ECDSA_SHA_512',
],
'MultiRegion': True|False,
'MultiRegionConfiguration': {
'MultiRegionKeyType': 'PRIMARY'|'REPLICA',
'PrimaryKey': {
'Arn': 'string',
'Region': 'string'
},
'ReplicaKeys': [
{
'Arn': 'string',
'Region': 'string'
},
]
},
'PendingDeletionWindowInDays': 123
},
'ReplicaPolicy': 'string',
'ReplicaTags': [
{
'TagKey': 'string',
'TagValue': 'string'
},
]
}
Response Structure
(dict) --
ReplicaKeyMetadata (dict) --
Displays details about the new replica CMK, including its Amazon Resource Name ( key ARN ) and key state. It also includes the ARN and AWS Region of its primary key and other replica keys.
AWSAccountId (string) --
The twelve-digit account ID of the AWS account that owns the CMK.
KeyId (string) --
The globally unique identifier for the CMK.
Arn (string) --
The Amazon Resource Name (ARN) of the CMK. For examples, see AWS Key Management Service (AWS KMS) in the Example ARNs section of the AWS General Reference .
CreationDate (datetime) --
The date and time when the CMK was created.
Enabled (boolean) --
Specifies whether the CMK is enabled. When KeyState is Enabled this value is true, otherwise it is false.
Description (string) --
The description of the CMK.
KeyUsage (string) --
The cryptographic operations for which you can use the CMK.
KeyState (string) --
The current status of the CMK.
For more information about how key state affects the use of a CMK, see Key state: Effect on your CMK in the AWS Key Management Service Developer Guide .
DeletionDate (datetime) --
The date and time after which AWS KMS deletes this CMK. This value is present only when the CMK is scheduled for deletion, that is, when its KeyState is PendingDeletion .
When the primary key in a multi-Region key is scheduled for deletion but still has replica keys, its key state is PendingReplicaDeletion and the length of its waiting period is displayed in the PendingDeletionWindowInDays field.
ValidTo (datetime) --
The time at which the imported key material expires. When the key material expires, AWS KMS deletes the key material and the CMK becomes unusable. This value is present only for CMKs whose Origin is EXTERNAL and whose ExpirationModel is KEY_MATERIAL_EXPIRES , otherwise this value is omitted.
Origin (string) --
The source of the CMK's key material. When this value is AWS_KMS , AWS KMS created the key material. When this value is EXTERNAL , the key material was imported from your existing key management infrastructure or the CMK lacks key material. When this value is AWS_CLOUDHSM , the key material was created in the AWS CloudHSM cluster associated with a custom key store.
CustomKeyStoreId (string) --
A unique identifier for the custom key store that contains the CMK. This value is present only when the CMK is created in a custom key store.
CloudHsmClusterId (string) --
The cluster ID of the AWS CloudHSM cluster that contains the key material for the CMK. When you create a CMK in a custom key store, AWS KMS creates the key material for the CMK in the associated AWS CloudHSM cluster. This value is present only when the CMK is created in a custom key store.
ExpirationModel (string) --
Specifies whether the CMK's key material expires. This value is present only when Origin is EXTERNAL , otherwise this value is omitted.
KeyManager (string) --
The manager of the CMK. CMKs in your AWS account are either customer managed or AWS managed. For more information about the difference, see Customer Master Keys in the AWS Key Management Service Developer Guide .
CustomerMasterKeySpec (string) --
Describes the type of key material in the CMK.
EncryptionAlgorithms (list) --
The encryption algorithms that the CMK supports. You cannot use the CMK with other encryption algorithms within AWS KMS.
This value is present only when the KeyUsage of the CMK is ENCRYPT_DECRYPT .
(string) --
SigningAlgorithms (list) --
The signing algorithms that the CMK supports. You cannot use the CMK with other signing algorithms within AWS KMS.
This field appears only when the KeyUsage of the CMK is SIGN_VERIFY .
(string) --
MultiRegion (boolean) --
Indicates whether the CMK is a multi-Region ( True ) or regional ( False ) key. This value is True for multi-Region primary and replica CMKs and False for regional CMKs.
For more information about multi-Region keys, see Using multi-Region keys in the AWS Key Management Service Developer Guide .
MultiRegionConfiguration (dict) --
Lists the primary and replica CMKs in same multi-Region CMK. This field is present only when the value of the MultiRegion field is True .
For more information about any listed CMK, use the DescribeKey operation.
MultiRegionKeyType indicates whether the CMK is a PRIMARY or REPLICA key.
PrimaryKey displays the key ARN and Region of the primary key. This field displays the current CMK if it is the primary key.
ReplicaKeys displays the key ARNs and Regions of all replica keys. This field includes the current CMK if it is a replica key.
MultiRegionKeyType (string) --
Indicates whether the CMK is a PRIMARY or REPLICA key.
PrimaryKey (dict) --
Displays the key ARN and Region of the primary key. This field includes the current CMK if it is the primary key.
Arn (string) --
Displays the key ARN of a primary or replica key of a multi-Region key.
Region (string) --
Displays the AWS Region of a primary or replica key in a multi-Region key.
ReplicaKeys (list) --
displays the key ARNs and Regions of all replica keys. This field includes the current CMK if it is a replica key.
(dict) --
Describes the primary or replica key in a multi-Region key.
Arn (string) --
Displays the key ARN of a primary or replica key of a multi-Region key.
Region (string) --
Displays the AWS Region of a primary or replica key in a multi-Region key.
PendingDeletionWindowInDays (integer) --
The waiting period before the primary key in a multi-Region key is deleted. This waiting period begins when the last of its replica keys is deleted. This value is present only when the KeyState of the CMK is PendingReplicaDeletion . That indicates that the CMK is the primary key in a multi-Region key, it is scheduled for deletion, and it still has existing replica keys.
When a regional CMK or a replica key in a multi-Region key is scheduled for deletion, its deletion date is displayed in the DeletionDate field. However, when the primary key in a multi-Region key is scheduled for deletion, its waiting period doesn't begin until all of its replica keys are deleted. This value displays that waiting period. When the last replica key in the multi-Region key is deleted, the KeyState of the scheduled primary key changes from PendingReplicaDeletion to PendingDeletion and the deletion date appears in the DeletionDate field.
ReplicaPolicy (string) --
The key policy of the new replica key. The value is a key policy document in JSON format.
ReplicaTags (list) --
The tags on the new replica key. The value is a list of tag key and tag value pairs.
(dict) --
A key-value pair. A tag consists of a tag key and a tag value. Tag keys and tag values are both required, but tag values can be empty (null) strings.
For information about the rules that apply to tag keys and tag values, see User-Defined Tag Restrictions in the AWS Billing and Cost Management User Guide .
TagKey (string) --
The key of the tag.
TagValue (string) --
The value of the tag.
Changes the primary key of a multi-Region key.
This operation changes the replica key in the specified Region to a primary key and changes the former primary key to a replica key. For example, suppose you have a primary key in us-east-1 and a replica key in eu-west-2 . If you run UpdatePrimaryRegion with a PrimaryRegion value of eu-west-2 , the primary key is now the key in eu-west-2 , and the key in us-east-1 becomes a replica key. For details, see
This operation supports multi-Region keys , an AWS KMS feature that lets you create multiple interoperable CMKs in different AWS Regions. Because these CMKs have the same key ID, key material, and other metadata, you can use them to encrypt data in one AWS Region and decrypt it in a different AWS Region without making a cross-Region call or exposing the plaintext data. For more information about multi-Region keys, see Using multi-Region keys in the AWS Key Management Service Developer Guide .
The primary key of a multi-Region key is the source for properties that are always shared by primary and replica keys, including the key material, key ID, key spec, key usage, key material origin, and automatic key rotation. It's the only key that can be replicated. You cannot delete the primary key until all replicas are deleted.
The key ID and primary Region that you specify uniquely identify the replica key that will become the primary key. The primary Region must already have a replica key. This operation does not create a CMK in the specified Region. To find the replica keys, use the DescribeKey operation on the primary key or any replica key. To create a replica key, use the ReplicateKey operation.
You can run this operation while using the affected multi-Region keys in cryptographic operations. This operation should not delay, interrupt, or cause failures in cryptographic operations.
Even after this operation completes, the process of updating the primary Region might still be in progress for a few more seconds. Operations such as DescribeKey might display both the old and new primary keys as replicas. The old and new primary keys have a transient key state of Updating . The original key state is restored when the update is complete. While the key state is Updating , you can use the keys in cryptographic operations, but you cannot replicate the new primary key or perform certain management operations, such as enabling or disabling these keys. For details about the Updating key state, see Key state: Effect on your CMK in the AWS Key Management Service Developer Guide .
This operation does not return any output. To verify that primary key is changed, use the DescribeKey operation.
Cross-account use : No. You cannot use this operation in a different AWS account.
Required permissions :
kms:UpdatePrimaryRegion on the current primary CMK (in the primary CMK's Region). Include this permission primary CMK's key policy.
kms:UpdatePrimaryRegion on the current replica CMK (in the replica CMK's Region). Include this permission in the replica CMK's key policy.
Related operations
CreateKey
ReplicateKey
See also: AWS API Documentation
Request Syntax
client.update_primary_region(
KeyId='string',
PrimaryRegion='string'
)
string
[REQUIRED]
Identifies the current primary key. When the operation completes, this CMK will be a replica key.
Specify the key ID or key ARN of a multi-Region primary key.
For example:
Key ID: mrk-1234abcd12ab34cd56ef1234567890ab
Key ARN: arn:aws:kms:us-east-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab
To get the key ID and key ARN for a CMK, use ListKeys or DescribeKey.
string
[REQUIRED]
The AWS Region of the new primary key. Enter the Region ID, such as us-east-1 or ap-southeast-2 . There must be an existing replica key in this Region.
When the operation completes, the multi-Region key in this Region will be the primary key.
None
{'MultiRegion': 'boolean'}
Response {'KeyMetadata': {'KeyState': {'Creating', 'Updating', 'PendingReplicaDeletion'},
'MultiRegion': 'boolean',
'MultiRegionConfiguration': {'MultiRegionKeyType': 'PRIMARY | '
'REPLICA',
'PrimaryKey': {'Arn': 'string',
'Region': 'string'},
'ReplicaKeys': [{'Arn': 'string',
'Region': 'string'}]},
'PendingDeletionWindowInDays': 'integer'}}
Creates a unique customer managed customer master key (CMK) in your AWS account and Region.
You can use the CreateKey operation to create symmetric or asymmetric CMKs.
Symmetric CMKs contain a 256-bit symmetric key that never leaves AWS KMS unencrypted. To use the CMK, you must call AWS KMS. You can use a symmetric CMK to encrypt and decrypt small amounts of data, but they are typically used to generate data keys and data keys pairs. For details, see GenerateDataKey and GenerateDataKeyPair.
Asymmetric CMKs can contain an RSA key pair or an Elliptic Curve (ECC) key pair. The private key in an asymmetric CMK never leaves AWS KMS unencrypted. However, you can use the GetPublicKey operation to download the public key so it can be used outside of AWS KMS. CMKs with RSA key pairs can be used to encrypt or decrypt data or sign and verify messages (but not both). CMKs with ECC key pairs can be used only to sign and verify messages.
For information about symmetric and asymmetric CMKs, see Using Symmetric and Asymmetric CMKs in the AWS Key Management Service Developer Guide .
To create different types of CMKs, use the following guidance:
Asymmetric CMKs
To create an asymmetric CMK, use the CustomerMasterKeySpec parameter to specify the type of key material in the CMK. Then, use the KeyUsage parameter to determine whether the CMK will be used to encrypt and decrypt or sign and verify. You can't change these properties after the CMK is created.
Symmetric CMKs
When creating a symmetric CMK, you don't need to specify the CustomerMasterKeySpec or KeyUsage parameters. The default value for CustomerMasterKeySpec , SYMMETRIC_DEFAULT , and the default value for KeyUsage , ENCRYPT_DECRYPT , are the only valid values for symmetric CMKs.
Multi-Region primary keys Imported key material
To create a multi-Region primary key in the local AWS Region, use the MultiRegion parameter with a value of True . To create a multi-Region replica key , that is, a CMK with the same key ID and key material as a primary key, but in a different AWS Region, use the ReplicateKey operation. To change a replica key to a primary key, and its primary key to a replica key, use the UpdatePrimaryRegion operation.
This operation supports multi-Region keys , an AWS KMS feature that lets you create multiple interoperable CMKs in different AWS Regions. Because these CMKs have the same key ID, key material, and other metadata, you can use them to encrypt data in one AWS Region and decrypt it in a different AWS Region without making a cross-Region call or exposing the plaintext data. For more information about multi-Region keys, see Using multi-Region keys in the AWS Key Management Service Developer Guide .
You can create symmetric and asymmetric multi-Region keys and multi-Region keys with imported key material. You cannot create multi-Region keys in a custom key store.
To import your own key material, begin by creating a symmetric CMK with no key material. To do this, use the Origin parameter of CreateKey with a value of EXTERNAL . Next, use GetParametersForImport operation to get a public key and import token, and use the public key to encrypt your key material. Then, use ImportKeyMaterial with your import token to import the key material. For step-by-step instructions, see Importing Key Material in the AWS Key Management Service Developer Guide . You cannot import the key material into an asymmetric CMK.
To create a multi-Region primary key with imported key material, use the Origin parameter of CreateKey with a value of EXTERNAL and the MultiRegion parameter with a value of True . To create replicas of the multi-Region primary key, use the ReplicateKey operation. For more information about multi-Region keys, see Using multi-Region keys in the AWS Key Management Service Developer Guide .
Custom key store
To create a symmetric CMK in a custom key store, use the CustomKeyStoreId parameter to specify the custom key store. You must also use the Origin parameter with a value of AWS_CLOUDHSM . The AWS CloudHSM cluster that is associated with the custom key store must have at least two active HSMs in different Availability Zones in the AWS Region.
You cannot create an asymmetric CMK or a multi-Region CMK in a custom key store. For information about custom key stores in AWS KMS see Using Custom Key Stores in the AWS Key Management Service Developer Guide .
Cross-account use : No. You cannot use this operation to create a CMK in a different AWS account.
Required permissions : kms:CreateKey (IAM policy). To use the Tags parameter, kms:TagResource (IAM policy). For examples and information about related permissions, see Allow a user to create CMKs in the AWS Key Management Service Developer Guide .
Related operations:
DescribeKey
ListKeys
ScheduleKeyDeletion
See also: AWS API Documentation
Request Syntax
client.create_key(
Policy='string',
Description='string',
KeyUsage='SIGN_VERIFY'|'ENCRYPT_DECRYPT',
CustomerMasterKeySpec='RSA_2048'|'RSA_3072'|'RSA_4096'|'ECC_NIST_P256'|'ECC_NIST_P384'|'ECC_NIST_P521'|'ECC_SECG_P256K1'|'SYMMETRIC_DEFAULT',
Origin='AWS_KMS'|'EXTERNAL'|'AWS_CLOUDHSM',
CustomKeyStoreId='string',
BypassPolicyLockoutSafetyCheck=True|False,
Tags=[
{
'TagKey': 'string',
'TagValue': 'string'
},
],
MultiRegion=True|False
)
string
The key policy to attach to the CMK.
If you provide a key policy, it must meet the following criteria:
If you don't set BypassPolicyLockoutSafetyCheck to true, the key policy must allow the principal that is making the CreateKey request to make a subsequent PutKeyPolicy request on the CMK. This reduces the risk that the CMK becomes unmanageable. For more information, refer to the scenario in the Default Key Policy section of the AWS Key Management Service Developer Guide .
Each statement in the key policy must contain one or more principals. The principals in the key policy must exist and be visible to AWS KMS. When you create a new AWS principal (for example, an IAM user or role), you might need to enforce a delay before including the new principal in a key policy because the new principal might not be immediately visible to AWS KMS. For more information, see Changes that I make are not always immediately visible in the AWS Identity and Access Management User Guide .
If you do not provide a key policy, AWS KMS attaches a default key policy to the CMK. For more information, see Default Key Policy in the AWS Key Management Service Developer Guide .
The key policy size quota is 32 kilobytes (32768 bytes).
For help writing and formatting a JSON policy document, see the IAM JSON Policy Reference in the IAM User Guide .
string
A description of the CMK.
Use a description that helps you decide whether the CMK is appropriate for a task. The default value is an empty string (no description).
string
Determines the cryptographic operations for which you can use the CMK. The default value is ENCRYPT_DECRYPT . This parameter is required only for asymmetric CMKs. You can't change the KeyUsage value after the CMK is created.
Select only one valid value.
For symmetric CMKs, omit the parameter or specify ENCRYPT_DECRYPT .
For asymmetric CMKs with RSA key material, specify ENCRYPT_DECRYPT or SIGN_VERIFY .
For asymmetric CMKs with ECC key material, specify SIGN_VERIFY .
string
Specifies the type of CMK to create. The default value, SYMMETRIC_DEFAULT , creates a CMK with a 256-bit symmetric key for encryption and decryption. For help choosing a key spec for your CMK, see How to Choose Your CMK Configuration in the AWS Key Management Service Developer Guide .
The CustomerMasterKeySpec determines whether the CMK contains a symmetric key or an asymmetric key pair. It also determines the encryption algorithms or signing algorithms that the CMK supports. You can't change the CustomerMasterKeySpec after the CMK is created. To further restrict the algorithms that can be used with the CMK, use a condition key in its key policy or IAM policy. For more information, see kms:EncryptionAlgorithm or kms:Signing Algorithm in the AWS Key Management Service Developer Guide .
Warning
AWS services that are integrated with AWS KMS use symmetric CMKs to protect your data. These services do not support asymmetric CMKs. For help determining whether a CMK is symmetric or asymmetric, see Identifying Symmetric and Asymmetric CMKs in the AWS Key Management Service Developer Guide .
AWS KMS supports the following key specs for CMKs:
Symmetric key (default)
SYMMETRIC_DEFAULT (AES-256-GCM)
Asymmetric RSA key pairs
RSA_2048
RSA_3072
RSA_4096
Asymmetric NIST-recommended elliptic curve key pairs
ECC_NIST_P256 (secp256r1)
ECC_NIST_P384 (secp384r1)
ECC_NIST_P521 (secp521r1)
Other asymmetric elliptic curve key pairs
ECC_SECG_P256K1 (secp256k1), commonly used for cryptocurrencies.
string
The source of the key material for the CMK. You cannot change the origin after you create the CMK. The default is AWS_KMS , which means that AWS KMS creates the key material.
To create a CMK with no key material (for imported key material), set the value to EXTERNAL . For more information about importing key material into AWS KMS, see Importing Key Material in the AWS Key Management Service Developer Guide . This value is valid only for symmetric CMKs.
To create a CMK in an AWS KMS custom key store and create its key material in the associated AWS CloudHSM cluster, set this value to AWS_CLOUDHSM . You must also use the CustomKeyStoreId parameter to identify the custom key store. This value is valid only for symmetric CMKs.
string
Creates the CMK in the specified custom key store and the key material in its associated AWS CloudHSM cluster. To create a CMK in a custom key store, you must also specify the Origin parameter with a value of AWS_CLOUDHSM . The AWS CloudHSM cluster that is associated with the custom key store must have at least two active HSMs, each in a different Availability Zone in the Region.
This parameter is valid only for symmetric CMKs and regional CMKs. You cannot create an asymmetric CMK or a multi-Region CMK in a custom key store.
To find the ID of a custom key store, use the DescribeCustomKeyStores operation.
The response includes the custom key store ID and the ID of the AWS CloudHSM cluster.
This operation is part of the Custom Key Store feature feature in AWS KMS, which combines the convenience and extensive integration of AWS KMS with the isolation and control of a single-tenant key store.
boolean
A flag to indicate whether to bypass the key policy lockout safety check.
Warning
Setting this value to true increases the risk that the CMK becomes unmanageable. Do not set this value to true indiscriminately.
For more information, refer to the scenario in the Default Key Policy section in the AWS Key Management Service Developer Guide .
Use this parameter only when you include a policy in the request and you intend to prevent the principal that is making the request from making a subsequent PutKeyPolicy request on the CMK.
The default value is false.
list
Assigns one or more tags to the CMK. Use this parameter to tag the CMK when it is created. To tag an existing CMK, use the TagResource operation.
Note
Tagging or untagging a CMK can allow or deny permission to the CMK. For details, see Using ABAC in AWS KMS in the AWS Key Management Service Developer Guide .
To use this parameter, you must have kms:TagResource permission in an IAM policy.
Each tag consists of a tag key and a tag value. Both the tag key and the tag value are required, but the tag value can be an empty (null) string. You cannot have more than one tag on a CMK with the same tag key. If you specify an existing tag key with a different tag value, AWS KMS replaces the current tag value with the specified one.
When you assign tags to an AWS resource, AWS generates a cost allocation report with usage and costs aggregated by tags. Tags can also be used to control access to a CMK. For details, see Tagging Keys.
(dict) --
A key-value pair. A tag consists of a tag key and a tag value. Tag keys and tag values are both required, but tag values can be empty (null) strings.
For information about the rules that apply to tag keys and tag values, see User-Defined Tag Restrictions in the AWS Billing and Cost Management User Guide .
TagKey (string) -- [REQUIRED]
The key of the tag.
TagValue (string) -- [REQUIRED]
The value of the tag.
boolean
Creates a multi-Region primary key that you can replicate into other AWS Regions. You cannot change this value after you create the CMK.
For a multi-Region key, set this parameter to True . For a single-Region CMK, omit this parameter or set it to False . The default value is False .
This operation supports multi-Region keys , an AWS KMS feature that lets you create multiple interoperable CMKs in different AWS Regions. Because these CMKs have the same key ID, key material, and other metadata, you can use them to encrypt data in one AWS Region and decrypt it in a different AWS Region without making a cross-Region call or exposing the plaintext data. For more information about multi-Region keys, see Using multi-Region keys in the AWS Key Management Service Developer Guide .
This value creates a primary key , not a replica. To create a replica key , use the ReplicateKey operation.
You can create a symmetric or asymmetric multi-Region CMK, and you can create a multi-Region CMK with imported key material. However, you cannot create a multi-Region CMK in a custom key store.
dict
Response Syntax
{
'KeyMetadata': {
'AWSAccountId': 'string',
'KeyId': 'string',
'Arn': 'string',
'CreationDate': datetime(2015, 1, 1),
'Enabled': True|False,
'Description': 'string',
'KeyUsage': 'SIGN_VERIFY'|'ENCRYPT_DECRYPT',
'KeyState': 'Creating'|'Enabled'|'Disabled'|'PendingDeletion'|'PendingImport'|'PendingReplicaDeletion'|'Unavailable'|'Updating',
'DeletionDate': datetime(2015, 1, 1),
'ValidTo': datetime(2015, 1, 1),
'Origin': 'AWS_KMS'|'EXTERNAL'|'AWS_CLOUDHSM',
'CustomKeyStoreId': 'string',
'CloudHsmClusterId': 'string',
'ExpirationModel': 'KEY_MATERIAL_EXPIRES'|'KEY_MATERIAL_DOES_NOT_EXPIRE',
'KeyManager': 'AWS'|'CUSTOMER',
'CustomerMasterKeySpec': 'RSA_2048'|'RSA_3072'|'RSA_4096'|'ECC_NIST_P256'|'ECC_NIST_P384'|'ECC_NIST_P521'|'ECC_SECG_P256K1'|'SYMMETRIC_DEFAULT',
'EncryptionAlgorithms': [
'SYMMETRIC_DEFAULT'|'RSAES_OAEP_SHA_1'|'RSAES_OAEP_SHA_256',
],
'SigningAlgorithms': [
'RSASSA_PSS_SHA_256'|'RSASSA_PSS_SHA_384'|'RSASSA_PSS_SHA_512'|'RSASSA_PKCS1_V1_5_SHA_256'|'RSASSA_PKCS1_V1_5_SHA_384'|'RSASSA_PKCS1_V1_5_SHA_512'|'ECDSA_SHA_256'|'ECDSA_SHA_384'|'ECDSA_SHA_512',
],
'MultiRegion': True|False,
'MultiRegionConfiguration': {
'MultiRegionKeyType': 'PRIMARY'|'REPLICA',
'PrimaryKey': {
'Arn': 'string',
'Region': 'string'
},
'ReplicaKeys': [
{
'Arn': 'string',
'Region': 'string'
},
]
},
'PendingDeletionWindowInDays': 123
}
}
Response Structure
(dict) --
KeyMetadata (dict) --
Metadata associated with the CMK.
AWSAccountId (string) --
The twelve-digit account ID of the AWS account that owns the CMK.
KeyId (string) --
The globally unique identifier for the CMK.
Arn (string) --
The Amazon Resource Name (ARN) of the CMK. For examples, see AWS Key Management Service (AWS KMS) in the Example ARNs section of the AWS General Reference .
CreationDate (datetime) --
The date and time when the CMK was created.
Enabled (boolean) --
Specifies whether the CMK is enabled. When KeyState is Enabled this value is true, otherwise it is false.
Description (string) --
The description of the CMK.
KeyUsage (string) --
The cryptographic operations for which you can use the CMK.
KeyState (string) --
The current status of the CMK.
For more information about how key state affects the use of a CMK, see Key state: Effect on your CMK in the AWS Key Management Service Developer Guide .
DeletionDate (datetime) --
The date and time after which AWS KMS deletes this CMK. This value is present only when the CMK is scheduled for deletion, that is, when its KeyState is PendingDeletion .
When the primary key in a multi-Region key is scheduled for deletion but still has replica keys, its key state is PendingReplicaDeletion and the length of its waiting period is displayed in the PendingDeletionWindowInDays field.
ValidTo (datetime) --
The time at which the imported key material expires. When the key material expires, AWS KMS deletes the key material and the CMK becomes unusable. This value is present only for CMKs whose Origin is EXTERNAL and whose ExpirationModel is KEY_MATERIAL_EXPIRES , otherwise this value is omitted.
Origin (string) --
The source of the CMK's key material. When this value is AWS_KMS , AWS KMS created the key material. When this value is EXTERNAL , the key material was imported from your existing key management infrastructure or the CMK lacks key material. When this value is AWS_CLOUDHSM , the key material was created in the AWS CloudHSM cluster associated with a custom key store.
CustomKeyStoreId (string) --
A unique identifier for the custom key store that contains the CMK. This value is present only when the CMK is created in a custom key store.
CloudHsmClusterId (string) --
The cluster ID of the AWS CloudHSM cluster that contains the key material for the CMK. When you create a CMK in a custom key store, AWS KMS creates the key material for the CMK in the associated AWS CloudHSM cluster. This value is present only when the CMK is created in a custom key store.
ExpirationModel (string) --
Specifies whether the CMK's key material expires. This value is present only when Origin is EXTERNAL , otherwise this value is omitted.
KeyManager (string) --
The manager of the CMK. CMKs in your AWS account are either customer managed or AWS managed. For more information about the difference, see Customer Master Keys in the AWS Key Management Service Developer Guide .
CustomerMasterKeySpec (string) --
Describes the type of key material in the CMK.
EncryptionAlgorithms (list) --
The encryption algorithms that the CMK supports. You cannot use the CMK with other encryption algorithms within AWS KMS.
This value is present only when the KeyUsage of the CMK is ENCRYPT_DECRYPT .
(string) --
SigningAlgorithms (list) --
The signing algorithms that the CMK supports. You cannot use the CMK with other signing algorithms within AWS KMS.
This field appears only when the KeyUsage of the CMK is SIGN_VERIFY .
(string) --
MultiRegion (boolean) --
Indicates whether the CMK is a multi-Region ( True ) or regional ( False ) key. This value is True for multi-Region primary and replica CMKs and False for regional CMKs.
For more information about multi-Region keys, see Using multi-Region keys in the AWS Key Management Service Developer Guide .
MultiRegionConfiguration (dict) --
Lists the primary and replica CMKs in same multi-Region CMK. This field is present only when the value of the MultiRegion field is True .
For more information about any listed CMK, use the DescribeKey operation.
MultiRegionKeyType indicates whether the CMK is a PRIMARY or REPLICA key.
PrimaryKey displays the key ARN and Region of the primary key. This field displays the current CMK if it is the primary key.
ReplicaKeys displays the key ARNs and Regions of all replica keys. This field includes the current CMK if it is a replica key.
MultiRegionKeyType (string) --
Indicates whether the CMK is a PRIMARY or REPLICA key.
PrimaryKey (dict) --
Displays the key ARN and Region of the primary key. This field includes the current CMK if it is the primary key.
Arn (string) --
Displays the key ARN of a primary or replica key of a multi-Region key.
Region (string) --
Displays the AWS Region of a primary or replica key in a multi-Region key.
ReplicaKeys (list) --
displays the key ARNs and Regions of all replica keys. This field includes the current CMK if it is a replica key.
(dict) --
Describes the primary or replica key in a multi-Region key.
Arn (string) --
Displays the key ARN of a primary or replica key of a multi-Region key.
Region (string) --
Displays the AWS Region of a primary or replica key in a multi-Region key.
PendingDeletionWindowInDays (integer) --
The waiting period before the primary key in a multi-Region key is deleted. This waiting period begins when the last of its replica keys is deleted. This value is present only when the KeyState of the CMK is PendingReplicaDeletion . That indicates that the CMK is the primary key in a multi-Region key, it is scheduled for deletion, and it still has existing replica keys.
When a regional CMK or a replica key in a multi-Region key is scheduled for deletion, its deletion date is displayed in the DeletionDate field. However, when the primary key in a multi-Region key is scheduled for deletion, its waiting period doesn't begin until all of its replica keys are deleted. This value displays that waiting period. When the last replica key in the multi-Region key is deleted, the KeyState of the scheduled primary key changes from PendingReplicaDeletion to PendingDeletion and the deletion date appears in the DeletionDate field.
{'KeyMetadata': {'KeyState': {'Creating', 'Updating', 'PendingReplicaDeletion'},
'MultiRegion': 'boolean',
'MultiRegionConfiguration': {'MultiRegionKeyType': 'PRIMARY | '
'REPLICA',
'PrimaryKey': {'Arn': 'string',
'Region': 'string'},
'ReplicaKeys': [{'Arn': 'string',
'Region': 'string'}]},
'PendingDeletionWindowInDays': 'integer'}}
Provides detailed information about a customer master key (CMK). You can run DescribeKey on a customer managed CMK or an AWS managed CMK.
This detailed information includes the key ARN, creation date (and deletion date, if applicable), the key state, and the origin and expiration date (if any) of the key material. For CMKs in custom key stores, it includes information about the custom key store, such as the key store ID and the AWS CloudHSM cluster ID. It includes fields, like KeySpec , that help you distinguish symmetric from asymmetric CMKs. It also provides information that is particularly important to asymmetric CMKs, such as the key usage (encryption or signing) and the encryption algorithms or signing algorithms that the CMK supports.
DescribeKey does not return the following information:
Aliases associated with the CMK. To get this information, use ListAliases.
Whether automatic key rotation is enabled on the CMK. To get this information, use GetKeyRotationStatus. Also, some key states prevent a CMK from being automatically rotated. For details, see How Automatic Key Rotation Works in AWS Key Management Service Developer Guide .
Tags on the CMK. To get this information, use ListResourceTags.
Key policies and grants on the CMK. To get this information, use GetKeyPolicy and ListGrants.
If you call the DescribeKey operation on a predefined AWS alias , that is, an AWS alias with no key ID, AWS KMS creates an AWS managed CMK. Then, it associates the alias with the new CMK, and returns the KeyId and Arn of the new CMK in the response.
Cross-account use : Yes. To perform this operation with a CMK in a different AWS account, specify the key ARN or alias ARN in the value of the KeyId parameter.
Required permissions : kms:DescribeKey (key policy)
Related operations:
GetKeyPolicy
GetKeyRotationStatus
ListAliases
ListGrants
ListKeys
ListResourceTags
ListRetirableGrants
See also: AWS API Documentation
Request Syntax
client.describe_key(
KeyId='string',
GrantTokens=[
'string',
]
)
string
[REQUIRED]
Describes the specified customer master key (CMK).
If you specify a predefined AWS alias (an AWS alias with no key ID), KMS associates the alias with an AWS managed CMK and returns its KeyId and Arn in the response.
To specify a CMK, use its key ID, key ARN, alias name, or alias ARN. When using an alias name, prefix it with "alias/" . To specify a CMK in a different AWS account, you must use the key ARN or alias ARN.
For example:
Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab
Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
Alias name: alias/ExampleAlias
Alias ARN: arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias
To get the key ID and key ARN for a CMK, use ListKeys or DescribeKey. To get the alias name and alias ARN, use ListAliases.
list
A list of grant tokens.
Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency . For more information, see Grant token in the AWS Key Management Service Developer Guide .
(string) --
dict
Response Syntax
{
'KeyMetadata': {
'AWSAccountId': 'string',
'KeyId': 'string',
'Arn': 'string',
'CreationDate': datetime(2015, 1, 1),
'Enabled': True|False,
'Description': 'string',
'KeyUsage': 'SIGN_VERIFY'|'ENCRYPT_DECRYPT',
'KeyState': 'Creating'|'Enabled'|'Disabled'|'PendingDeletion'|'PendingImport'|'PendingReplicaDeletion'|'Unavailable'|'Updating',
'DeletionDate': datetime(2015, 1, 1),
'ValidTo': datetime(2015, 1, 1),
'Origin': 'AWS_KMS'|'EXTERNAL'|'AWS_CLOUDHSM',
'CustomKeyStoreId': 'string',
'CloudHsmClusterId': 'string',
'ExpirationModel': 'KEY_MATERIAL_EXPIRES'|'KEY_MATERIAL_DOES_NOT_EXPIRE',
'KeyManager': 'AWS'|'CUSTOMER',
'CustomerMasterKeySpec': 'RSA_2048'|'RSA_3072'|'RSA_4096'|'ECC_NIST_P256'|'ECC_NIST_P384'|'ECC_NIST_P521'|'ECC_SECG_P256K1'|'SYMMETRIC_DEFAULT',
'EncryptionAlgorithms': [
'SYMMETRIC_DEFAULT'|'RSAES_OAEP_SHA_1'|'RSAES_OAEP_SHA_256',
],
'SigningAlgorithms': [
'RSASSA_PSS_SHA_256'|'RSASSA_PSS_SHA_384'|'RSASSA_PSS_SHA_512'|'RSASSA_PKCS1_V1_5_SHA_256'|'RSASSA_PKCS1_V1_5_SHA_384'|'RSASSA_PKCS1_V1_5_SHA_512'|'ECDSA_SHA_256'|'ECDSA_SHA_384'|'ECDSA_SHA_512',
],
'MultiRegion': True|False,
'MultiRegionConfiguration': {
'MultiRegionKeyType': 'PRIMARY'|'REPLICA',
'PrimaryKey': {
'Arn': 'string',
'Region': 'string'
},
'ReplicaKeys': [
{
'Arn': 'string',
'Region': 'string'
},
]
},
'PendingDeletionWindowInDays': 123
}
}
Response Structure
(dict) --
KeyMetadata (dict) --
Metadata associated with the key.
AWSAccountId (string) --
The twelve-digit account ID of the AWS account that owns the CMK.
KeyId (string) --
The globally unique identifier for the CMK.
Arn (string) --
The Amazon Resource Name (ARN) of the CMK. For examples, see AWS Key Management Service (AWS KMS) in the Example ARNs section of the AWS General Reference .
CreationDate (datetime) --
The date and time when the CMK was created.
Enabled (boolean) --
Specifies whether the CMK is enabled. When KeyState is Enabled this value is true, otherwise it is false.
Description (string) --
The description of the CMK.
KeyUsage (string) --
The cryptographic operations for which you can use the CMK.
KeyState (string) --
The current status of the CMK.
For more information about how key state affects the use of a CMK, see Key state: Effect on your CMK in the AWS Key Management Service Developer Guide .
DeletionDate (datetime) --
The date and time after which AWS KMS deletes this CMK. This value is present only when the CMK is scheduled for deletion, that is, when its KeyState is PendingDeletion .
When the primary key in a multi-Region key is scheduled for deletion but still has replica keys, its key state is PendingReplicaDeletion and the length of its waiting period is displayed in the PendingDeletionWindowInDays field.
ValidTo (datetime) --
The time at which the imported key material expires. When the key material expires, AWS KMS deletes the key material and the CMK becomes unusable. This value is present only for CMKs whose Origin is EXTERNAL and whose ExpirationModel is KEY_MATERIAL_EXPIRES , otherwise this value is omitted.
Origin (string) --
The source of the CMK's key material. When this value is AWS_KMS , AWS KMS created the key material. When this value is EXTERNAL , the key material was imported from your existing key management infrastructure or the CMK lacks key material. When this value is AWS_CLOUDHSM , the key material was created in the AWS CloudHSM cluster associated with a custom key store.
CustomKeyStoreId (string) --
A unique identifier for the custom key store that contains the CMK. This value is present only when the CMK is created in a custom key store.
CloudHsmClusterId (string) --
The cluster ID of the AWS CloudHSM cluster that contains the key material for the CMK. When you create a CMK in a custom key store, AWS KMS creates the key material for the CMK in the associated AWS CloudHSM cluster. This value is present only when the CMK is created in a custom key store.
ExpirationModel (string) --
Specifies whether the CMK's key material expires. This value is present only when Origin is EXTERNAL , otherwise this value is omitted.
KeyManager (string) --
The manager of the CMK. CMKs in your AWS account are either customer managed or AWS managed. For more information about the difference, see Customer Master Keys in the AWS Key Management Service Developer Guide .
CustomerMasterKeySpec (string) --
Describes the type of key material in the CMK.
EncryptionAlgorithms (list) --
The encryption algorithms that the CMK supports. You cannot use the CMK with other encryption algorithms within AWS KMS.
This value is present only when the KeyUsage of the CMK is ENCRYPT_DECRYPT .
(string) --
SigningAlgorithms (list) --
The signing algorithms that the CMK supports. You cannot use the CMK with other signing algorithms within AWS KMS.
This field appears only when the KeyUsage of the CMK is SIGN_VERIFY .
(string) --
MultiRegion (boolean) --
Indicates whether the CMK is a multi-Region ( True ) or regional ( False ) key. This value is True for multi-Region primary and replica CMKs and False for regional CMKs.
For more information about multi-Region keys, see Using multi-Region keys in the AWS Key Management Service Developer Guide .
MultiRegionConfiguration (dict) --
Lists the primary and replica CMKs in same multi-Region CMK. This field is present only when the value of the MultiRegion field is True .
For more information about any listed CMK, use the DescribeKey operation.
MultiRegionKeyType indicates whether the CMK is a PRIMARY or REPLICA key.
PrimaryKey displays the key ARN and Region of the primary key. This field displays the current CMK if it is the primary key.
ReplicaKeys displays the key ARNs and Regions of all replica keys. This field includes the current CMK if it is a replica key.
MultiRegionKeyType (string) --
Indicates whether the CMK is a PRIMARY or REPLICA key.
PrimaryKey (dict) --
Displays the key ARN and Region of the primary key. This field includes the current CMK if it is the primary key.
Arn (string) --
Displays the key ARN of a primary or replica key of a multi-Region key.
Region (string) --
Displays the AWS Region of a primary or replica key in a multi-Region key.
ReplicaKeys (list) --
displays the key ARNs and Regions of all replica keys. This field includes the current CMK if it is a replica key.
(dict) --
Describes the primary or replica key in a multi-Region key.
Arn (string) --
Displays the key ARN of a primary or replica key of a multi-Region key.
Region (string) --
Displays the AWS Region of a primary or replica key in a multi-Region key.
PendingDeletionWindowInDays (integer) --
The waiting period before the primary key in a multi-Region key is deleted. This waiting period begins when the last of its replica keys is deleted. This value is present only when the KeyState of the CMK is PendingReplicaDeletion . That indicates that the CMK is the primary key in a multi-Region key, it is scheduled for deletion, and it still has existing replica keys.
When a regional CMK or a replica key in a multi-Region key is scheduled for deletion, its deletion date is displayed in the DeletionDate field. However, when the primary key in a multi-Region key is scheduled for deletion, its waiting period doesn't begin until all of its replica keys are deleted. This value displays that waiting period. When the last replica key in the multi-Region key is deleted, the KeyState of the scheduled primary key changes from PendingReplicaDeletion to PendingDeletion and the deletion date appears in the DeletionDate field.
{'KeyState': 'Creating | Enabled | Disabled | PendingDeletion | PendingImport '
'| PendingReplicaDeletion | Unavailable | Updating',
'PendingWindowInDays': 'integer'}
Schedules the deletion of a customer master key (CMK). By default, AWS KMS applies a waiting period of 30 days, but you can specify a waiting period of 7-30 days. When this operation is successful, the key state of the CMK changes to PendingDeletion and the key can't be used in any cryptographic operations. It remains in this state for the duration of the waiting period. Before the waiting period ends, you can use CancelKeyDeletion to cancel the deletion of the CMK. After the waiting period ends, AWS KMS deletes the CMK, its key material, and all AWS KMS data associated with it, including all aliases that refer to it.
Warning
Deleting a CMK is a destructive and potentially dangerous operation. When a CMK is deleted, all data that was encrypted under the CMK is unrecoverable. (The only exception is a multi-Region replica key.) To prevent the use of a CMK without deleting it, use DisableKey.
If you schedule deletion of a CMK from a custom key store, when the waiting period expires, ScheduleKeyDeletion deletes the CMK from AWS KMS. Then AWS KMS makes a best effort to delete the key material from the associated AWS CloudHSM cluster. However, you might need to manually delete the orphaned key material from the cluster and its backups.
You can schedule the deletion of a multi-Region primary key and its replica keys at any time. However, AWS KMS will not delete a multi-Region primary key with existing replica keys. If you schedule the deletion of a primary key with replicas, its key state changes to PendingReplicaDeletion and it cannot be replicated or used in cryptographic operations. This status can continue indefinitely. When the last of its replicas keys is deleted (not just scheduled), the key state of the primary key changes to PendingDeletion and its waiting period ( PendingWindowInDays ) begins. For details, see Deleting multi-Region keys in the AWS Key Management Service Developer Guide .
For more information about scheduling a CMK for deletion, see Deleting Customer Master Keys in the AWS Key Management Service Developer Guide .
The CMK that you use for this operation must be in a compatible key state. For details, see Key state: Effect on your CMK in the AWS Key Management Service Developer Guide .
Cross-account use : No. You cannot perform this operation on a CMK in a different AWS account.
Required permissions : kms:ScheduleKeyDeletion (key policy)
Related operations
CancelKeyDeletion
DisableKey
See also: AWS API Documentation
Request Syntax
client.schedule_key_deletion(
KeyId='string',
PendingWindowInDays=123
)
string
[REQUIRED]
The unique identifier of the customer master key (CMK) to delete.
Specify the key ID or key ARN of the CMK.
For example:
Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab
Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
To get the key ID and key ARN for a CMK, use ListKeys or DescribeKey.
integer
The waiting period, specified in number of days. After the waiting period ends, AWS KMS deletes the customer master key (CMK).
If the CMK is a multi-Region primary key with replicas, the waiting period begins when the last of its replica keys is deleted. Otherwise, the waiting period begins immediately.
This value is optional. If you include a value, it must be between 7 and 30, inclusive. If you do not include a value, it defaults to 30.
dict
Response Syntax
{
'KeyId': 'string',
'DeletionDate': datetime(2015, 1, 1),
'KeyState': 'Creating'|'Enabled'|'Disabled'|'PendingDeletion'|'PendingImport'|'PendingReplicaDeletion'|'Unavailable'|'Updating',
'PendingWindowInDays': 123
}
Response Structure
(dict) --
KeyId (string) --
The Amazon Resource Name ( key ARN ) of the CMK whose deletion is scheduled.
DeletionDate (datetime) --
The date and time after which AWS KMS deletes the customer master key (CMK).
If the CMK is a multi-Region primary key with replica keys, this field does not appear. The deletion date for the primary key isn't known until its last replica key is deleted.
KeyState (string) --
The current status of the CMK.
For more information about how key state affects the use of a CMK, see Key state: Effect on your CMK in the AWS Key Management Service Developer Guide .
PendingWindowInDays (integer) --
The waiting period before the CMK is deleted.
If the CMK is a multi-Region primary key with replicas, the waiting period begins when the last of its replica keys is deleted. Otherwise, the waiting period begins immediately.