Creating an alarm that detects use of a KMS key pending deletion - 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 (PDF).

Creating an alarm that detects use of a KMS key pending deletion

You can combine the features of Amazon 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. 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 Amazon KMS API operations that return this error message, see Key states of Amazon KMS keys.

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. 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 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 Amazon 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.

Requirements for a CloudWatch alarm

Before you create a CloudWatch alarm, you must create an Amazon CloudTrail trail and configure CloudTrail to deliver CloudTrail log files to Amazon CloudWatch Logs. You also need an Amazon SNS topic for the alarm notification.

  • Create a CloudTrail trail.

    CloudTrail is automatically enabled on your Amazon Web Services account when you create the account. However, for an ongoing record of events in your account, including events for Amazon KMS, create a trail.

  • Configure CloudTrail to deliver your log files CloudWatch Logs.

    Configure delivery of your CloudTrail log files to CloudWatch Logs. This allows CloudWatch Logs to monitor the logs for Amazon KMS API requests that attempt to use a KMS key that is pending deletion.

  • Create an Amazon SNS topic.

    When your alarm triggers, it notifies you by sending an email message to an email address in an Amazon Simple Notification Service (Amazon SNS) topic.

Creating the CloudWatch alarm

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 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 using the following required values. For other fields, accept the default values and provide names as requested.

    Field Value
    Filter pattern

    { $.eventSource = kms* && $.errorMessage = "* is pending deletion."}

    Metric value 1
  2. Create a CloudWatch alarm based on the metric filter that you created in Step 1.

    Follow the instructions in Creating a CloudWatch alarm based on a log group-metric filter using the following required values. For other fields, accept the default values and provide names as requested.

    Field Value
    Metric filter

    The name of the metric filter that you created in Step 1.

    Threshold type Static
    Conditions Whenever metric-name is Greater than 1
    Datapoints to alarm 1 out of 1
    Missing data treatment Treat missing data as good (not breaching threshold)

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 and reconsider your decision to delete it.