Using IAM policies with AWS KMS - AWS Key Management Service

Using IAM policies with AWS KMS

You can use IAM policies, along with key policies, grants, and VPC endpoint policies, to control access to your customer master keys (CMKs) in AWS KMS.

Note

To use an IAM policy to control access to a CMK, the key policy for the CMK must give the account permission to use IAM policies. Specifically, the key policy must include the policy statement that enables IAM policies.

This section explains how to use IAM policies to control access to AWS KMS operations. For more general information about IAM, see the IAM User Guide.

All CMKs must have a key policy. IAM policies are optional. To use an IAM policy to control access to a CMK, the key policy for the CMK must give the account permission to use IAM policies. Specifically, the key policy must include the policy statement that enables IAM policies.

IAM policies can control access to any AWS KMS operation. Unlike key policies, IAM policies can control access to multiple CMKs and provide permissions for the operations of several related AWS services. But IAM policies are particularly useful for controlling access to operations, such as CreateKey, that can't be controlled by a key policy because they don't involve any particular CMK.

If you access AWS KMS through an Amazon Virtual Private Cloud (Amazon VPC) endpoint, you can also use a VPC endpoint policy to limit access to your AWS KMS resources when using the endpoint. For example, when using the VPC endpoint, you might only allow the principals in your AWS account to access your CMKs. For details, see Controlling access to a VPC endpoint .

For help writing and formatting a JSON policy document, see the IAM JSON Policy Reference in the IAM User Guide.

Overview of IAM policies

You can use IAM policies in the following ways:

  • Attach a permissions policy to a user or a group – You can attach a policy that allows an IAM user or group of users to call AWS KMS operations.

  • Attach a permissions policy to a role for federation or cross-account permissions – You can attach an IAM policy to an IAM role to enable identity federation, allow cross-account permissions, or give permissions to applications running on EC2 instances. For more information about the various use cases for IAM roles, see IAM Roles in the IAM User Guide.

The following example shows an IAM policy with AWS KMS permissions. This policy allows the IAM identities to which it is attached to list all CMKs and aliases.

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:ListKeys", "kms:ListAliases" ], "Resource": "*" } }

Like all IAM policies, this policy doesn't have a Principal element. When you attach an IAM policy to an IAM user or IAM role, the user or assumed role user gets the permissions specified in the policy.

For a table showing all of the AWS KMS API actions and the resources that they apply to, see the AWS KMS API permissions reference.

Best practices for IAM policies

Securing access to AWS KMS customer master keys (CMKs) is critical to the security of all of your AWS resources. AWS KMS CMKs are used to protect many of the most sensitive resources in your AWS account. Take the time to design the key policies, IAM policies, grants, and VPC endpoint policies that control access to your CMKs.

In IAM policy statements that control access to CMKs, use the least privileged principle. Give IAM principals only the permissions they need on only the CMKs they must use or manage.

Use key policies

Whenever possible, provide permissions in key policies that affect one CMK, rather than in an IAM policy that can apply to many CMKs, including those in other AWS accounts. This is particularly important for sensitive permissions like kms:PutKeyPolicy and kms:ScheduleKeyDeletion but also for cryptographic operations that determine how your data is protected.

Limit CreateKey permission

Give permission to create keys (kms:CreateKey) only to principals who need it. Principals who create a CMK also set its key policy, so they can give themselves and others permission to use and manage the CMKs they create. When you allow this permission, consider limiting it by using policy conditions. For example, you can use the kms:CustomerMasterKeySpec condition to limit the permission to symmetric CMKs.

Specify CMKs in an IAM policy

As a best practice, specify the key ARN of each CMK to which the permission applies in the Resource element of the policy statement. This practice restricts the permission to the CMKs that principal requires. For example, this Resource element lists only the CMKs the principal needs to use.

"Resource": [ "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" ]

