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, to control access to your customer master keys (CMKs) in AWS KMS.

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.

Note

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.

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 get 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.

Specifying CMKs in IAM policy statements

Some IAM policies control access to AWS KMS operations, such as CreateKey, that don't involve a particular customer master key (CMK). However, you can specify one or more CMKs as the resource in an IAM policy statement.

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.

To specify particular CMKs in an IAM policy, use the key ARN of the CMK, that is, the Amazon Resource Name (ARN) of the CMK. You cannot use a key id, alias name, or alias ARN to identify a CMK in an IAM policy statement.

For example, the following IAM policy statement allows the principal to call the DescribeKey, GenerateDataKey, and Decrypt operations on the CMKs listed in the Resource element of the policy statement.

{ "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 specify multiple CMKs, use a wildcard character (*). For example, the following policy statement allows the principal to call the specified operations on any CMK in the example account.

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

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.

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 read-only access to all CMKs through 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, though you do need to grant these users permission to use the API. For more information, see AWS KMS API permissions reference.

AWS managed (predefined) policies for AWS KMS

AWS addresses many common use cases by providing standalone IAM policies that are created and managed by AWS. These are called AWS managed policies. AWS managed policies provide the necessary permissions for common use cases so you don't have to investigate which permissions are needed. For more information, see AWS Managed Policies in the IAM User Guide.

AWS provides one AWS managed policy for AWS KMS called AWSKeyManagementServicePowerUser. This policy allows the following permissions:

  • Allows users to list all CMKs and aliases.

  • Allows users to retrieve information about each CMK, including its identifiers, creation date, rotation status, key policy, and more.

  • Allows users to create CMKs that they can administer or use. When users create a CMK, they can set permissions in the CMK's key policy. This means users can create CMKs with any permissions they want, including allowing themselves to administer or use the CMK. The AWSKeyManagementServicePowerUser policy does not allow users to administer or use any other CMKs, only the ones they create.

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.

Allow a user read-only access to all CMKs through the AWS KMS console

The following IAM policy allows users read-only access to the AWS KMS console. That is, users can use the console to view all CMKs, but they cannot make changes to any CMKs or create new ones.

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "kms:DescribeKey", "kms:GetKeyPolicy", "kms:GetKeyRotationStatus", "kms:GetPublicKey", "kms:ListKeys", "kms:ListAliases", "kms:ListKeyPolicies", "iam:ListUsers", "iam:ListRoles" ], "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": "*" } }

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

The following IAM policy allows a user to successfully request that AWS KMS 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 successfully request that AWS KMS 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, 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": "*" } }