Menu
AWS Key Management Service
Developer Guide

Determining Access to an AWS KMS Customer Master Key

To determine the full extent of who or what currently has access to a customer master key (CMK) in AWS KMS, you must examine the CMK's key policy, all grants that apply to the CMK, and potentially all AWS Identity and Access Management (IAM) policies. You might do this to determine the scope of potential usage of a CMK, or to help you meet compliance or auditing requirements. The following topics can help you generate a complete list of the AWS principals (identities) that currently have access to a CMK.

Understanding Policy Evaluation

When authorizing access to a CMK, AWS KMS evaluates the key policy attached to the CMK, all grants that apply to the CMK, and all IAM policies attached to the IAM user or role making the request. In many cases, AWS KMS must evaluate the CMK's key policy and IAM policies together to determine whether access to the CMK is allowed or denied. To do this, AWS KMS uses a process similar to the one described at Determining Whether a Request is Allowed or Denied in the IAM User Guide. Remember, though, that IAM policies by themselves are not sufficient to allow access to a KMS CMK. The CMK's key policy must also allow access.

For example, assume that you have two CMKs and three users, all in the same AWS account. The CMKs and users have the following policies:

Alice cannot access CMK1 because CMK1's key policy does not explicitly allow her access, and she has no IAM policy that allows access. Alice can access CMK2 because the CMK's key policy explicitly allows her access.

Bob can access CMK1 because CMK1's key policy enables IAM policies to allow access, and Bob has an IAM policy that allows access. Bob cannot access CMK2 because the key policy for CMK2 does not allow access to the account, so Bob's IAM policy does not by itself allow access to CMK2.

Charlie cannot access CMK1 or CMK2 because all AWS KMS actions are denied in his IAM policy. The explicit deny in Charlie's IAM policy overrides the explicit allow in CMK2's key policy.

Examining the Key Policy

You can examine the key policy in two ways:

  • If the CMK was created in the AWS Management Console, you can use the console's default view on the key details page to view the principals listed in the key policy. If you can view the key policy in this way, it means the key policy allows access with IAM policies. Be sure to examine IAM policies to determine the complete list of principals that can access the CMK.

  • You can use the GetKeyPolicy operation in the AWS KMS API to retrieve a copy of the key policy document, and then examine the document. You can also view the policy document in the AWS Management Console.

Examining the Key Policy in the AWS Management Console

To view a customer master key (CMK)'s permissions on the key details page (console)

  1. Open the Encryption Keys section of the Identity and Access Management (IAM) console at https://console.aws.amazon.com/iam/home#encryptionKeys.

  2. For Region, choose the appropriate AWS region. Do not use the region selector in the navigation bar (top right corner).

  3. In the list of keys, choose the alias of the key that you want to examine.

  4. In the Key Policy section of the key details page, find the list of IAM users and roles in the Key Administrators section, and another list in the Key Users section. The listed users, roles, and AWS accounts all have access to manage or use this CMK.

    Important

    The IAM users, roles, and AWS accounts listed here are the ones that have been explicitly granted access in the key policy. If you use IAM policies to allow access to CMKs, other IAM users and roles might have access to this CMK, even if they are not listed here. Take care to examine all IAM policies in this account to determine if they allow access to this CMK.

  5. (Optional) To view the key policy document, choose Switch to policy view.

Examining the Key Policy Document

You can view the key policy document in a couple of ways:

  • Use the key details page of the AWS Management Console (see the preceding section for instructions).

  • Use the GetKeyPolicy operation in the AWS KMS API to retrieve a copy of the key policy document.

Examine the key policy document and take note of all principals specified in each policy statement's Principal element. The IAM users, IAM roles, and AWS accounts in the Principal elements are those that have access to this CMK.

The following examples use the policy statements found in the default key policy to demonstrate how to do this.

Example Policy Statement 1

Copy
{ "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:root"}, "Action": "kms:*", "Resource": "*" }

In the preceding policy statement, arn:aws:iam::111122223333:root refers to the AWS account 111122223333. By default, a policy statement like this one is present in the key policy document when you create a new CMK with the console, and when you create a new CMK programmatically but do not provide a key policy.