When specifying CMKs is impractical, use a Resource value that limits access to CMKs in a trusted AWS account and Region, such as arn:aws:kms:region:account:key/*. Or limit access to CMKs in all Regions (*) of a trusted AWS account, such as arn:aws:kms:*:account:key/*.

Avoid "Resource": "*" in an IAM policy

Use wildcard characters (*) judiciously. In a key policy, the wildcard character in the Resource element represents the CMK to which the key policy is attached. But in an IAM policy, a wildcard character alone in the Resource element ("Resource": "*") applies the permissions to all CMKs in all AWS accounts that the principal's account has permission to use. This might include CMKs in other AWS accounts, as well as CMKs in the principal's account.

For example, to use a CMK in another AWS account, a principal needs permission from the key policy of the CMK in the external account, and from an IAM policy in their own account. Suppose that an arbitrary account gave your AWS account kms:Decrypt permission on their CMKs. If so, an IAM policy in your account that gives a role kms:Decrypt permission on all CMKs ("Resource": "*") would satisfy the IAM part of the requirement. As a result, principals who can assume that role can now decrypt ciphertexts using the CMK in the untrusted account. Entries for their operations appear in the CloudTrail logs of both accounts.

In particular, avoid using "Resource": "*" in a policy statement that allows the following API operations. These operations can be called on CMKs in other AWS accounts.

When to use "Resource": "*"

In an IAM policy, use a wildcard character in the Resource element only for permissions that require it. Only the following permissions require the "Resource": "*" element.

Note

Permissions for alias operations (kms:CreateAlias, kms:UpdateAlias, kms:DeleteAlias) must be attached to the alias and the CMK. You can use "Resource": "*" in an IAM policy to represent the aliases and the CMKs, or specify the aliases and CMKs in the Resource element. For examples, see Controlling access to aliases.

 

The examples in this topic provide more information and guidance for designing IAM policies for CMKs. For general AWS KMS best practice guidance, see the AWS Key Management Service Best Practices whitepaper.

Specifying CMKs in IAM policy statements

You can use an IAM policy to allow a principal to use or manage CMKs. CMKs are specified in the Resource element of the policy statement.

When writing your policy statements, it's a best practice to limit the CMKs to those that the principals need to use, rather than giving them access to all CMKs.

  • To specify particular CMKs in an IAM policy statement, use the key ARN of each CMK. You cannot use a key id, alias name, or alias ARN to identify a CMK in an IAM policy statement.

    For example: "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"

  • To specify multiple CMKs in the account and Region, use wildcard characters (*) in the Region or resource ID positions of the key ARN.

    For example, to specify all CMKs in the US West (Oregon) Region of an account, use "Resource": "arn:aws:kms:us-west-2:111122223333:key/*". To specify all CMKs in all Regions of the account, use "Resource": "arn:aws:kms:*:111122223333:key/*".

  • To represent all CMKs, use a wildcard character alone ("*"). Use this format for operations that don't use any particular CMK, namely CreateKey, GenerateRandom, ListAliases, and ListKeys.

For example, the following IAM policy statement allows the principal to call the DescribeKey, GenerateDataKey, Decrypt operations only on the CMKs listed in the Resource element of the policy statement. Specifying CMKs by key ARN, which is a best practice, ensures that the permissions are limited only to the specified CMKs.

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:DescribeKey", "kms:GenerateDataKey", "kms:Decrypt" ], "Resource": [ "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" ] } }

To apply the permission to all CMKs in a particular trusted AWS account, you can use wildcard characters (*) in the Region and key ID positions. For example, the following policy statement allows the principal to call the specified operations on all CMKs in two trusted example accounts.

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:DescribeKey", "kms:GenerateDataKey", "kms:GenerateDataKeyPair" ], "Resource": [ "arn:aws:kms:*:111122223333:key/*", "arn:aws:kms:*:444455556666:key/*" ] } }

You can also use a wildcard character ("*") alone in the Resource element. Because it allows access to all CMKs the account has permission to use, it's recommended primarily for operations that don't involve a particular CMK and for Deny statements. You can also use it in policy statements that allow only less sensitive read-only operations. To determine whether an AWS KMS operation involves a particular CMK, look for the CMK value in the Resources column of the table in AWS KMS API permissions: Actions and resources reference.

For example, the following policy statement uses a Deny effect to prohibit the principals from using the specified operations on any CMK. It uses a wildcard character in the Resource element to represent all CMKs.

{ "Version": "2012-10-17", "Statement": { "Effect": "Deny", "Action": [ "kms:CreateKey", "kms:PutKeyPolicy", "kms:CreateGrant", "kms:ScheduleKeyDeletion" ], "Resource": "*" } }

The following policy statement uses a wildcard character alone to represent all CMKs. But it allows only less sensitive read-only operations and operations that don't apply to any particular CMK.

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:CreateKey", "kms:ListKeys", "kms:ListAliases", "kms:ListResourceTags" ], "Resource": "*" } }

Permissions required to use the AWS KMS console

To work with the AWS KMS console, users must have a minimum set of permissions that allow them to work with the AWS KMS resources in their AWS account. In addition to these AWS KMS permissions, users must also have permissions to list IAM users and roles. If you create an IAM policy that is more restrictive than the minimum required permissions, the AWS KMS console won't function as intended for users with that IAM policy.

For the minimum permissions required to allow a user read-only access to the AWS KMS console, see Allow a user to view CMKs in the AWS KMS console.

To allow users to work with the AWS KMS console to create and manage CMKs, attach the AWSKeyManagementServicePowerUser managed policy to the user, as described in the following section.

You don't need to allow minimum console permissions for users that are working with the AWS KMS API through the AWS SDKs or command line tools. However, you do need to grant these users permission to use the API. For more information, see AWS KMS API permissions reference.

AWS managed policy for power users

You can use an AWS managed policy to give IAM principals in your account the permissions of a power user. Power users can create CMKs, use and manage the CMKs they create, and view all CMKs and IAM identities.

Note

This policy gives the power user kms:DescribeKey permissions on any CMK with a key policy that permits the operation. This might include CMKs in untrusted AWS accounts. For details, see Best practices for IAM policies.

The AWSKeyManagementServicePowerUser managed policy includes the following permissions.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:CreateAlias", "kms:CreateKey", "kms:DeleteAlias", "kms:Describe*", "kms:GenerateRandom", "kms:Get*", "kms:List*", "kms:TagResource", "kms:UntagResource", "iam:ListGroups", "iam:ListRoles", "iam:ListUsers" ], "Resource": "*" } ] }
  • Allows users to create CMKs. Because this process includes setting the key policy, power users can give themselves and others permission to use and manage the CMKs they create.

  • Allows users to create and delete aliases and tags on all CMKs.

  • Allows users to get detailed information about all CMKs, including their key ARN, cryptographic configuration, key policy, aliases, tags, and rotation status.

  • Allows users to list IAM users, groups, and roles.

  • This policy does not give these users permission to use or manage CMKs that they didn't create, although they can manages aliases and tags on all CMKs.

Users who have the AWSKeyManagementServicePowerUser managed policy can also get permissions from other sources, including key policies, other IAM policies, and grants.

Customer managed policy examples

In this section, you can find example IAM policies that allow permissions for various AWS KMS actions.

Important

Some of the permissions in the following policies are allowed only when the CMK's key policy also allows them. For more information, see AWS KMS API permissions reference.

For help writing and formatting a JSON policy document, see the IAM JSON Policy Reference in the IAM User Guide.

Allow a user to view CMKs in the AWS KMS console

The following IAM policy allows users read-only access to the AWS KMS console. Users with these permissions can view all CMKs in their AWS account, but they cannot create or change any CMKs.

To view CMKs on the AWS managed keys and Customer managed keys pages, principals require kms:ListKeys and kms:ListAliases permissions. The remaining permissions, particularly kms:DescribeKey, are required to view optional CMK table columns and data on the CMK detail pages. The iam:ListUsers and iam:ListRoles permissions are required to display the key policy in default view without error. To view data on the Custom key stores page and details about CMKs in custom key stores, principals also need kms:DescribeCustomKeyStores permission.

If you limit a user's console access to particular CMKs, the console displays an error for each CMK that is not visible.

This policy includes of two policy statements. The Resource element in the first policy statement allows the specified permissions on all CMKs in all Regions of the example AWS account. Console viewers don't need additional access because the AWS KMS console displays only CMKs in the principal's account. This is true even if they have permission to view CMKs in other AWS accounts. The remaining AWS KMS and IAM permissions require a "Resource": "*" element because they don't apply to any particular CMK.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Allow read-only permission to all CMKs in the account", "Effect": "Allow", "Action": [ "kms:GetPublicKey", "kms:GetKeyRotationStatus", "kms:GetKeyPolicy", "kms:DescribeKey", "kms:ListKeyPolicies", "kms:ListResourceTags" ], "Resource": "arn:aws:kms:*:111122223333:key/*" }, { "Sid": "Allow read-only access to operations with no CMK resource", "Effect": "Allow", "Action": [ "kms:ListKeys", "kms:ListAliases", "iam:ListRoles", "iam:ListUsers" ], "Resource": "*" } ] }

Allow a user to create CMKs

The following IAM policy allows a user to create CMKs. The value of the Resource element is * because the CreateKey operation does not use any particular AWS KMS resources (CMKs or aliases).

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "kms:CreateKey", "Resource": "*" } }

Principals who create keys might need some related permissions.

  • kms:PutKeyPolicy — Principals who have kms:CreateKey permission can set the initial key policy for the CMK. However, the CreateKey caller must have kms:PutKeyPolicy permission, which lets them change the CMK's key policy, or they must specify the BypassPolicyLockoutSafetyCheck parameter of CreateKey, which is not recommended. The CreateKey caller can get kms:PutKeyPolicy permission for the CMK from an IAM policy or they can include this permission in the key policy of the CMK that they're creating.

  • kms:TagResource — To add tags to the CMK during the CreateKey operation, the CreateKey caller must have kms:TagResource permission in an IAM policy. Including this permission in the key policy of the new CMK isn't sufficient. However, if the CreateKey caller includes kms:TagResource in the initial key policy, they can add tags in a separate call after the CMK is created.

  • kms:CreateAlias — Principals who create a CMK in the AWS KMS console must have kms:CreateAlias permission on the CMK and on the alias. (The console makes two calls; one to CreateKey and one to CreateAlias). You must provide the alias permission in an IAM policy. You can provide the CMK permission in a key policy or IAM policy. For details, see Controlling access to aliases.

In addition to kms:CreateKey, the following IAM policy provides kms:TagResource permission on all CMKs in the AWS account and kms:CreateAlias permission on all aliases that the account. It also includes some useful read-only permissions that can be provided only in an IAM policy.

This IAM policy does not include kms:PutKeyPolicy permission or any other permissions that can be set in a key policy. It's a best practice to set these permissions in the key policy where they apply exclusively to one CMK.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "IAM permissions for particular CMKs", "Effect": "Allow", "Action": { "kms:TagResource" }, "Resource": "arn:aws:kms:*:111122223333:key/*" }, { "Sid": "IAM permissions for particular aliases", "Effect": "Allow", "Action": { "kms:CreateAlias" }, "Resource": "arn:aws:kms:*:111122223333:alias/*" }, { "Sid": "IAM permission that must be set for all CMKs", "Effect": "Allow", "Action": [ "kms:CreateKey", "kms:ListKeys", "kms:ListAliases" ], "Resource": "*" } ] }

Allow a user to encrypt and decrypt with any CMK in a specific AWS account

The following IAM policy allows a user to encrypt and decrypt data with any CMK in AWS account 111122223333.

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt" ], "Resource": "arn:aws:kms:*:111122223333:key/*" } }

Allow a user to encrypt and decrypt with any CMK in a specific AWS account and Region

The following IAM policy allows a user to encrypt and decrypt data with any CMK in AWS account 111122223333 in the US West (Oregon) Region.

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt" ], "Resource": [ "arn:aws:kms:us-west-2:111122223333:key/*" ] } }

Allow a user to encrypt and decrypt with specific CMKs

The following IAM policy allows a user to encrypt and decrypt data with the two CMKs specified in the Resource element. When specifying a CMK in an IAM policy statement, you must use the key ARN of the CMK.

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt" ], "Resource": [ "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" ] } }

Prevent a user from disabling or deleting any CMKs

The following IAM policy prevents a user from disabling or deleting any CMKs, even when another IAM policy or a key policy allows these permissions. A policy that explicitly denies permissions overrides all other policies, even those that explicitly allow the same permissions. For more information, see Troubleshooting key access.

{ "Version": "2012-10-17", "Statement": { "Effect": "Deny", "Action": [ "kms:DisableKey", "kms:ScheduleKeyDeletion" ], "Resource": "*" } }