AWS awscloudtrail documentation change
Summary
Updated KMS key policy documentation to differentiate between trails and event data stores, added details about encrypting digest files, restructured sections, and standardized policy statement IDs.
Security assessment
The changes clarify and expand documentation on KMS key policies required for CloudTrail encryption, improving guidance for secure configuration. While KMS policies are security-critical, there is no evidence this addresses a specific vulnerability. The updates enhance security documentation by adding granularity for trails vs event data stores and digest files.
Diff
diff --git a/awscloudtrail/latest/userguide/create-kms-key-policy-for-cloudtrail.md b/awscloudtrail/latest/userguide/create-kms-key-policy-for-cloudtrail.md index 2e08defc4..6bc6a96b5 100644 --- a//awscloudtrail/latest/userguide/create-kms-key-policy-for-cloudtrail.md +++ b//awscloudtrail/latest/userguide/create-kms-key-policy-for-cloudtrail.md @@ -5 +5 @@ -Required KMS key policy sections for use with CloudTrailGranting encrypt permissionsGranting decrypt permissionsEnable CloudTrail to describe KMS key properties +Required KMS key policy sections for use with CloudTrailGranting encrypt permissions for trailsGranting encrypt permissions for event data storesGranting decrypt permissions for trailsGranting decrypt permissions for event data storesEnable CloudTrail to describe KMS key properties @@ -24 +24 @@ If you create a KMS key in the CloudTrail console, CloudTrail adds the required -If you create a KMS key in the AWS Management or the AWS CLI, you must add policy sections to the key so that you can use it with CloudTrail. The policy must allow CloudTrail to use the key to encrypt your log files and event data stores, and allow the users you specify to read log files in unencrypted form. +If you create a KMS key in the AWS Management Console or the AWS CLI, you must add policy sections to the key so that you can use it with CloudTrail. The policy must allow CloudTrail to use the key to encrypt your log files, digest files, and event data stores, and allow the users you specify to read log files and digest files in unencrypted form. @@ -36,0 +37,19 @@ See the following resources: +###### Topics + + * Required KMS key policy sections for use with CloudTrail + + * Granting encrypt permissions for trails + + * Granting encrypt permissions for event data stores + + * Granting decrypt permissions for trails + + * Granting decrypt permissions for event data stores + + * Enable CloudTrail to describe KMS key properties + + * [Default KMS key policy created in CloudTrail console](./default-kms-key-policy.html) + + + + @@ -52 +71 @@ If you created a KMS key with the AWS Management console or the AWS CLI, then yo - 1. Enable CloudTrail log encrypt permissions. See Granting encrypt permissions. + 1. Grant permissions to encrypt CloudTrail log and digest files. For more information, see Granting encrypt permissions for trails. @@ -54 +73 @@ If you created a KMS key with the AWS Management console or the AWS CLI, then yo - 2. Enable CloudTrail log decrypt permissions. See Granting decrypt permissions. If you are using an existing S3 bucket with an [S3 Bucket Key](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-key.html), `kms:Decrypt` permissions are required to create or update a trail with SSE-KMS encryption enabled. + 2. Grant permissions to decrypt CloudTrail log and digest files. For more information, see Granting decrypt permissions for trails. If you are using an existing S3 bucket with an [S3 Bucket Key](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-key.html), `kms:Decrypt` permissions are required to create or update a trail with SSE-KMS encryption enabled. @@ -56 +75 @@ If you created a KMS key with the AWS Management console or the AWS CLI, then yo - 3. Enable CloudTrail to describe KMS key properties. See Enable CloudTrail to describe KMS key properties. + 3. Enable CloudTrail to describe KMS key properties. For more information, see Enable CloudTrail to describe KMS key properties. @@ -73 +92 @@ If encryption is enabled on a trail, and the KMS key is disabled, or the KMS key - 1. Enable CloudTrail log encrypt permissions. See Granting encrypt permissions. + 1. Grant permissions to encrypt a CloudTrail Lake event data store. For more information, see Granting encrypt permissions for event data stores. @@ -75,3 +94 @@ If encryption is enabled on a trail, and the KMS key is disabled, or the KMS key - 2. Enable CloudTrail log decrypt permissions. See Granting decrypt permissions. - - 3. Grant users and roles permission to encrypt and decrypt event data store data with the KMS key. + 2. Grant permissions to decrypt a CloudTrail Lake event data store. For more information, see Granting decrypt permissions for event data stores. @@ -81 +98 @@ When you create an event data store and encrypt it with a KMS key, or run querie - 4. Enable CloudTrail to describe KMS key properties. See Enable CloudTrail to describe KMS key properties. + 3. Enable CloudTrail to describe KMS key properties. For more information, see Enable CloudTrail to describe KMS key properties. @@ -94 +111 @@ If encryption is enabled on an event data store, and the KMS key is disabled or -## Granting encrypt permissions +## Granting encrypt permissions for trails @@ -96 +113 @@ If encryption is enabled on an event data store, and the KMS key is disabled or -###### Example Allow CloudTrail to encrypt logs on behalf of specific accounts +###### Example Allow CloudTrail to encrypt log files and digest files on behalf of specific accounts @@ -98 +115 @@ If encryption is enabled on an event data store, and the KMS key is disabled or -CloudTrail needs explicit permission to use the KMS key to encrypt logs on behalf of specific accounts. To specify an account, add the following required statement to your KMS key policy and replace `account-id`, `region`, and `trailName` with the appropriate values for your configuration. You can add additional account IDs to the `EncryptionContext` section to enable those accounts to use CloudTrail to use your KMS key to encrypt log files. +CloudTrail needs explicit permission to use the KMS key to encrypt log files and digest files on behalf of specific accounts. To specify an account, add the following required statement to your KMS key policy and replace `account-id`, `region`, and `trailName` with the appropriate values for your configuration. You can add additional account IDs to the `EncryptionContext` section to enable those accounts to use CloudTrail to use your KMS key to encrypt log files and digest files. @@ -104 +121 @@ As a security best practice, add an `aws:SourceArn` condition key to the KMS key - "Sid": "Allow CloudTrail to encrypt logs", + "Sid": "AllowCloudTrailEncryptLogs", @@ -121,17 +138 @@ As a security best practice, add an `aws:SourceArn` condition key to the KMS key -A policy for a KMS key used to encrypt CloudTrail Lake event data store logs cannot use the condition keys `aws:SourceArn` or `aws:SourceAccount`. The following is an example of a KMS key policy for an event data store. - - - { - "Sid": "Allow CloudTrail to encrypt event data store", - "Effect": "Allow", - "Principal": { - "Service": "cloudtrail.amazonaws.com" - }, - "Action": [ - "kms:GenerateDataKey", - "kms:Decrypt" - ], - "Resource": "*" - } - -The following example policy statement illustrates how another account can use your KMS key to encrypt CloudTrail logs. +The following example policy statement illustrates how another account can use your KMS key to encrypt CloudTrail log files and digest files. @@ -148 +149 @@ The following example policy statement illustrates how another account can use y -In the policy, you add one or more accounts that encrypt with your key to the CloudTrail **EncryptionContext**. This restricts CloudTrail to using your key to encrypt logs only for the accounts that you specify. When you give the root of account `222222222222` permission to encrypt logs, it delegates permission to the account administrator to encrypt the necessary permissions to other users in that account. The account administrator does this by changing the policies associated with those IAM users. +In the policy, you add one or more accounts that encrypt with your key to the CloudTrail **EncryptionContext**. This restricts CloudTrail to using your key to encrypt log files and digest files only for the accounts that you specify. When you give the root of account `222222222222` permission to encrypt log files and digest files, it delegates permission to the account administrator to encrypt the necessary permissions to other users in that account. The account administrator does this by changing the policies associated with those IAM users. @@ -156 +157 @@ KMS key policy statement: - "Sid": "Enable CloudTrail encrypt permissions", + "Sid": "EnableCloudTrailEncryptPermissions", @@ -178 +179,19 @@ For more information about editing a KMS key policy for use with CloudTrail, see -## Granting decrypt permissions +## Granting encrypt permissions for event data stores + +A policy for a KMS key used to encrypt a CloudTrail Lake event data store cannot use the condition keys `aws:SourceArn` or `aws:SourceAccount`. The following is an example of a KMS key policy for an event data store. + + + { + "Sid": "AllowCloudTrailEncryptEds", + "Effect": "Allow", + "Principal": { + "Service": "cloudtrail.amazonaws.com" + }, + "Action": [ + "kms:GenerateDataKey", + "kms:Decrypt" + ], + "Resource": "*" + } + +## Granting decrypt permissions for trails @@ -188 +207 @@ Users of your key must be given explicit permissions to read the log files that - "Sid": "Enable CloudTrail log decrypt permissions", + "Sid": "EnableCloudTrailLogDecryptPermissions", @@ -206,30 +225 @@ The following is an example policy that is required to allow the CloudTrail serv - "Sid": "Allow CloudTrail to decrypt a trail", - "Effect": "Allow", - "Principal": { - "Service": "cloudtrail.amazonaws.com" - }, - "Action": "kms:Decrypt", - "Resource": "*" - } - -A decrypt policy for a KMS key that is used with a CloudTrail Lake event data store is similar to the following. The user or role ARNs specified as values for `Principal` need decrypt permissions to create or update event data stores, run queries, or get query results. - - - { - "Sid": "Enable user key permissions for event data stores" - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::account-id:user/username" - }, - "Action": [ - "kms:Decrypt", - "kms:GenerateDataKey" - ], - "Resource": "*" - } - -The following is an example policy that is required to allow the CloudTrail service principal to decrypt event data store logs. - - - { - "Sid": "Allow CloudTrail to decrypt an event data store", + "Sid": "AllowCloudTrailDecryptTrail", @@ -265 +255 @@ KMS key policy statement: - "Sid": "Enable CloudTrail log decrypt permissions", + "Sid": "EnableCloudTrailLogDecryptPermissions", @@ -286 +276 @@ KMS key policy statement: -You can allow users in other accounts to use your KMS key to decrypt trail logs, but not event data store logs. The changes required to your key policy depend on whether the S3 bucket is in your account or in another account. +You can allow users in other accounts to use your KMS key to decrypt trail logs. The changes required to your key policy depend on whether the S3 bucket is in your account or in another account. @@ -309 +299 @@ KMS key policy statement: - "Sid": "Enable encrypted CloudTrail log read access", + "Sid": "EnableEncryptedCloudTrailLogReadAccess", @@ -360 +350 @@ KMS key policy statement: - "Sid": "Enable encrypted CloudTrail log read access", + "Sid": "EnableEncryptedCloudTrailLogReadAccess", @@ -394,0 +385,31 @@ For information about editing a KMS key policy for use with CloudTrail, see [Edi +## Granting decrypt permissions for event data stores + +A decrypt policy for a KMS key that is used with a CloudTrail Lake event data store is similar to the following. The user or role ARNs specified as values for `Principal` need decrypt permissions to create or update event data stores, run queries, or get query results. + + + { + "Sid": "EnableUserKeyPermissionsEds" + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::account-id:user/username" + }, + "Action": [ + "kms:Decrypt", + "kms:GenerateDataKey" + ], + "Resource": "*" + } + +The following is an example policy that is required to allow the CloudTrail service principal to decrypt an event data store. + + + { + "Sid": "AllowCloudTrailDecryptEds", + "Effect": "Allow", + "Principal": { + "Service": "cloudtrail.amazonaws.com" + }, + "Action": "kms:Decrypt", + "Resource": "*" + } + @@ -403 +424 @@ As a security best practice, add an `aws:SourceArn` condition key to the KMS key - "Sid": "Allow CloudTrail access", + "Sid": "AllowCloudTrailAccess",