# Delete an AWS KMS key
Deleting an AWS KMS key 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. (The only exceptions are [multi-Region replica keys](#deleting-mrks) and asymmetric and HMAC KMS keys with imported key material.) This risk is significant for [asymmetric KMS keys used for encryption](#deleting-asymmetric-cmks) where, without warning or error, users can continue to generate ciphertexts with the public key that cannot be decrypted after the private key is deleted from AWS KMS.
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](enabling-keys.md) instead of deleting it. You can re-enable a disabled KMS key and [cancel the scheduled deletion](deleting-keys-scheduling-key-deletion.md) of a KMS key, but you cannot recover a deleted KMS key.
You can only schedule the deletion of a customer managed key. You cannot delete AWS managed keys or AWS owned keys.
Before deleting a KMS key, you might want to know how many ciphertexts were encrypted under that KMS key. AWS 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 [Determine past usage of a KMS key](deleting-keys-determining-usage.md).
AWS 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](https://aws.amazon.com/kms/pricing/) associated with maintaining unused KMS keys
+ To reduce the number of KMS keys that count against your [KMS key resource quota](resource-limits.md#kms-keys-limit)
**Note**
If you [close your AWS account](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/close-account.html), your KMS keys become inaccessible and you are no longer billed for them.
AWS KMS records an entry in your AWS CloudTrail log when you [schedule deletion](ct-schedule-key-deletion.md) of the KMS key and when the [KMS key is actually deleted](ct-delete-key.md).
## About the waiting period
Because it is destructive and potentially dangerous to delete a KMS key, AWS 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operation. Or in the AWS KMS console, on [detail page](finding-keys.md#viewing-console-details) 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**.
+ A KMS key pending deletion cannot be used in any [cryptographic operations](kms-cryptography.md#cryptographic-operations).
+ AWS KMS does not [rotate the key material](rotate-keys.md#rotate-keys-how-it-works) of KMS keys that are pending deletion.
After the waiting period ends, AWS KMS deletes the KMS key, its aliases, and all related AWS KMS metadata.
Scheduling the deletion of a KMS key might not immediately affect data keys encrypted by the KMS key. For details, see [How unusable KMS keys affect data keys](unusable-kms-keys.md).
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](deleting-keys-creating-cloudwatch-alarm.md) 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 AWS KMS deletes the KMS key.
## Special considerations
Before you schedule your keys for deletion, review the following special considerations for deleting special purpose KMS keys.
**Deleting asymmetric KMS keys**
Users [who are authorized](deleting-keys-adding-permission.md) 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](download-public-key.md) and used outside of AWS 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](kms-cryptography.md#cryptographic-operations). However, scheduling deletion has no effect on public keys outside of AWS 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 AWS KMS.
+ When the KMS key is deleted, all AWS 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 AWS KMS. Then, consider [disabling the KMS key](enabling-keys.md) instead of deleting it.
The risk posed by deleting an asymmetric KMS key is mitigated for asymmetric KMS keys with imported key material. For details, see [Deleting KMS keys with imported key material](#import-delete-key).
**Deleting multi-Region keys**
To delete a primary key, you must schedule the deletion all of its replica keys, and then wait for the replica keys to be deleted. The required waiting period for deleting a primary key begins when the last of its replica keys is deleted. If you must delete a primary key from a particular Region without deleting its replica keys, change the primary key to a replica key by [updating the primary Region](multi-region-update.md).
You can delete a replica key at any time. It doesn't depend on the key state of any other KMS key. If you mistakenly delete a replica key, you can recreate it by replicating the same primary key in the same Region. The new replica key you create will have the same [shared properties](multi-region-keys-overview.md#mrk-sync-properties) as the original replica key.
**Deleting KMS keys with imported key material**
Deleting the key material of a KMS key with imported key material is temporary and reversible. To restore the key, reimport its key material.
In contrast, deleting a KMS key is irreversible. If you [schedule key deletion](#deleting-keys-how-it-works) and the required waiting period expires, AWS KMS permanently and irreversibly deletes the KMS key, its key material, and all metadata associated with the KMS key.
However, the risk and consequence of deleting a KMS key with imported key material depends on the type ("key spec") of the KMS key.
+ Symmetric encryption keys — If you delete a symmetric encryption KMS key, all remaining ciphertexts encrypted by that key are unrecoverable. You cannot create a new symmetric encryption KMS key that can decrypt the ciphertexts of a deleted symmetric encryption KMS key, even if you have the same key material. Metadata unique to each KMS key is cryptographically bound to each symmetric ciphertext. This security feature guarantees that only the KMS key that encrypted the symmetric ciphertext can decrypt it, but it prevents you from recreating an equivalent KMS key.
+ Asymmetric and HMAC keys — If you have the original key material, you can create a new KMS key with the same cryptographic properties as an asymmetric or HMAC KMS key that was deleted. AWS KMS generates standard RSA ciphertexts and signatures, ECC signatures, and HMAC tags, which do not include any unique security features. Also, you can use an HMAC key or the private key of an asymmetric key pair outside of AWS.
A new KMS key that you create with the same asymmetric or HMAC key material will have a different key identifier. You will have to create a new key policy, recreate any aliases, and update existing IAM policies and grants to refer to the new key.
**Deleting KMS keys from an AWS CloudHSM key stores**
When you schedule deletion of a KMS key from an AWS CloudHSM key store, its [key state](key-state.md) changes to **Pending deletion**. The KMS key remains in the **Pending deletion** state throughout the waiting period, even if the KMS key becomes unavailable because you have [disconnected the custom key store](disconnect-keystore.md). This allows you to cancel the deletion of the KMS key at any time during the waiting period.
When the waiting period expires, AWS KMS deletes the KMS key from AWS KMS. Then AWS KMS makes a best effort to delete the key material from the associated AWS CloudHSM cluster. If AWS KMS cannot delete the key material, such as when the key store is disconnected from AWS KMS, you might need to manually [delete the orphaned key material](fix-keystore.md#fix-keystore-orphaned-key) from the cluster.
AWS KMS does not delete the key material from cluster backups. Even if you delete the KMS key from AWS KMS and delete its key material from your AWS CloudHSM cluster, clusters created from backups might contain the deleted key material. To permanently delete the key material, use the [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operation to identify the creation date of the KMS key. Then [delete all cluster backups](https://docs.aws.amazon.com/cloudhsm/latest/userguide/delete-restore-backup.html) that might contain the key material.
When you schedule the deletion of a KMS key from an AWS CloudHSM key store, the KMS key becomes unusable right away (subject to eventual consistency). However, resources encrypted with [data keys](data-keys.md) protected by the KMS key are not affected until the KMS key is used again, such to decrypt the data key. This issue affects AWS services, many of which use data keys to protect your resources. For details, see [How unusable KMS keys affect data keys](unusable-kms-keys.md).
**Deleting KMS keys from an external key store**
Deleting a KMS key from an external key store has no effect on the [external key](keystore-external.md#concept-external-key) that served as its key material.
When you schedule deletion of a KMS key from an external key store, its [key state](key-state.md) changes to **Pending deletion**. The KMS key remains in the **Pending deletion** state throughout the waiting period, even if the KMS key becomes unavailable because you have [disconnected the external key store](xks-connect-disconnect.md). This allows you to cancel the deletion of the KMS key at any time during the waiting period. When the waiting period expires, AWS KMS deletes the KMS key from AWS KMS.
When you schedule the deletion of a KMS key from an external key store, the KMS key becomes unusable right away (subject to eventual consistency). However, resources encrypted with [data keys](data-keys.md) protected by the KMS key are not affected until the KMS key is used again, such to decrypt the data key. This issue affects AWS services, many of which use data keys to protect your resources. For details, see [How unusable KMS keys affect data keys](unusable-kms-keys.md).
# Control access to key deletion
If you use IAM policies to allow AWS KMS permissions, IAM identities that have AWS administrator access (`"Action": "*"`) or AWS KMS full access (`"Action": "kms:*"`) are already allowed to schedule and cancel key the deletion of KMS keys. To allow key administrators to schedule and cancel key deletion in the key policy, use the AWS KMS console or the AWS KMS API.
Typically, only key administrators have permission to schedule or cancel key deletion. However, you can give these permissions to other IAM identities by adding the `kms:ScheduleKeyDeletion` and `kms:CancelKeyDeletion` permission to the key policy or an IAM policy. You can also use the [`kms:ScheduleKeyDeletionPendingWindowInDays`](conditions-kms.md#conditions-kms-schedule-key-deletion-pending-window-in-days) condition key to further constrain the values that principals can specify in the `PendingWindowInDays` parameter of a [ScheduleKeyDeletion](https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html) request.
## Allow key administrators to schedule and cancel key deletion
### Using the AWS KMS console
To give key administrators permission to schedule and cancel key deletion.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Choose the alias or key ID of the KMS key whose permissions you want to change.
1. Choose the **key policy** tab.
1. The next step differs for the *default view* and *policy view* of your key policy. Default view is available only if you are using the default console key policy. Otherwise, only policy view is available.
When default view is available, a **Switch to policy view** or **Switch to default view** button appears on the **Key policy** tab.
+ In default view:
1. Under **Key deletion**, choose **Allow key administrators to delete this key**.
+ In policy view:
1. Choose **Edit**.
1. In the policy statement for key administrators, add the `kms:ScheduleKeyDeletion` and `kms:CancelKeyDeletion` permissions to the `Action` element.
```
{
"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": "*"
}
```
1. Choose **Save changes**.
### Using the AWS KMS API
You can use the AWS Command Line Interface to add permissions for scheduling and canceling key deletion.
**To add permission to schedule and cancel key deletion**
1. Use the [https://docs.aws.amazon.com/cli/latest/reference/kms/get-key-policy.html](https://docs.aws.amazon.com/cli/latest/reference/kms/get-key-policy.html) command to retrieve the existing key policy, and then save the policy document to a file.
1. Open the policy document in your preferred text editor. In the policy statement for key administrators, add the `kms:ScheduleKeyDeletion` and `kms:CancelKeyDeletion` permissions. 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": "*"
}
```
1. Use the [https://docs.aws.amazon.com/cli/latest/reference/kms/put-key-policy.html](https://docs.aws.amazon.com/cli/latest/reference/kms/put-key-policy.html) command to apply the key policy to the KMS key.
# Schedule key deletion
The following procedures describe how to schedule key deletion and cancel key deletion of AWS KMS keys (KMS keys) in AWS KMS using the AWS Management Console and the AWS KMS API.
**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](enabling-keys.md) instead of deleting it.
Before you can delete a KMS key, you must have permission to do so. For information about giving these permissions to key administrators, see [Control access to key deletion](deleting-keys-adding-permission.md). You can also use the [`kms:ScheduleKeyDeletionPendingWindowInDays`](conditions-kms.md#conditions-kms-schedule-key-deletion-pending-window-in-days) condition key to further constrain the waiting period, such as enforcing a minimum waiting period.
AWS KMS records an entry in your AWS CloudTrail log when you [schedule deletion](ct-schedule-key-deletion.md) of the KMS key and when the [KMS key is actually deleted](ct-delete-key.md).
## Using the AWS KMS console
In the AWS 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 AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
You cannot schedule the deletion of [AWS managed keys](concepts.md#aws-managed-key) or [AWS owned keys](concepts.md#aws-owned-key).
1. Choose the checkbox next to the KMS key that you want to delete.
1. Choose **Key actions**, **Schedule key deletion**.
1. 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**.
1. For **Waiting period (in days)**, enter a number of days between 7 and 30.
1. Review the KMS keys that you are deleting.
1. Choose the check box next to **Confirm you want to schedule this key for deletion in ** days.**.
1. Choose **Schedule deletion**.
The KMS key status changes to **Pending deletion**.
## Using the AWS KMS API
Use the [https://docs.aws.amazon.com/cli/latest/reference/kms/schedule-key-deletion.html](https://docs.aws.amazon.com/cli/latest/reference/kms/schedule-key-deletion.html) command to schedule key deletion of a [customer managed key](concepts.md#customer-mgn-key), as shown in the following example.
You cannot schedule the deletion of an AWS managed key or AWS owned key.
```
$ aws kms schedule-key-deletion --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --pending-window-in-days 10
```
When used successfully, the AWS 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
}
```
# Cancel key deletion
After you [schedule a KMS key for deletion](deleting-keys-scheduling-key-deletion.md), you can cancel the key deletion while it is still in the [pending deletion](key-state.md) state. You can cancel key deletion in the AWS KMS console or by using the [CancelKeyDeletion](https://docs.aws.amazon.com/kms/latest/APIReference/API_CancelKeyDeletion.html) operation. After you cancel the pending deletion of a KMS key, the key state of the KMS key is `Disabled`. For more information on enabling the KMS key, see [Enable and disable keys](enabling-keys.md).
## Using the AWS KMS console
**To cancel key deletion**
1. Open the AWS KMS console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Choose the check box next to the KMS key that you want to recover.
1. 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](enabling-keys.md).
## Using the AWS KMS API
Use the [https://docs.aws.amazon.com/cli/latest/reference/kms/cancel-key-deletion.html](https://docs.aws.amazon.com/cli/latest/reference/kms/cancel-key-deletion.html) command to cancel key deletion from the AWS CLI as shown in the following example.
```
$ aws kms cancel-key-deletion --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
When used successfully, the AWS 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](enabling-keys.md).
# Create an alarm that detects use of a KMS key pending deletion
You can combine the features of AWS CloudTrail, Amazon CloudWatch Logs, and Amazon Simple Notification Service (Amazon SNS) to create an Amazon CloudWatch alarm that notifies you when someone in your account tries to use a KMS key that is pending deletion. If you receive this notification, you might want to cancel deletion of the KMS key and reconsider your decision to delete it.
The following procedures create an alarm that notifies you whenever the "`Key ARN is pending deletion`" error message is written to your CloudTrail log files. This error message indicates that a person or application tried to use the KMS key in a [cryptographic operation](kms-cryptography.md#cryptographic-operations). Because the notification is linked to the error message, it is not triggered when you use API operations that are permitted on KMS keys that are pending deletion, such as `ListKeys`, `CancelKeyDeletion`, and `PutKeyPolicy`. To see a list of the AWS KMS API operations that return this error message, see [Key states of AWS KMS keys](key-state.md).
The notification email that you receive does not list the KMS key or the cryptographic operation. You can find that information in [your CloudTrail log](logging-using-cloudtrail.md). Instead, the email reports that the alarm state changed from **OK** to **Alarm**. For more information about CloudWatch alarms and state changes, see [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the *Amazon CloudWatch User Guide*.
**Warning**
This Amazon CloudWatch alarm cannot detect use of the public key of an asymmetric KMS key outside of AWS KMS. For details about the special risks of deleting asymmetric KMS keys used for public key cryptography, including creating ciphertexts that cannot be decrypted, see [Deleting asymmetric KMS keys](deleting-keys.md#deleting-asymmetric-cmks).
In this procedure, you create a CloudWatch log group metric filter that finds instances of the pending deletion exception. Then, you create a CloudWatch alarm based on the log group metric. For information about log group metric filters, see [Creating metrics from log events using filters](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/MonitoringLogData.html) in the Amazon CloudWatch Logs User Guide.
1. Create a CloudWatch metric filter that parses CloudTrail logs.
Follow the instructions in [Create a metric filter for a log group](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CreateMetricFilterProcedure.html) using the following required values. For other fields, accept the default values and provide names as requested.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys-creating-cloudwatch-alarm.html)
1. Create a CloudWatch alarm based on the metric filter that you created in Step 1.
Follow the instructions in [Create a CloudWatch alarm based on a log group-metric filter](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Alarm-On-Logs.html) using the following required values. For other fields, accept the default values and provide names as requested.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys-creating-cloudwatch-alarm.html)
After you complete this procedure, you will receive a notification each time your new CloudWatch alarm enters the `ALARM` state. If you receive a notification for this alarm, it might mean that a KMS key that is scheduled for deletion is still needed to encrypt or decrypt data. In that case, [cancel deletion of the KMS key](deleting-keys-scheduling-key-deletion.md) and reconsider your decision to delete it.
# Determine past usage of a KMS key
Before deleting a KMS key, you might want to know how many ciphertexts were encrypted under that key. AWS KMS does not store this information, and does not store any of the ciphertexts. Knowing how a KMS key was used in the past might help you decide whether or not you will need it in the future. This topic suggest several strategies that can help you determine the past usage of a KMS key.
**Warning**
These strategies for determining past and actual usage are effective only for AWS users and AWS KMS operations. They cannot detect use of the public key of an asymmetric KMS key outside of AWS KMS. For details about the special risks of deleting asymmetric KMS keys used for public key cryptography, including creating ciphertexts that cannot be decrypted, see [Deleting asymmetric KMS keys](deleting-keys.md#deleting-asymmetric-cmks).
**Topics**
+ [
## Examine KMS key permissions to determine the scope of potential usage
](#deleting-keys-usage-key-permissions)
+ [
## Examine AWS CloudTrail logs to determine actual usage
](#deleting-keys-usage-cloudtrail)
## Examine KMS key permissions to determine the scope of potential usage
Determining who or what currently has access to a KMS key might help you determine how widely the KMS key was used and whether it is still needed. To learn how to determine who or what currently has access to a KMS key, go to [Determining access to AWS KMS keys](determining-access.md).
## Examine AWS CloudTrail logs to determine actual usage
You might be able to use a KMS key usage history to help you determine whether you have ciphertexts encrypted under a particular KMS key.
All AWS KMS API activity is recorded in AWS CloudTrail log files. If you have [created a CloudTrail trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) in the region where your KMS key is located, you can examine your CloudTrail log files to view a history of all AWS KMS API activity for a particular KMS key. If you don't have a trail, you can still view recent events in your [CloudTrail event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html). For details about how AWS KMS uses CloudTrail, see [Logging AWS KMS API calls with AWS CloudTrail](logging-using-cloudtrail.md).
The following examples show CloudTrail log entries that are generated when a KMS key is used to protect an object stored in Amazon Simple Storage Service (Amazon S3). In this example, the object is uploaded to Amazon S3 using [Protecting data using server-side encryption with KMS keys (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html). When you upload an object to Amazon S3 with SSE-KMS, you specify the KMS key to use for protecting the object. Amazon S3 uses the AWS KMS [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) operation to request a unique data key for the object, and this request event is logged in CloudTrail with an entry similar to the following:
```
{
"eventVersion": "1.02",
"userIdentity": {
"type": "AssumedRole",
"principalId": "AROACKCEVSQ6C2EXAMPLE:example-user",
"arn": "arn:aws:sts::111122223333:assumed-role/Admins/example-user",
"accountId": "111122223333",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"sessionContext": {
"attributes": {
"mfaAuthenticated": "false",
"creationDate": "2015-09-10T23:12:48Z"
},
"sessionIssuer": {
"type": "Role",
"principalId": "AROACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws:iam::111122223333:role/Admins",
"accountId": "111122223333",
"userName": "Admins"
}
},
"invokedBy": "internal.amazonaws.com"
},
"eventTime": "2015-09-10T23:58:18Z",
"eventSource": "kms.amazonaws.com",
"eventName": "GenerateDataKey",
"awsRegion": "us-west-2",
"sourceIPAddress": "internal.amazonaws.com",
"userAgent": "internal.amazonaws.com",
"requestParameters": {
"encryptionContext": {"aws:s3:arn": "arn:aws:s3:::example_bucket/example_object"},
"keySpec": "AES_256",
"keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
},
"responseElements": null,
"requestID": "cea04450-5817-11e5-85aa-97ce46071236",
"eventID": "80721262-21a5-49b9-8b63-28740e7ce9c9",
"readOnly": true,
"resources": [{
"ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"accountId": "111122223333"
}],
"eventType": "AwsApiCall",
"recipientAccountId": "111122223333"
}
```
When you later download this object from Amazon S3, Amazon S3 sends a `Decrypt` request to AWS KMS to decrypt the object's data key using the specified KMS key. When you do this, your CloudTrail log files include an entry similar to the following:
```
{
"eventVersion": "1.02",
"userIdentity": {
"type": "AssumedRole",
"principalId": "AROACKCEVSQ6C2EXAMPLE:example-user",
"arn": "arn:aws:sts::111122223333:assumed-role/Admins/example-user",
"accountId": "111122223333",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"sessionContext": {
"attributes": {
"mfaAuthenticated": "false",
"creationDate": "2015-09-10T23:12:48Z"
},
"sessionIssuer": {
"type": "Role",
"principalId": "AROACKCEVSQ6C2EXAMPLE",
"arn": "arn:aws:iam::111122223333:role/Admins",
"accountId": "111122223333",
"userName": "Admins"
}
},
"invokedBy": "internal.amazonaws.com"
},
"eventTime": "2015-09-10T23:58:39Z",
"eventSource": "kms.amazonaws.com",
"eventName": "Decrypt",
"awsRegion": "us-west-2",
"sourceIPAddress": "internal.amazonaws.com",
"userAgent": "internal.amazonaws.com",
"requestParameters": {
"encryptionContext": {"aws:s3:arn": "arn:aws:s3:::example_bucket/example_object"}},
"responseElements": null,
"requestID": "db750745-5817-11e5-93a6-5b87e27d91a0",
"eventID": "ae551b19-8a09-4cfc-a249-205ddba330e3",
"readOnly": true,
"resources": [{
"ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"accountId": "111122223333"
}],
"eventType": "AwsApiCall",
"recipientAccountId": "111122223333"
}
```
All AWS KMS API activity is logged by CloudTrail. By evaluating these log entries, you might be able to determine the past usage of a particular KMS key, and this might help you determine whether or not you want to delete it.
To see more examples of how AWS KMS API activity appears in your CloudTrail log files, go to [Logging AWS KMS API calls with AWS CloudTrail](logging-using-cloudtrail.md). For more information about CloudTrail go to the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
# Delete imported key material
You can delete the imported key material from a KMS key at any time. Also, when imported key material with an expiration date expires, AWS KMS deletes the key material. In either case, when the key material is deleted, the [key state](key-state.md) of the KMS key changes to *Pending import*, and the KMS key can't be used in any cryptographic operations.
Symmetric encryption keys can have multiple key materials associated with them. For these keys, KMS assigns a unique identifier to each key material. You can use the [ListKeyRotations](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeyRotations.html) API to view these key material identifiers and corresponding key material state (see [RotationsListEntry](https://docs.aws.amazon.com/kms/latest/APIReference/API_RotationsListEntry.html)). A key material state of `PENDING_ROTATION` or `PENDING_MULTI_REGION_IMPORT_AND_ROTATION` indicates the key material is not permanently associated with the KMS key. Deletion or expiration of any permanently associated key material changes the key state to *Pending import*. You can delete a specific key material by specifying its identifier using the `key-material-id` parameter in the [DeleteImportedKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteImportedKeyMaterial.html) API.
**Considerations for multi-Region keys**
+ When you delete the key material of a primary Region key that is in `PENDING_ROTATION` or `PENDING_MULTI_REGION_IMPORT_AND_ROTATION` state, you'll also be deleting the key materials for the replica Region keys.
+ If you delete the key material in a primary or replica Region key, only that specific key is affected and other related multi-region keys remain unchanged. Any primary or replica Region keys that have all their permanently associated key materials continue to be usable in cryptographic operations.
**Warning**
The `key-material-id` parameter is optional and if you do not specify it, AWS KMS will delete the current key material.
Along with disabling the KMS key and withdrawing permissions, deleting key material can be used as a strategy to quickly, but temporarily, halt the use of the KMS key. In contrast, scheduling the deletion of a KMS key with imported key material also quickly halts the use of the KMS key. However, if the deletion is not canceled during the waiting period, the KMS key, associated key materials, and all key metadata are permanently deleted. For details, see [Deleting KMS keys with imported key material](deleting-keys.md#import-delete-key).
To delete key material, you can use the AWS KMS console or the [DeleteImportedKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteImportedKeyMaterial.html) API operation. AWS KMS records an entry in your AWS CloudTrail log when you [delete imported key material](ct-deleteimportedkeymaterial.md) and when [AWS KMS deletes expired key material](ct-deleteexpiredkeymaterial.md).
**How deleting key material affects AWS services**
When you delete any key material, the KMS key becomes unusable right away (subject to eventual consistency). However, resources encrypted with [data keys](data-keys.md) protected by the KMS key are not affected until the KMS key is used again, such as to decrypt the data key. This issue affects AWS services, many of which use data keys to protect your resources. For details, see [How unusable KMS keys affect data keys](unusable-kms-keys.md).
## Using the AWS KMS console
You can use the AWS KMS console to delete key material.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Do one of the following:
+ Select the check box for a KMS key with imported key material. Choose **Key actions**, **Delete key material**. For symmetric encryption keys that have multiple key materials associated with them, this will delete the current key material.
+ For symmetric encryption KMS keys with imported key material, choose the alias or key ID of a KMS key. Choose the **Key material and rotations** tab. The key material table will list all of the key materials associated with the key. Choose **Delete key material** from the **Actions** menu in the row corresponding to the key material you want to delete.
1. Confirm that you want to delete the key material and then choose **Delete key material**. The KMS key's status, which corresponds to its [key state](key-state.md), changes to **Pending import**. If the deleted key material was in `PENDING_ROTATION` state, there is no change to the KMS key's status.
## Using the AWS KMS API
To use the [AWS KMS API](https://docs.aws.amazon.com/kms/latest/APIReference/) to delete key material, send a [DeleteImportedKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteImportedKeyMaterial.html) request. The following example shows how to do this with the [AWS CLI](https://aws.amazon.com/cli/).
Replace `1234abcd-12ab-34cd-56ef-1234567890ab` with the key ID of the KMS key whose key material you want to delete. You can use the KMS key's key ID or ARN but you cannot use an alias for this operation. The following command deletes the current key material which may be the only key material associated with the key.
```
$ aws kms delete-imported-key-material --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
```
To delete a specific key material, specify the key material identified using the `key-material-id` parameter. Replace `123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0` with the identifier of the key material you want to delete.
```
$ aws kms delete-imported-key-material --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-material-id 123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0
```