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
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/*" ] } } } ] }