Key state: Effect on your CMK

A customer master key (CMK) always has a key state. Operations on the CMK and its environment can change that key state, either transiently, or until another operation changes its key state.

The table in this section shows how key states affect calls to AWS KMS API operations. As a result of its key state, an operation on a CMK is expected to succeed (✓), fail (X), or succeed only under certain conditions (?). The result often differs for CMKs with imported key material.

This table includes only the API operations that use an existing CMK. Other operations, such as CreateKey and ListKeys, are omitted.

Key states and CMK types

The type of the CMK determines the key states it can have.

• Most CMKs are created in the Enabled state. Keys with imported key material are created in the PendingImport state.

• Symmetric CMKs can be in the Enabled, Disabled, PendingImport, PendingDeletion, or Unavailable states.

• Asymmetric CMKs can be in the Enabled, Disabled, or PendingDeletion key state.

• The PendingImport state applies only to CMKs with imported key material.

• The Unavailable state applies only to a CMK in a custom key store. A CMK in a custom key store is Unavailable when the custom key store is intentionally disconnected from its AWS CloudHSM cluster. You can view and manage unavailable CMKs, but you cannot use them in cryptographic operations.

• The Creating, Updating, and PendingReplicaDeletion key states apply only to multi-Region keys.

  • A multi-Region replica key is in the transient Creating key state while it is being created. This process might still be in progress when the ReplicateKey operation completes. When the replicate process completes, the replica key is in the Enabled or PendingImport state.

  • Multi-Region keys are in the transient Updating key state while the primary Region is being updated. This process might still be in progress when the UpdatePrimaryRegion operation completes. When the update process completes, the primary and replica keys resume the Enabled key state.

  • When you schedule deletion of a multi-Region primary key that has replica keys, the primary key is in the PendingReplicaDeletion state until all of its replica keys are deleted. Then its key state changes to PendingDeletion. For details, see Deleting multi-Region keys.

Key state table

The following table shows how the key state of a customer master key (CMK) affects AWS KMS operations.

The descriptions of the numbered footnotes ([n]) are at the end of this topic.

Note

You might need to scroll horizontally or vertically to see all of the data in this table.

API	Enabled	Disabled	Pending deletion Pending replica deletion	Pending import	Unavailable	Creating	Updating
CancelKeyDeletion	[4]	[4]		[4]	[4], [13]	[4]	[4]
CreateAlias			[3]
CreateGrant		[1]	[2] or [3]	[5]		[14]
Decrypt		[1]	[2] or [3]	[5]	[11]	[14]
DeleteAlias
DeleteImportedKeyMaterial	[9]	[9]	[9]	(No effect)	N/A	[14]	[15]
DescribeKey
DisableKey			[3]	[5]	[12]	[14]	[15]
DisableKeyRotation	[7]	[1] or [7]	[3] or [7]	[6]	[7]	[14]	[7]
EnableKey			[3]	[5]	[12]	[14]	[15]
EnableKeyRotation	[7]	[1] or [7]	[3] or [7]	[6]	[7]	[14]	[7]
Encrypt		[1]	[2] or [3]	[5]	[11]	[14]
GenerateDataKey		[1]	[2] or [3]	[5]	[11]	[14]
GenerateDataKeyPair		[1]	[2] or [3]	[5]	[11]	[14]
GenerateDataKeyPairWithoutPlaintext		[1]	[2] or [3]	[5]	[11]	[14]
GenerateDataKeyWithoutPlaintext		[1]	[2] or [3]	[5]	[11]	[14]
GetKeyPolicy
GetKeyRotationStatus	[7]	[7]	[7]	[6]	[7]	[7]	[7]
GetParametersForImport	[9]	[9]	[8] or [9]		[9]	[14]	[15]
GetPublicKey		[1]	[2] or [3]	N/A	N/A	[14]
ImportKeyMaterial	[9]	[9]	[8] or [9]		[9]	[14]
ListAliases
ListGrants
ListKeyPolicies
ListResourceTags
PutKeyPolicy
ReEncrypt		[1]	[2] or [3]	[5]	[11]	[14]
ReplicateKey		[1]	[2] or [3]	[5]	N/A	[14]	[15]
RetireGrant
RevokeGrant
ScheduleKeyDeletion			[3]				[15]
Sign		[1]	[2] or [3]	N/A	N/A	[14]
TagResource			[3]
UntagResource			[3]
UpdateAlias			[10]
UpdateKeyDescription			[3]
UpdatePrimaryRegion		[1]	[2] or [3]	[5]	N/A	[14]
Verify		[1]	[2] or [3]	N/A	N/A	[14]

Table Details

• [1] DisabledException: <CMK ARN> is disabled.

• [2] DisabledException: <CMK ARN> is pending deletion (or pending replica deletion).

• [3] KMSInvalidStateException: <CMK ARN> is pending deletion (or pending replica deletion).

• [4] KMSInvalidStateException: <CMK ARN> is not pending deletion (or pending replica deletion).

• [5] KMSInvalidStateException: <CMK ARN> is pending import.

• [6] UnsupportedOperationException: <CMK ARN> origin is EXTERNAL which is not valid for this operation.

• [7] If the CMK has imported key material or is in a custom key store: UnsupportedOperationException.

• [8] If the CMK has imported key material: KMSInvalidStateException

• [9] If the CMK cannot or does not have imported key material: UnsupportedOperationException.

• [10] If the source CMK is pending deletion, the command succeeds. If the destination CMK is pending deletion, the command fails with error: KMSInvalidStateException : <CMK ARN> is pending deletion.

• [11] KMSInvalidStateException: <CMK ARN> is unavailable. You cannot perform this operation on an unavailable CMK.

• [12] The operation succeeds, but the key state of the CMK does not change until it becomes available.

• [13] While a CMK in a custom key store is pending deletion, its key state remains PendingDeletion even if the CMK becomes unavailable. This allows you to cancel deletion of the CMK at any time during the waiting period.

• [14] KMSInvalidStateException: <CMK ARN> is creating. AWS KMS throws this exception while it is replicating a multi-region CMK (ReplicateKey).

• [15] KMSInvalidStateException: <CMK ARN> is updating. AWS KMS throws this exception while it is updating the primary region of a multi-region CMK (UpdatePrimaryRegion).