Deleting Amazon KMS keys - Amazon Key Management Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Deleting Amazon KMS keys

Deleting an Amazon KMS key (KMS key) from Amazon Key Management Service (Amazon KMS) is destructive and potentially dangerous. It deletes the key material and all metadata associated with the KMS key and is irreversible. After a KMS key is deleted, you can no longer decrypt the data that was encrypted under that KMS key, which means that data becomes unrecoverable. You should delete a KMS key only when you are sure that you don't need to use it anymore. If you are not sure, consider disabling the KMS key instead of deleting it. You can re-enable a disabled KMS key if you need to use it again later, but you cannot recover a deleted KMS key.

Before deleting a KMS key, you might want to know how many ciphertexts were encrypted under that KMS key. Amazon KMS does not store this information and does not store any of the ciphertexts. To get this information, you must determine past usage of a KMS key. For help, go to Determining past usage of a KMS key.

Amazon KMS never deletes your KMS keys unless you explicitly schedule them for deletion and the mandatory waiting period expires.

However, you might choose to delete a KMS key for one or more of the following reasons:

  • To complete the key lifecycle for KMS keys that you no longer need

  • To avoid the management overhead and costs associated with maintaining unused KMS keys

  • To reduce the number of KMS keys that count against your KMS key resource quota

Note

If you close or delete your Amazon Web Services account, your KMS keys become inaccessible and you are no longer billed for them. You do not need to schedule deletion of your KMS keys separate from closing the account.

Amazon KMS records an entry in your Amazon CloudTrail log when you schedule deletion of the KMS key and when the KMS key is actually deleted.

For information about deleting multi-Region primary and replica keys, see Deleting multi-Region keys.

About the waiting period

Because it is destructive and potentially dangerous to delete a KMS key, Amazon KMS requires you to set a waiting period of 7 – 30 days. The default waiting period is 30 days.

However, the actual waiting period might be up to 24 hours longer than the one you scheduled. To get the actual date and time when the KMS key will be deleted, use the DescribeKey operation. Or in the Amazon KMS console, on detail page for the KMS key, in the General configuration section, see the Scheduled deletion date. Be sure to note the time zone.

During the waiting period, the KMS key status and key state is Pending deletion.

After the waiting period ends, Amazon KMS deletes the KMS key, its aliases, and all related Amazon KMS metadata.

Use the waiting period to ensure that you don't need the KMS key now or in the future. You can configure an Amazon CloudWatch alarm to warn you if a person or application attempts to use the KMS key during the waiting period. To recover the KMS key, you can cancel key deletion before the waiting period ends. After the waiting period ends you cannot cancel key deletion, and Amazon KMS deletes the KMS key.

Deleting asymmetric KMS keys

Users who are authorized can delete symmetric or asymmetric KMS keys. The procedure to schedule the deletion of these KMS keys is the same for both types of keys. However, because the public key of an asymmetric KMS key can be downloaded and used outside of Amazon KMS, the operation poses significant additional risks, especially for asymmetric KMS keys used for encryption (the key usage is ENCRYPT_DECRYPT).

  • When you schedule the deletion of a KMS key, the key state of KMS key changes to Pending deletion, and the KMS key cannot be used in cryptographic operations. However, scheduling deletion has no effect on public keys outside of Amazon KMS. Users who have the public key can continue to use them to encrypt messages. They do not receive any notification that the key state is changed. Unless the deletion is canceled, ciphertext created with the public key cannot be decrypted.

  • Alarms, logs, and other strategies that detect attempted use of KMS key that is pending deletion cannot detect use of the public key outside of Amazon KMS.

  • When the KMS key is deleted, all Amazon KMS actions involving that KMS key fail. However, users who have the public key can continue to use them to encrypt messages. These ciphertexts cannot be decrypted.

If you must delete an asymmetric KMS key with a key usage of ENCRYPT_DECRYPT, use your CloudTrail Log entries to determine whether the public key has been downloaded and shared. If it has, verify that the public key is not being used outside of Amazon KMS. Then, consider disabling the KMS key instead of deleting it.

Deleting multi-Region keys

Users who are authorized can schedule the deletion of multi-Region primary and replica keys. However, Amazon KMS will not delete a multi-Region primary key that has replica keys. Also, as long as its primary key exists, you can recreate a deleted multi-Region replica key. For details, see Deleting multi-Region keys.

Scheduling and canceling key deletion

The following procedures describe how to schedule key deletion and cancel key deletion of single-Region Amazon KMS keys (KMS keys) in Amazon KMS using the Amazon Web Services Management Console, the Amazon CLI, and the Amazon SDK for Java.

For information about scheduling the deletion of multi-Region keys, see Deleting multi-Region keys.

Warning

Deleting a KMS key is destructive and potentially dangerous. You should proceed only when you are sure that you don't need to use the KMS key anymore and won't need to use it in the future. If you are not sure, you should disable the KMS key instead of deleting it.

Before you can delete a KMS key, you must have permission to do so. If you rely on the key policy alone to specify Amazon KMS permissions, you might need to add additional permissions before you can delete the KMS key. For information about adding these permissions, go to Adding permission to schedule and cancel key deletion.

