Creating a key policy
You can create and manage key policies in the AWS KMS console or by using AWS KMS API operations, such as CreateKey, ReplicateKey, and PutKeyPolicy.
When you create a KMS key in the AWS KMS console, the console walks you through the steps
of creating a key policy based on the default key policy
for the console. When you use the CreateKey
or ReplicateKey
APIs, if you don't specify a key policy, these APIs apply the default key policy for keys created programmatically.
When you use the PutKeyPolicy
API, you are required to specify a key policy.
Each policy document can have one or more policy statements. The following example shows a valid key policy document with one policy statement.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "
Describe the policy statement
", "Effect": "Allow
", "Principal": { "AWS": "arn:aws:iam::111122223333:user/Alice
" }, "Action": "kms:DescribeKey
", "Resource": "*", "Condition": { "StringEquals
": {"kms:KeySpec": "SYMMETRIC_DEFAULT"
} } } ] }
Key policy format
A key policy document must conform to the following rules:
-
Up to 32 kilobytes (32,768 bytes)
-
The
Sid
element in a key policy statement can include spaces. (Spaces are prohibited in theSid
element of an IAM policy document.)
A key policy document can include only the following characters:
-
Printable ASCII characters
-
Printable characters in the Basic Latin and Latin-1 Supplement character set
-
The tab (
\u0009
), line feed (\u000A
), and carriage return (\u000D
) special characters
Elements in a key policy
A key policy document must have the following elements:
- Version
-
Specifies the key policy document version. Set the version to
2012-10-17
(the latest version). - Statement
-
Encloses the policy statements. A key policy document must have at least one statement.
Each key policy statement consists of up to six elements. The
Effect
,Principal
,Action
, andResource
elements are required.- Sid
-
(Optional) The statement identifier (
Sid
) an arbitrary string you can use to describe the statement. TheSid
in a key policy can include spaces. (You can't include spaces in an IAM policySid
element.) - Effect
-
(Required) Determines whether to allow or deny the permissions in the policy statement. Valid values are
Allow
orDeny
. If you don't explicitly allow access to a KMS key, access is implicitly denied. You can also explicitly deny access to a KMS key. You might do this to make sure that a user cannot access it, even when a different policy allows access. - Principal
-
(Required) The principal is the identity that gets the permissions specified in the policy statement. You can specify AWS accounts, IAM users, IAM roles, and some AWS services as principals in a key policy. IAM user groups are not a valid principal in any policy type.
An asterisk value, such as
"AWS": "*"
represents all AWS identities in all accounts.Important
Do not set the Principal to an asterisk (*) in any key policy statement that allows permissions unless you use conditions to limit the key policy. An asterisk gives every identity in every AWS account permission to use the KMS key, unless another policy statement explicitly denies it. Users in other AWS accounts can use your KMS key whenever they have corresponding permissions in their own account.
Note
IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see Security best practices in IAM in the IAM User Guide.
When the principal in a key policy statement is an AWS account principal expressed as
arn:aws:iam::
, the policy statement doesn't give permission to any IAM principal. Instead, it gives the AWS account permission to use IAM policies to delegate the permissions specified in the key policy. (A principal in111122223333
:root"arn:aws:iam::
format does not represent the AWS account root user, despite the use of "root" in the account identifier. However, the account principal represents the account and its administrators, including the account root user.)111122223333
:root"When the principal is another AWS account or its principals, the permissions are effective only when the account is enabled in the Region with the KMS key and key policy. For information about Regions that are not enabled by default ("opt-in Regions"), see Managing AWS Regions in the AWS General Reference.
To allow a different AWS account or its principals to use a KMS key, you must provide permission in a key policy and in an IAM policy in the other account. For details, see Allowing users in other accounts to use a KMS key.
- Action
-
(Required) Specify the API operations to allow or deny. For example, the
kms:Encrypt
action corresponds to the AWS KMS Encrypt operation. You can list more than one action in a policy statement. For more information, see Permissions reference. - Resource
-
(Required) In a key policy, the value of the Resource element is
"*"
, which means "this KMS key." The asterisk ("*"
) identifies the KMS key to which the key policy is attached.Note
If the required
Resource
element is missing from a key policy statement, the policy statement has no effect. A key policy statement without aResource
element doesn't apply to any KMS key.When a key policy statement is missing its
Resource
element, the AWS KMS console correctly reports an error, but the CreateKey and PutKeyPolicy APIs succeed, even though the policy statement is ineffective. - Condition
-
(Optional) Conditions specify requirements that must be met for a key policy to take effect. With conditions, AWS can evaluate the context of an API request to determine whether or not the policy statement applies.
To specify conditions, you use predefined condition keys. AWS KMS supports AWS global condition keys and AWS KMS condition keys. To support attribute-based access control (ABAC), AWS KMS provides condition keys that control access to a KMS key based on tags and aliases. For details, see ABAC for AWS KMS.
The format for a condition is:
"Condition": {"
condition operator
": {"condition key
": "condition value
"}}such as:
"Condition": {"
StringEquals
": {"kms:CallerAccount
": "111122223333
"}}
For more information about AWS policy syntax, see AWS IAM Policy Reference in the IAM User Guide.
Example key policy
The following example shows a complete key policy for a symmetric encryption KMS key. You can use it for reference as you read about the key policy concepts in this chapter. This key policy combines the example policy statements from the preceding default key policy section into a single key policy that accomplishes the following:
-
Allows the example AWS account, 111122223333, full access to the KMS key. It allows the account and its administrators, including the account root user (for emergencies), to use IAM policies in the account to allow access to the KMS key.
-
Allows the
ExampleAdminRole
IAM role to administer the KMS key. -
Allows the
ExampleUserRole
IAM role to use the KMS key.
{ "Id": "key-consolepolicy", "Version": "2012-10-17", "Statement": [ { "Sid": "Enable IAM user Permissions", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:root" }, "Action": "kms:*", "Resource": "*" }, { "Sid": "Allow access for Key Administrators", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/
ExampleAdminRole
" }, "Action": [ "kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*", "kms:Update*", "kms:Revoke*", "kms:Disable*", "kms:Get*", "kms:Delete*", "kms:TagResource", "kms:UntagResource", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion", "kms:RotateKeyOnDemand" ], "Resource": "*" }, { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleUserRole
" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" }, { "Sid": "Allow attachment of persistent resources", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/ExampleUserRole
" }, "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": "*", "Condition": { "Bool": { "kms:GrantIsForAWSResource": "true" } } } ] }