Managing grants - AWS Key Management Service

Managing grants

Principals with the required permissions can view, use and delete (retire or revoke) grants. To refine permissions for creating and managing grants, AWS KMS supports several policy conditions that you can use in key policies and IAM policies.

Controlling access to grants

You can control access to the operations that create and manage grants in key policies, IAM policies, and in grants. Principals who get CreateGrant permission from a grant have more limited grant permissions.

API operation Key policy or IAM policy Grant
CreateGrant
ListGrants -
ListRetirableGrants -
Retire Grants (Limited. See Retiring and revoking grants)
RevokeGrant -

When you use a key policy or IAM policy to control access to operations that create and manage grants, you can use one or more of the following policy conditions to limit the permission. AWS KMS supports all of the following grant-related condition keys. For detailed information and examples, see AWS KMS condition keys.

kms:GrantConstraintType

Allows principals to create a grant only when the grant includes the specified grant constraint.

kms:GrantIsForAWSResource

Allows principals to call CreateGrant, ListGrants, or RevokeGrant only when an AWS service that is integrated with AWS KMS sends the request on the principal's behalf.

kms:GrantOperations

Allows principals to create a grant, but limits the grant to the specified operations.

kms:GranteePrincipal

Allows principals to create a grant only for the specified grantee principal.

kms:RetiringPrincipal

Allows principals to create a grant only when the grant specifies a particular retiring principal.

Viewing grants

To view the grant, use the ListGrants operation. You must specify the CMK to which the grants apply. You can also filter the grant list by grant ID or grantee principal. For more examples, see Viewing a grant.

To view all grants in the AWS account and Region with a particular retiring principal, use ListRetirableGrants. The responses include details about each grant.

Note

The GranteePrincipal field in the ListGrants response usually contains the grantee principal of the grant. However, when the grantee principal in the grant is an AWS service, the GranteePrincipal field contains the service principal, which might represent several different grantee principals.

For example, the following command lists all of the grants for a CMK.

$ aws kms list-grants --key-id 1234abcd-12ab-34cd-56ef-1234567890ab { "Grants": [ { "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "CreationDate": 1572216195.0, "GrantId": "abcde1237f76e4ba7987489ac329fbfba6ad343d6f7075dbd1ef191f0120514a", "Constraints": { "EncryptionContextSubset": { "Department": "IT" } }, "RetiringPrincipal": "arn:aws:iam::111122223333:role/adminRole", "Name": "", "IssuingAccount": "arn:aws:iam::111122223333:root", "GranteePrincipal": "arn:aws:iam::111122223333:user/exampleUser", "Operations": [ "Decrypt" ] } ] }

Using a grant token

When you create a grant, the grant might not be effective immediately. There's likely to be a brief interval, less than five minutes, until the grant achieves eventual consistency, that is, before the new grant is available throughout AWS KMS. Once the grant has achieved eventual consistency, the grantee principal can use the permissions in the grant without specifying the grant token or any evidence the grant. However, if grant that is so new that it is not yet known to all of AWS KMS, the request might fail with an AccessDeniedException error.

To use the permissions in a new grant immediately, use the grant token for the grant. Save the grant token that the CreateGrant operation returns. Then submit the grant token in the request for the AWS KMS operation. You can submit a grant token to any AWS KMS grant operation and you can submit multiple grant tokens in the same request.

The following example use the CreateGrant operation to create a grant that allows the GenerateDataKey and Decrypt operations. It saves the grant token that CreateGrant returns in the token variable. Then, in a call to the GenerateDataKey operation, it uses the grant token in the token variable.

# Create a grant; save the grant token $ token=$(aws kms create-grant \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --grantee-principal arn:aws:iam::111122223333:user/appUser \ --retiring-principal arn:aws:iam::111122223333:user/acctAdmin \ --operations GenerateDataKey Decrypt \ --query GrantToken \ --output text) # Use the grant token in a request $ aws kms generate-data-key \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ –-key-spec AES_256 \ --grant-tokens $token

Principals with permission can also use a grant token to retire a new grant even before the grant achieves eventual consistency. (The RevokeGrant operation doesn't accept a grant token.) For details, see Retiring and revoking grants.

# Retire the grant $ aws kms retire-grant --grant-token $token

Retiring and revoking grants

To delete a grant, retire or revoke it.

The RetireGrant and RevokeGrant operations are very similar to each other. They both delete a grant, which eliminates the permissions that the grant allows. The difference is how they are authorized.

RevokeGrant

Like most AWS KMS operations, access to the RevokeGrant operation is controlled through key policies and IAM policies. The RevokeGrant API can be called by any principal with kms:RevokeGrant permission. This permission is included in the standard permissions given to key administrators. Typically, administrators revoke a grant to deny permissions the grant allows.

RetireGrant

The grant determines who can retire it. This design allows you to control the lifecycle of a grant without changing key policies or IAM policies. Typically, you retire a grant when you are done using its permissions.

A grant can be retired by an optional retiring principal specified in the grant. The grantee principal can also retire the grant, but only if they are also a retiring principal or the grant includes the RetireGrant operation. As a backup, the AWS account (root user) in which the grant was created can retire the grant.

There is a kms:RetireGrant permission that can be used in key policies and IAM policies, but it has limited utility. Principals specified in the grant can retire a grant without the kms:RetireGrant permission. The kms:RetireGrant permission alone does not allow principals to retire a grant.

  • To deny permission to retire a grant, you can use a Deny action with the kms:RetireGrant permission.

  • The AWS account (root user) that owns the CMK can use the kms:RetireGrant permission to delegate permission to retire the grant.

  • If the retiring principal is the root user of a different AWS account, administrators in the other account can use kms:RetireGrant to delegate permission to retire the grant to an IAM user in that account.

You can use a grant token to retire a grant, but not to revoke it. If you need to delete a new grant immediately, before it is available throughout AWS KMS, you must retire it.

When you create, retire, or revoke a grant, there might be a brief delay, usually less than five minutes, until the operation achieves eventual consistency. You can use a grant token to retire a grant immediately after it is created. You cannot use a grant token to revoke a grant.