Amazon KMS records an entry in your Amazon CloudTrail log when you schedule deletion of the KMS key and when the KMS key is actually deleted.

Scheduling and canceling key deletion (console)

In the Amazon Web Services Management Console, you can schedule and cancel the deletion of multiple KMS keys at one time.

To schedule key deletion

  1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys.

  4. Select the check box next to the KMS key that you want to delete.

  5. Choose Key actions, Schedule key deletion.

  6. Read and consider the warning, and the information about canceling the deletion during the waiting period. If you decide to cancel the deletion, at the bottom of the page, choose Cancel.

  7. For Waiting period (in days), enter a number of days between 7 and 30.

  8. Review the KMS keys that you are deleting.

  9. Select the check box next to Confirm you want to schedule this key for deletion in <number of days> days..

  10. Choose Schedule deletion.

The KMS key status changes to Pending deletion.

To cancel key deletion

  1. Open the Amazon KMS console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys.

  4. Select the check box next to the KMS key that you want to recover.

  5. Choose Key actions, Cancel key deletion.

The KMS key status changes from Pending deletion to Disabled. To use the KMS key, you must enable it.

Scheduling and canceling key deletion (Amazon CLI)

Use the aws kms schedule-key-deletion command to schedule key deletion from the Amazon CLI as shown in the following example.

$ aws kms schedule-key-deletion --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --pending-window-in-days 10

When used successfully, the Amazon CLI returns output like the output shown in the following example:

{ "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "DeletionDate": 1598304792.0, "KeyState": "PendingDeletion", "PendingWindowInDays": 10 }

Use the aws kms cancel-key-deletion command to cancel key deletion from the Amazon CLI as shown in the following example.

$ aws kms cancel-key-deletion --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

When used successfully, the Amazon CLI returns output like the output shown in the following example:

{ "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" }

The status of the KMS key changes from Pending Deletion to Disabled. To use the KMS key, you must enable it.

Scheduling and canceling key deletion (Amazon SDK for Java)

The following example demonstrates how to schedule a KMS key for deletion with the Amazon SDK for Java. This example requires that you previously instantiated an AWSKMSClient as kms.

String KeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; int PendingWindowInDays = 10; ScheduleKeyDeletionRequest scheduleKeyDeletionRequest = new ScheduleKeyDeletionRequest().withKeyId(KeyId).withPendingWindowInDays(PendingWindowInDays); kms.scheduleKeyDeletion(scheduleKeyDeletionRequest);

The following example demonstrates how to cancel key deletion with the Amazon SDK for Java. This example requires that you previously instantiated an AWSKMSClient as kms.

String KeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; CancelKeyDeletionRequest cancelKeyDeletionRequest = new CancelKeyDeletionRequest().withKeyId(KeyId); kms.cancelKeyDeletion(cancelKeyDeletionRequest);

The status of the KMS key changes from Pending Deletion to Disabled. To use the KMS key, you must enable it.

Adding permission to schedule and cancel key deletion

If you use IAM policies to allow Amazon KMS permissions, all IAM users and roles that have Amazon administrator access ("Action": "*") or Amazon KMS full access ("Action": "kms:*") are already allowed to schedule and cancel key the deletion of KMS keys. If you rely on the key policy alone to allow Amazon KMS permissions, you might need to add additional permissions to allow your IAM users and roles to delete KMS keys. You can add those permissions in the Amazon KMS console or by using the Amazon KMS API.

Adding permission to schedule and cancel key deletion (console)

You can use the Amazon Web Services Management Console to add permissions for scheduling and canceling key deletion.

  1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys.

  4. Choose the alias or key ID of the KMS key whose permissions you want to change.

  5. Choose the Key policy tab. Under Key deletion, select Allow key administrators to delete this key and then choose Save changes.

    Note

    If you do not see the Allow key administrators to delete this key option, this usually means that you have changed this key policy using the Amazon KMS API. In this case, you must update the key policy document manually. Add the kms:ScheduleKeyDeletion and kms:CancelKeyDeletion permissions to the key administrators statement ("Sid": "Allow access for Key Administrators") in the key policy, and then choose Save changes.

Adding permission to schedule and cancel key deletion (Amazon CLI)

You can use the Amazon Command Line Interface to add permissions for scheduling and canceling key deletion.

To add permission to schedule and cancel key deletion

  1. Use the aws kms get-key-policy command to retrieve the existing key policy, and then save the policy document to a file.

  2. Open the policy document in your preferred text editor, add the kms:ScheduleKeyDeletion and kms:CancelKeyDeletion permissions to the policy statement that gives permissions to the key administrators (for example, the policy statement with "Sid": "Allow access for Key Administrators"). Then save the file. The following example shows a policy statement with these two permissions:

    { "Sid": "Allow access for Key Administrators", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:user/KMSKeyAdmin"}, "Action": [ "kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*", "kms:Update*", "kms:Revoke*", "kms:Disable*", "kms:Get*", "kms:Delete*", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion" ], "Resource": "*" }
  3. Use the aws kms put-key-policy command to apply the key policy to the KMS key.