Note

A key policy document with a statement that allows access to the AWS account (root user) enables IAM policies in the account to allow access to the CMK. This means that IAM users and roles in the account might have access to the CMK even if they are not explicitly listed as principals in the key policy document. Take care to examine all IAM policies in all AWS accounts listed as principals to determine whether they allow access to this CMK.

Example Policy Statement 2

Copy
{ "Sid": "Allow access for Key Administrators", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:user/KMSKeyAdmin"}, "Action": [ "kms:Describe*", "kms:Put*", "kms:Create*", "kms:Update*", "kms:Enable*", "kms:Revoke*", "kms:List*", "kms:Disable*", "kms:Get*", "kms:Delete*", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion" ], "Resource": "*" }

In the preceding policy statement, arn:aws:iam::111122223333:user/KMSKeyAdmin refers to the IAM user named KMSKeyAdmin in AWS account 111122223333. This user is allowed to perform the actions listed in the policy statement, which are the administrative actions for managing a CMK.

Example Policy Statement 3

Copy
{ "Sid": "Allow use of the key", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:role/EncryptionApp"}, "Action": [ "kms:DescribeKey", "kms:GenerateDataKey*", "kms:Encrypt", "kms:ReEncrypt*", "kms:Decrypt" ], "Resource": "*" }

In the preceding policy statement, arn:aws:iam::111122223333:role/EncryptionApp refers to the IAM role named EncryptionApp in AWS account 111122223333. Principals that can assume this role are allowed to perform the actions listed in the policy statement, which are the cryptographic actions for encrypting and decrypting data with a CMK.

Example Policy Statement 4

Copy
{ "Sid": "Allow attachment of persistent resources", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:role/EncryptionApp"}, "Action": [ "kms:ListGrants", "kms:CreateGrant", "kms:RevokeGrant" ], "Resource": "*", "Condition": {"Bool": {"kms:GrantIsForAWSResource": true}} }

In the preceding policy statement, arn:aws:iam::111122223333:role/EncryptionApp refers to the IAM role named EncryptionApp in AWS account 111122223333. Principals that can assume this role are allowed to perform the actions listed in the policy statement. These actions, when combined with the actions allowed in Example policy statement 3, are those necessary to delegate use of the CMK to most AWS services that integrate with AWS KMS, specifically the services that use grants. The Condition element ensures that the delegation is allowed only when the delegate is an AWS service that integrates with AWS KMS and uses grants for authorization.

To learn all the different ways you can specify a principal in a key policy document, see Specifying a Principal in the IAM User Guide.

To learn more about AWS KMS key policies, see Using Key Policies in AWS KMS.

Examining IAM Policies

In addition to the key policy and grants, you can also use IAM policies in combination with a CMK's key policy to allow access to a CMK. For more information about how IAM policies and key policies work together, see Understanding Policy Evaluation.

To determine which principals currently have access to a CMK through IAM policies, you can use the browser-based IAM Policy Simulator tool, or you can make requests to the IAM API.

Examining IAM Policies with the IAM Policy Simulator

The IAM Policy Simulator can help you learn which principals have access to a KMS CMK through an IAM policy.

To use the IAM Policy Simulator to determine access to a KMS CMK

  1. Sign in to the AWS Management Console and then open the IAM Policy Simulator at https://policysim.aws.amazon.com/.

  2. In the Users, Groups, and Roles pane, choose the user, group, or role whose policies you want to simulate.

  3. (Optional) Clear the check box next to any policies that you want to omit from the simulation. To simulate all policies, leave all policies selected.

  4. In the Policy Simulator pane, do the following:

    1. For Select service, choose Key Management Service.

    2. To simulate specific AWS KMS actions, for Select actions, choose the actions to simulate. To simulate all AWS KMS actions, choose Select All.

  5. (Optional) The Policy Simulator simulates access to all KMS CMKs by default. To simulate access to a specific KMS CMK, select Simulation Settings and then type the Amazon Resource Name (ARN) of the KMS CMK to simulate.

  6. Select Run Simulation.

You can view the results of the simulation in the Results section. Repeat steps 2 through 6 for every IAM user, group, and role in the AWS account.

Examining IAM Policies with the IAM API

You can use the IAM API to examine IAM policies programmatically. The following steps provide a general overview of how to do this:

  1. For each AWS account listed as a principal in the CMK's key policy (that is, each root account listed in this format: "Principal": {"AWS": "arn:aws:iam::111122223333:root"}), use the ListUsers and ListRoles operations in the IAM API to retrieve a list of every IAM user and role in the account.

  2. For each IAM user and role in the list, use the SimulatePrincipalPolicy operation in the IAM API, passing in the following parameters:

    • For PolicySourceArn, specify the Amazon Resource Name (ARN) of a user or role from your list. You can specify only one PolicySourceArn for each SimulatePrincipalPolicy API request, so you must call this API multiple times, once for each IAM user and role in your list.

    • For the ActionNames list, specify every AWS KMS API action to simulate. To simulate all AWS KMS API actions, use kms:*. To test individual AWS KMS API actions, precede each API action with "kms:", for example "kms:ListKeys". For a complete list of all AWS KMS API actions, see Actions in the AWS Key Management Service API Reference.

    • (Optional) To determine whether the IAM users or roles have access to specific KMS CMKs, use the ResourceArns parameter to specify a list of the Amazon Resource Names (ARNs) of the CMKs. To determine whether the IAM users or roles have access to any CMK, do not use the ResourceArns parameter.

IAM responds to each SimulatePrincipalPolicy API request with an evaluation decision: allowed, explicitDeny, or implicitDeny. For each response that contains an evaluation decision of allowed, the response will also contain the name of the specific AWS KMS API action that is allowed and, if applicable, the ARN of the CMK that was used in the evaluation.

Examining Grants

Grants are advanced mechanisms for specifying permissions that you or an AWS service integrated with AWS KMS can use to specify how and when a CMK can be used. Grants are attached to a CMK, and each grant contains the principal who receives permission to use the CMK and a list of operations that are allowed. Grants are an alternative to the key policy, and are useful for specific use cases. For more information, see Using Grants.

To retrieve a list of grants attached to a CMK, use the AWS KMS ListGrants API (or list-grants AWS CLI command). You can examine the grants for a CMK to determine who or what currently has access to use the CMK via those grants. For example, the following is a JSON representation of a grant that was obtained from the list-grants command in the AWS CLI.

Copy
{"Grants": [{ "Operations": ["Decrypt"], "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "Name": "0d8aa621-43ef-4657-b29c-3752c41dc132", "RetiringPrincipal": "arn:aws:iam::123456789012:root", "GranteePrincipal": "arn:aws:sts::111122223333:assumed-role/aws:ec2-infrastructure/i-5d476fab", "GrantId": "dc716f53c93acacf291b1540de3e5a232b76256c83b2ecb22cdefa26576a2d3e", "IssuingAccount": "arn:aws:iam::111122223333:root", "CreationDate": 1.444151834E9, "Constraints": {"EncryptionContextSubset": {"aws:ebs:id": "vol-5cccfb4e"}} }]}

To find out who or what has access to use the CMK, look for the "GranteePrincipal" element. In the preceding example, the grantee principal is an assumed role user associated with the EC2 instance i-5d476fab, which the EC2 infrastructure uses to attach the encrypted EBS volume vol-5cccfb4e to the instance. In this case, the EC2 infrastructure role has permission to use the CMK because you previously created an encrypted EBS volume protected by this CMK, and then attached the volume to an EC2 instance.

The following is another example of a JSON representation of a grant that was obtained from the list-grants command in the AWS CLI. In the following example, the grantee principal is another AWS account.

Copy
{"Grants": [{ "Operations": ["Encrypt"], "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "Name": "", "GranteePrincipal": "arn:aws:iam::444455556666:root", "GrantId": "f271e8328717f8bde5d03f4981f06a6b3fc18bcae2da12ac38bd9186e7925d11", "IssuingAccount": "arn:aws:iam::111122223333:root", "CreationDate": 1.444151269E9 }]}