How AWS CloudTrail uses AWS KMS
You can use AWS CloudTrail to record AWS API calls and other activity for your AWS account and to save the recorded information to log files in an Amazon Simple Storage Service (Amazon S3) bucket that you choose. By default, the log files that CloudTrail puts in your S3 bucket are encrypted using server-side encryption with Amazon S3–managed encryption keys (SSE-S3). But you can choose instead to use server-side encryption with a KMS key (SSE-KMS). To learn how to encrypt your CloudTrail log files with AWS KMS, see Encrypting CloudTrail Log Files with AWS KMS keys (SSE-KMS) in the AWS CloudTrail User Guide.
Important
AWS CloudTrail and Amazon S3 support only symmetric AWS KMS keys. You cannot use an asymmetric KMS key to encrypt your CloudTrail Logs. For help determining whether a KMS key is symmetric or asymmetric, see Identifying asymmetric KMS keys.
You do not pay a key usage charge when CloudTrail reads or writes log files encrypted with an
SSE-KMS key. However, you pay a key usage charge when you access CloudTrail log files encrypted with
an SSE-KMS key. For information about AWS KMS pricing, see AWS Key Management Service Pricing
Understanding when your KMS key is used
Encrypting CloudTrail log files with AWS KMS builds on the Amazon S3 feature called server-side encryption with an AWS KMS key (SSE-KMS). To learn more about SSE-KMS, see How Amazon Simple Storage Service (Amazon S3) uses AWS KMS in this guide or Protecting data using server-side encryption with KMS keys (SSE-KMS) in the Amazon Simple Storage Service User Guide.
When you configure AWS CloudTrail to use SSE-KMS to encrypt your log files, CloudTrail and Amazon S3 use your AWS KMS keys when you perform certain actions with those services. The following sections explain when and how those services can use your KMS key, and provide additional information that you can use to validate this explanation.
Actions that cause CloudTrail and Amazon S3 to use your KMS key
You configure CloudTrail to encrypt log files with your AWS KMS key
When you update your CloudTrail
configuration to use your KMS key, CloudTrail sends a GenerateDataKey
request
to AWS KMS to verify that the KMS key exists and that CloudTrail has permission to use it for
encryption. CloudTrail does not use the resulting data key.
The GenerateDataKey
request includes the following information for the
encryption context:
-
The Amazon Resource Name (ARN) of the CloudTrail trail
-
The ARN of the S3 bucket and path where the CloudTrail log files are delivered
The GenerateDataKey
request results in an entry in your CloudTrail logs similar
to the following example. When you see a log entry like this one, you can determine that
CloudTrail (
) called the AWS KMS (
)
GenerateDataKey
operation (
) for a specific trail (
). AWS KMS created the data key under a specific KMS key (
).
Note
You might need to scroll to the right to see some of the callouts in the following example log entry.
{ "eventVersion": "1.02", "userIdentity": { "type": "IAMUser", "principalId": "AIDACKCEVSQ6C2EXAMPLE", "arn": "arn:aws:iam::086441151436:user/AWSCloudTrail",
"accountId": "086441151436", "accessKeyId": "AKIAI44QH8DHBEXAMPLE", "userName": "AWSCloudTrail", "sessionContext": {"attributes": { "mfaAuthenticated": "false", "creationDate": "2015-11-11T21:15:33Z" }}, "invokedBy": "internal.amazonaws.com" }, "eventTime": "2015-11-11T21:15:33Z", "eventSource": "kms.amazonaws.com",
"eventName": "GenerateDataKey",
"awsRegion": "us-west-2", "sourceIPAddress": "internal.amazonaws.com", "userAgent": "internal.amazonaws.com", "requestParameters": { "keyId": "arn:aws:kms:us-west-2:111122223333:alias/ExampleAliasForCloudTrailKMS key", "encryptionContext": { "aws:cloudtrail:arn": "arn:aws:cloudtrail:us-west-2:111122223333:trail/Default",
"aws:s3:arn": "arn:aws:s3:::example-bucket-for-CT-logs/AWSLogs/111122223333/" }, "keySpec": "AES_256" }, "responseElements": null, "requestID": "581f1f11-88b9-11e5-9c9c-595a1fb59ac0", "eventID": "3cdb2457-c035-4890-93b6-181832b9e766", "readOnly": true, "resources": [{ "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"accountId": "111122223333" }], "eventType": "AwsServiceEvent", "recipientAccountId": "111122223333" }
CloudTrail puts a log file into your S3 bucket
Each time CloudTrail puts a log file into your S3 bucket, Amazon S3 sends a GenerateDataKey
request
to AWS KMS on behalf of CloudTrail. In response to this request, AWS KMS generates a unique data key
and then sends Amazon S3 two copies of the data key, one in plaintext and one that is encrypted
with the specified KMS key. Amazon S3 uses the plaintext data key to encrypt the CloudTrail log file and
then removes the plaintext data key from memory as soon as possible after use. Amazon S3 stores
the encrypted data key as metadata with the encrypted CloudTrail log file.
The GenerateDataKey
request includes the following information for the
encryption context:
-
The Amazon Resource Name (ARN) of the CloudTrail trail
-
The ARN of the S3 object (the CloudTrail log file)
Each GenerateDataKey
request results in an entry in your CloudTrail logs similar
to the following example. When you see a log entry like this one, you can determine that
CloudTrail (
) called the AWS KMS (
)
GenerateDataKey
operation (
) for a specific trail (
) to protect a specific log file (
). AWS KMS created the data key under the specified KMS key (
), shown twice in the same log entry.
Note
You might need to scroll to the right to see some of the callouts in the following example log entry.
{ "eventVersion": "1.02", "userIdentity": { "type": "AssumedRole", "principalId": "AROACKCEVSQ6C2EXAMPLE:i-34755b85", "arn": "arn:aws:sts::086441151436:assumed-role/AWSCloudTrail/i-34755b85",
"accountId": "086441151436", "accessKeyId": "AKIAI44QH8DHBEXAMPLE", "sessionContext": { "attributes": { "mfaAuthenticated": "false", "creationDate": "2015-11-11T20:45:25Z" }, "sessionIssuer": { "type": "Role", "principalId": "AROACKCEVSQ6C2EXAMPLE", "arn": "arn:aws:iam::086441151436:role/AWSCloudTrail", "accountId": "086441151436", "userName": "AWSCloudTrail" } }, "invokedBy": "internal.amazonaws.com" }, "eventTime": "2015-11-11T21:15:58Z", "eventSource": "kms.amazonaws.com",
"eventName": "GenerateDataKey",
"awsRegion": "us-west-2", "sourceIPAddress": "internal.amazonaws.com", "userAgent": "internal.amazonaws.com", "requestParameters": { "encryptionContext": { "aws:cloudtrail:arn": "arn:aws:cloudtrail:us-west-2:111122223333:trail/Default",
"aws:s3:arn": "arn:aws:s3:::example-bucket-for-CT-logs/AWSLogs/111122223333/CloudTrail/us-west-2/2015/11/11/111122223333_CloudTrail_us-west-2_20151111T2115Z_7JREEBimdK8d2nC9.json.gz"
}, "keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"keySpec": "AES_256" }, "responseElements": null, "requestID": "66f3f74a-88b9-11e5-b7fb-63d925c72ffe", "eventID": "7738554f-92ab-4e27-83e3-03354b1aa898", "readOnly": true, "resources": [{ "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"accountId": "111122223333" }], "eventType": "AwsServiceEvent", "recipientAccountId": "111122223333" }
You get an encrypted log file from your S3 bucket
Each time you get an encrypted CloudTrail log file from your S3 bucket, Amazon S3 sends a Decrypt
request to AWS KMS on your
behalf to decrypt the log file's encrypted data key. In response to this request, AWS KMS uses
your KMS key to decrypt the data key and then sends the plaintext data key to Amazon S3. Amazon S3 uses
the plaintext data key to decrypt the CloudTrail log file and then removes the plaintext data key
from memory as soon as possible after use.
The Decrypt
request includes the following information for the encryption context:
-
The Amazon Resource Name (ARN) of the CloudTrail trail
-
The ARN of the S3 object (the CloudTrail log file)
Each Decrypt
request results in an entry in your CloudTrail logs similar to the
following example. When you see a log entry like this one, you can determine that a user in
your AWS account (
) called the AWS KMS (
)
Decrypt
operation (
) for a specific trail (
) and a specific log file (
). AWS KMS decrypted the data key under a specific KMS key (
).
Note
You might need to scroll to the right to see some of the callouts in the following example log entry.
{ "eventVersion": "1.02", "userIdentity": { "type": "IAMUser", "principalId": "AIDACKCEVSQ6C2EXAMPLE", "arn": "arn:aws:iam::111122223333:role/cloudtrail-admin",
"accountId": "111122223333", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "userName": "cloudtrail-admin", "sessionContext": {"attributes": { "mfaAuthenticated": "false", "creationDate": "2015-11-11T20:48:04Z" }}, "invokedBy": "signin.amazonaws.com" }, "eventTime": "2015-11-11T21:20:52Z", "eventSource": "kms.amazonaws.com",
"eventName": "Decrypt",
"awsRegion": "us-west-2", "sourceIPAddress": "internal.amazonaws.com", "userAgent": "internal.amazonaws.com", "requestParameters": { "encryptionContext": { "aws:cloudtrail:arn": "arn:aws:cloudtrail:us-west-2:111122223333:trail/Default",
"aws:s3:arn": "arn:aws:s3:::example-bucket-for-CT-logs/AWSLogs/111122223333/CloudTrail/us-west-2/2015/11/11/111122223333_CloudTrail_us-west-2_20151111T2115Z_7JREEBimdK8d2nC9.json.gz"
} }, "responseElements": null, "requestID": "16a0590a-88ba-11e5-b406-436f15c3ac01", "eventID": "9525bee7-5145-42b0-bed5-ab7196a16daa", "readOnly": true, "resources": [{ "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"accountId": "111122223333" }], "eventType": "AwsApiCall", "recipientAccountId": "111122223333" }