Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Managing grants

Principals with the required permissions can view, use and delete (retire or revoke) grants. To refine permissions for creating and managing grants, Amazon 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.

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. Amazon KMS supports all of the following grant-related condition keys. For detailed information and examples, see Amazon KMS condition keys.

Viewing grants

To view the grant, use the ListGrants operation. You must specify the KMS key 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 Amazon Web Services account and Region with a particular retiring principal, use ListRetirableGrants. The responses include details about each grant.

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

$  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

The Amazon KMS API follows an eventual consistency model. When you create a grant, the grant might not be effective immediately. There might be a brief delay before the change is available throughout Amazon KMS. It typically takes less than a few seconds for the change to propagate throughout the system, but in some cases it can take several minutes. Once the change has fully propagated throughout the system, the grantee principal can use the permissions in the grant without specifying the grant token or any evidence of the grant. However, if a grant that is so new that it is not yet known to all of Amazon 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 Amazon KMS operation. You can submit a grant token to any Amazon KMS grant operation and you can submit multiple grant tokens in the same request.

The following example uses 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 is available throught Amazon KMS. (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. Both operations delete a grant, which eliminates the permissions the grant allows. The primary difference between these operations is how they are authorized.

The Amazon KMS API follows an eventual consistency model. When you create, retire, or revoke a grant, there might be a brief delay before the change is available throughout Amazon KMS. It typically takes less than a few seconds for the change to propagate throughout the system, but in some cases it can take several minutes. If you need to delete a new grant immediately, before it is available throughout Amazon KMS, use a grant token to retire the grant. You cannot use a grant token to revoke a grant.