Logging Amazon KMS API calls with Amazon CloudTrail - 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.

Logging Amazon KMS API calls with Amazon CloudTrail

Amazon KMS is integrated with Amazon CloudTrail, a service that records all calls to Amazon KMS by users, roles, and other Amazon services. CloudTrail captures all API calls to Amazon KMS as events, including calls from the Amazon KMS console, Amazon KMS APIs, Amazon CloudFormation templates, the Amazon Command Line Interface (Amazon CLI), and Amazon Tools for PowerShell.

CloudTrail logs all Amazon KMS operations, including read-only operations, such as ListAliases and GetKeyRotationStatus, operations that manage KMS keys, such as CreateKey and PutKeyPolicy, and cryptographic operations, such as GenerateDataKey and Decrypt. It also logs internal operations that Amazon KMS calls for you, such as DeleteExpiredKeyMaterial, DeleteKey, SynchronizeMultiRegionKey, and RotateKey.

CloudTrail logs successful operations and attempted calls that failed, such as when the caller is denied access to a resource. Cross-account operations on KMS keys are logged in both the caller account and the KMS key owner account. However, cross-account Amazon KMS requests that are rejected because access is denied are logged only in the caller's account.

For security reasons, some fields are omitted from Amazon KMS log entries, such as the Plaintext parameter of an Encrypt request, and the response to GetKeyPolicy or any cryptographic operation. To make it easier to search for CloudTrail log entries for particular KMS keys, Amazon KMS adds the key ARN of the affected KMS key to the responseElements field in the log entries for some Amazon KMS key management operations, even when the API operation doesn't return the key ARN.

Although by default, all Amazon KMS actions are logged as CloudTrail events, you can exclude Amazon KMS actions from a CloudTrail trail. For details, see Excluding Amazon KMS events from a trail.

Logging events in CloudTrail

CloudTrail is enabled on your Amazon Web Services account when you create the account. When activity occurs in Amazon KMS, that activity is recorded in a CloudTrail event along with other Amazon service events in Event history. You can view, search, and download recent events in your Amazon Web Services account. For more information, see Viewing Events with CloudTrail Event History.

For an ongoing record of events in your Amazon Web Services account, including events for Amazon KMS, create a trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all Amazon Web Services Regions. The trail logs events from all Regions in the Amazon partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other Amazon Web Services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see:

To learn more about CloudTrail, see the Amazon CloudTrail User Guide. To learn about other ways to monitor the use of your KMS keys, see Monitoring Amazon KMS keys.

Every event or log entry contains information about who generated the request. The identity information helps you determine the following:

  • If the request was made with root or IAM user credentials.

  • If the request was made with temporary security credentials for a role or federated user.

  • If the request was made by another Amazon service.

For more information, see the CloudTrail userIdentity Element.

Searching events in CloudTrail

To search CloudTrail log entries, use the CloudTrail console or the CloudTrail LookupEvents operation. CloudTrail supports numerous attribute values for filtering your search, including event name, user name, and event source.

To help you search for Amazon KMS log entries in CloudTrail, Amazon KMS populates the following CloudTrail log entry fields.

Note

Beginning in December 2022, Amazon KMS populates the Resource type and Resource name attributes in all management operations that change a particular KMS key. These attribute values might be null in older CloudTrail entries for the following operations: CreateAlias, CreateGrant, DeleteAlias, DeleteImportedKeyMaterial, ImportKeyMaterial, ReplicateKey, RetireGrant, RevokeGrant, UpdateAlias, and UpdatePrimaryRegion.

Attribute Value Log entries
Event source (EventSource) kms.amazonaws.com All operations.
Resource type (ResourceType) AWS::KMS::Key Management operations that change a particular KMS key, such as CreateKey and EnableKey, but not ListKeys.
Resource name (ResourceName) Key ARN (or key ID and key ARN) Management operations that change a particular KMS key, such as CreateKey and EnableKey, but not ListKeys.

To help you find log entries for management operations on particular KMS keys, Amazon KMS records the key ARN of the affected KMS key in the responseElements.keyId element of the log entry, even when the Amazon KMS API operation doesn't return the key ARN.

For example, a successful call to the DisableKey operation doesn't return any values in the response, but instead of a null value, the responseElements.keyId value in the DisableKey log entry includes the key ARN of the disabled KMS key.

This feature was added in December 2022 and affects the following CloudTrail log entries: CreateAlias, CreateGrant, DeleteAlias, DeleteKey, DisableKey, EnableKey, EnableKeyRotation, ImportKeyMaterial, RotateKey, SynchronizeMultiRegionKey, TagResource, UntagResource, UpdateAlias, and UpdatePrimaryRegion.

Excluding Amazon KMS events from a trail

To provide a record of the use and management of their Amazon KMS resources, most Amazon KMS users rely on the events in a CloudTrail trail. The trail can be an valuable source of data for auditing critical events, such as creating, disabling, and deleting Amazon KMS keys, changing key policy, and the use of your KMS keys by Amazon services on your behalf. In some cases, the metadata in a CloudTrail log entry, such as the encryption context in an encryption operation, can help you to avoid or resolve errors.

However, because Amazon KMS can generate a large number of events, Amazon CloudTrail lets you exclude Amazon KMS events from a trail. This per-trail setting excludes all Amazon KMS events; you cannot exclude particular Amazon KMS events.

Warning

Excluding Amazon KMS events from a CloudTrail Log can obscure actions that use your KMS keys. Be cautious when giving principals the cloudtrail:PutEventSelectors permission that is required to perform this operation.

To exclude Amazon KMS events from a trail:

You can disable this exclusion at any time by changing the console setting or the event selectors for a trail. The trail will then start recording Amazon KMS events. However, it cannot recover Amazon KMS events that occurred while the exclusion was effective.

When you exclude Amazon KMS events by using the console or API, the resulting CloudTrail PutEventSelectors API operation is also logged in your CloudTrail Logs. If Amazon KMS events don't appear in your CloudTrail Logs, look for a PutEventSelectors event with the ExcludeManagementEventSources attribute set to kms.amazonaws.com.