Permissions for Amazon services in key policies - 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).

Permissions for Amazon services in key policies

Many Amazon services use Amazon KMS keys to protect the resources they manage. When a service uses Amazon owned keys or Amazon managed keys, the service establishes and maintains the key policies for these KMS keys.

However, when you use a customer managed key with an Amazon service, you set and maintain the key policy. That key policy must allow the service the minimum permissions that it requires to protect the resource on your behalf. We recommend that you follow the principle of least privilege: give the service only the permissions that it requires. You can do this effectively by learning which permissions the service needs and using Amazon global condition keys and Amazon KMS condition keys to refine the permissions.

To find the permissions that the service requires on a customer managed key, see the encryption documentation for the service. For example, for the permissions that Amazon Elastic Block Store (Amazon EBS) requires, see Permissions for IAM users in the Amazon EC2 User Guide for Linux Instances and Amazon EC2 User Guide for Windows Instances. For the permissions that Secrets Manager requires, see Authorizing use of the KMS key in the Amazon Secrets Manager User Guide.

Implementing least privileged permissions

When you give an Amazon service permission to use a KMS key, ensure that the permission is valid only for the resources that the service must access on your behalf. This least privilege strategy helps to prevent unauthorized use of a KMS key when requests are passed between Amazon services.

To implement a least privilege strategy, use we recommend using Amazon KMS encryption context condition keys and the global source ARN or source account condition keys.

Using encryption context condition keys

The most effective way to implement least privileged permissions when using Amazon KMS resources is to include the kms:EncryptionContext:context-key or kms:EncryptionContextKeys condition keys in the policy that allows principals to call Amazon KMS cryptographic operations. These condition keys are particularly effective because they associate the permission with the encryption context that is bound to the ciphertext when the resource is encrypted.

Use encryption context conditions keys only when the action in the policy statement is CreateGrant or an Amazon KMS symmetric cryptographic operation that takes an EncryptionContext parameter, such as the operations like GenerateDataKey or Decrypt. (For a list of supported operations, see kms:EncryptionContext:context-key or kms:EncryptionContextKeys.) If you use these condition keys to allow other operations, such as DescribeKey, permission will be denied.

Set the value to the encryption context that the service uses when it encrypts the resource. This information is typically available in the Security chapter of the service documentation. For example, the encryption context for Amazon Proton identifies the Amazon Proton resource and its associated template. The Amazon Secrets Manager encryption context identifies the secret and its version. The encryption context for Amazon Location identifies the tracker or collection.

The following example key policy statement allows Amazon Location Service to create grants on behalf of authorized users. This policy statement limits the permission by using the kms:ViaService, kms:CallerAccount, and kms:EncryptionContext:context-key condition keys to tie the permission to a particular tracker resource.

{ "Sid": "Allow Amazon Location to create grants on behalf of authorized users", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/LocationTeam" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": "geo.us-west-2.amazonaws.com", "kms:CallerAccount": "111122223333", "kms:EncryptionContext:aws:geo:arn": "arn:aws:geo:us-west-2:111122223333:tracker/SAMPLE-Tracker" } } }

Using aws:SourceArn or aws:SourceAccount condition keys

When the principal in a key policy statement is an Amazon service principal, we strongly recommend that you use the aws:SourceArn or aws:SourceAccount global condition keys, in addition to the kms:EncryptionContext:context-key condition key. The ARN and account values are included in the authorization context only when a request comes to Amazon KMS from another Amazon service. This combination of conditions implements least privileged permissions and avoids a potential confused deputy scenario. Service principals are not typically used as principals in a key policy, but some Amazon services, such as Amazon CloudTrail, require it.

To use the aws:SourceArn or aws:SourceAccount global condition keys, set the value to the Amazon Resource Name (ARN) or account of the resource that is being encrypted. For example, in a key policy statement that gives Amazon CloudTrail permission to encrypt a trail, set the value of aws:SourceArn to the ARN of the trail. Whenever possible, use aws:SourceArn, which is more specific. Set the value to the ARN or an ARN pattern with wildcard characters. If you don't know the ARN of the resource, use aws:SourceAccount instead.

Note

If a resource ARN includes characters that are not permitted in an Amazon KMS key policy, you cannot use that resource ARN in the value of the aws:SourceArn condition key. Instead, use the aws:SourceAccount condition key. For details about key policy document rules, see Key policy format.

In the following example key policy, the principal who gets the permissions is the Amazon CloudTrail service principal, cloudtrail.amazonaws.com. To implement least privilege, this policy uses the aws:SourceArn and kms:EncryptionContext:context-key condition keys. The policy statement allows CloudTrail to use the KMS key to generate the data key that it uses to encrypt a trail. The aws:SourceArn and kms:EncryptionContext:context-key conditions are evaluated independently. Any request to use the KMS key for the specified operation must satisfy both conditions.

To restrict the service's permission to the finance trail in the example account (111122223333) and us-west-2 Region, this policy statement sets the aws:SourceArn condition key to the ARN of a particular trail. The condition statement uses the ArnEquals operator to ensure that every element in the ARN is evaluated independently when matching. The example also uses the kms:EncryptionContext:context-key condition key to limit the permission to trails in a particular account and Region.

Before using this key policy, replace the example account ID, Region, and trail name with valid values from your account.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Allow CloudTrail to encrypt logs", "Effect": "Allow", "Principal": { "Service": "cloudtrail.amazonaws.com" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "ArnEquals": { "aws:SourceArn": [ "arn:aws:cloudtrail:us-west-2:111122223333:trail/finance" ] }, "StringLike": { "kms:EncryptionContext:aws:cloudtrail:arn": [ "arn:aws:cloudtrail:*:111122223333:trail/*" ] } } } ] }