AWS Documentation » AWS KMS » Developer Guide » How Key State Affects Use of a Customer Master Key

How Key State Affects Use of a Customer Master Key

A customer master key (CMK) is always in one of the following states: Enabled, Disabled, PendingImport, PendingDeletion, or Unavailable. The following table shows whether AWS KMS API operations that run on a CMK in each state can be expected to succeed (✓), fail (X), or succeed only under certain conditions (?). The result often differs for 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 following API operations do not appear in the table because they do not use an existing CMK.

• ConnectCustomKeyStore

• CreateCustomKeyStore

• CreateKey

• DeleteCustomKeyStore

• DescribeCustomKeyStores

• DisconnectCustomKeyStore

• GenerateRandom

• UpdateCustomKeyStore

API	Enabled	Disabled	Pending Import	Pending Deletion	Unavailable
CancelKeyDeletion	[4]	[4]	[4]		[4], [13]
CreateAlias				[3]
CreateGrant		[1]	[5]	[2] or [3]
Decrypt		[1]	[5]	[2] or [3]	[11]
DeleteAlias
DeleteImportedKeyMaterial	[9]	[9]	(No effect)	[9]	[9]
DescribeKey
DisableKey			[5]	[3]	[12]
DisableKeyRotation	[7]	[1] or [7]	[6]	[3] or [7]	[7]
EnableKey			[5]	[3]	[12]
EnableKeyRotation	[7]	[1] or [7]	[6]	[3] or [7]	[7]
Encrypt		[1]	[5]	[2] or [3]	[11]
GenerateDataKey		[1]	[5]	[2] or [3]	[11]
GenerateDataKeyWithoutPlaintext		[1]	[5]	[2] or [3]	[11]
GetKeyPolicy
GetKeyRotationStatus	[7]	[7]	[6]	[7]	[7]
GetParametersForImport	[9]	[9]		[8] or [9]	[9]
ImportKeyMaterial	[9]	[9]		[8] or [9]	[9]
ListAliases
ListGrants
ListKeyPolicies
ListKeys
ListResourceTags
ListRetirableGrants
PutKeyPolicy
ReEncrypt		[1]	[5]	[2] or [3]	[11]
RetireGrant
RevokeGrant
ScheduleKeyDeletion				[3]
TagResource				[3]
UnTagResource				[3]
UpdateAlias				[10]
UpdateKeyDescription				[3]

Table Details

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

• [2] DisabledException: <CMK ARN> is pending deletion.

• [3] KMSInvalidStateException: <CMK ARN> is pending deletion.

• [4] KMSInvalidStateException: <CMK ARN> is not pending 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.