Creating a key policy - AWS Key Management Service
Creating a key policy - AWS Key Management Service
Key policy formatElements in a key policyExample key policy

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 the Sid 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, and Resource elements are required.

Sid

(Optional) The statement identifier (Sid) an arbitrary string you can use to describe the statement. The Sid in a key policy can include spaces. (You can't include spaces in an IAM policy Sid element.)

Effect

(Required) Determines whether to allow or deny the permissions in the policy statement. Valid values are Allow or Deny. 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::111122223333:root", 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 in arn:aws:iam::111122223333:root" 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.)

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.

Note

If the required Action element is missing from a key policy statement, the policy statement has no effect. A key policy statement without an Action element doesn't apply to any KMS key.

When a key policy statement is missing its Action element, the AWS KMS console correctly reports an error, but the CreateKey and PutKeyPolicy APIs succeed, even though the policy statement is ineffective.

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 a Resource 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"
                }
            }
        }
    ]
}