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

Creating grants

Before creating a grant, learn about the options for customizing your grant. You can use grant constraints to limit the permissions in the grant. Also, learn about granting CreateGrant permission. Principals who get permission to create grants from a grant are limited in the grants that they can create.

Creating a grant

To create a grant, call the CreateGrant operation. Specify a KMS key, a grantee principal, and a list of allowed grant operations. You can also designate an optional retiring principal. To customize the grant, use optional Constraints parameters to define grant constraints.

When you create, retire, or revoke a grant, there might be a brief delay, usually less than five minutes, before the change is available throughout Amazon KMS. For more information, see Eventual consistency (for grants).

For example, the following CreateGrant command creates a grant that allows users who are authorized to assume the keyUserRole role to call the Decrypt operation on the specified symmetric KMS key. The grant uses the RetiringPrincipal parameter to designate a principal that can retire the grant. It also includes a grant constraint that allows the permission only when the encryption context in the request includes "Department": "IT".

$  aws kms create-grant \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --grantee-principal arn:aws:iam::111122223333:role/keyUserRole \
    --operations Decrypt \
    --retiring-principal arn:aws:iam::111122223333:role/adminRole \
    --constraints EncryptionContextSubset={Department=IT}

If your code retries the CreateGrant operation, or uses an Amazon SDK that automatically retries requests, use the optional Name parameter to prevent the creation of duplicate grants. If Amazon KMS gets a CreateGrant request for a grant with the same properties as an existing grant, including the name, it recognizes the request as a retry, and does not create a new grant. You cannot use the Name value to identify the grant in any Amazon KMS operations.

$ aws kms create-grant \
    --name IT-1234abcd-keyUserRole-decrypt \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --grantee-principal arn:aws:iam::111122223333:role/keyUserRole \
    --operations Decrypt \
    --retiring-principal arn:aws:iam::111122223333:role/adminRole \
    --constraints EncryptionContextSubset={Department=IT}

For code examples that demonstrate how to create grants in several programming languages, see Use CreateGrant with an Amazon SDK or CLI.

Using grant constraints

Grant constraints set conditions on the permissions that the grant gives to the grantee principal. Grant constraints take the place of condition keys in a key policy or IAM policy. Each grant constraint value can include up to 8 encryption context pairs. The encryption context value in each grant constraint cannot exceed 384 characters.

Amazon KMS supports two grant constraints, EncryptionContextEquals and EncryptionContextSubset, both of which establish requirements for the encryption context in a request for a cryptographic operation.

The encryption context grant constraints are designed to be used with grant operations that have an encryption context parameter.

Amazon KMS supports the following encryption context grant constraints.

To specify an encryption context constraint in a grant for a symmetric encryption KMS key, use the Constraints parameter in the CreateGrant operation. The grant that this command creates gives users who are authorized to assume the keyUserRole role permission to call the Decrypt operation. But that permission is effective only when the encryption context in the Decrypt request is a "Department": "IT" encryption context pair.

$ aws kms create-grant \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --grantee-principal arn:aws:iam::111122223333:role/keyUserRole \
    --operations Decrypt \
    --retiring-principal arn:aws:iam::111122223333:role/adminRole \
    --constraints EncryptionContextEquals={Department=IT}

The resulting grant looks like the following one. Notice that the permission granted to the keyUserRole role is effective only when the Decrypt request uses the same encryption context pair specified in the grant constraint. To find the grants on a KMS key, use the ListGrants operation.

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

To satisfy the EncryptionContextEquals grant constraint, the encryption context in the request for the Decrypt operation must be a "Department": "IT" pair. A request like the following from the grantee principal would satisfy the EncryptionContextEquals grant constraint.

$ aws kms decrypt \
    --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab\
    --ciphertext-blob fileb://encrypted_msg \
    --encryption-context Department=IT

When the grant constraint is EncryptionContextSubset, the encryption context pairs in the request must include the encryption context pairs in the grant constraint, but the request can also include other encryption context pairs. The following grant constraint requires that one of encryption context pairs in the request is "Deparment": "IT".

"Constraints": {
   "EncryptionContextSubset": {
       "Department": "IT"
   }
}

The following request from the grantee principal would satisfy both of the EncryptionContextEqual and EncryptionContextSubset grant constraints in this example.

$ aws kms decrypt \
    --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --ciphertext-blob fileb://encrypted_msg \
    --encryption-context Department=IT

However, a request like the following from the grantee principal would satisfy the EncryptionContextSubset grant constraint, but it would fail the EncryptionContextEquals grant constraint.

$ aws kms decrypt \
    --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --ciphertext-blob fileb://encrypted_msg \
    --encryption-context Department=IT,Purpose=Test

Amazon services often use encryption context constraints in the grants that give them permission to use KMS keys in your Amazon Web Services account. For example, Amazon DynamoDB uses a grant like the following one to get permission to use the Amazon managed key for DynamoDB in your account. The EncryptionContextSubset grant constraint in this grant makes the permissions in the grant effective only when the encryption context in the request includes "subscriberID": "111122223333" and "tableName": "Services" pairs. This grant constraint means that the grant allows DynamoDB to use the specified KMS key only for a particular table in your Amazon Web Services account.

To get this output, run the ListGrants operation on the Amazon managed key for DynamoDB in your account.

$ aws kms list-grants --key-id 0987dcba-09fe-87dc-65ba-ab0987654321

{
    "Grants": [
        {
            "Operations": [
                "Decrypt",
                "Encrypt",
                "GenerateDataKey",
                "ReEncryptFrom",
                "ReEncryptTo",
                "RetireGrant",
                "DescribeKey"
            ],
            "IssuingAccount": "arn:aws:iam::111122223333:root",
            "Constraints": {
                "EncryptionContextSubset": {
                    "aws:dynamodb:tableName": "Services",
                    "aws:dynamodb:subscriberId": "111122223333"
                }
            },
            "CreationDate": 1518567315.0,
            "KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
            "GranteePrincipal": "dynamodb.us-west-2.amazonaws.com",
            "RetiringPrincipal": "dynamodb.us-west-2.amazonaws.com",
            "Name": "8276b9a6-6cf0-46f1-b2f0-7993a7f8c89a",
            "GrantId": "1667b97d27cf748cf05b487217dd4179526c949d14fb3903858e25193253fe59"
        }
    ]
}

Granting CreateGrant permission

A grant can include permission to call the CreateGrant operation. But when a grantee principal gets permission to call CreateGrant from a grant, rather than from a policy, that permission is limited.

These limitations don't apply to principals who get CreateGrant permission from a policy, although their permissions can be limited by policy conditions.

For example, consider a grant that allows the grantee principal to call the GenerateDataKey, Decrypt, and CreateGrant operations. We call a grant that allow CreateGrant permission a parent grant.

# The original grant in a ListGrants response.
{
    "Grants": [
        {
            "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "CreationDate": 1572216195.0,
            "GrantId": "abcde1237f76e4ba7987489ac329fbfba6ad343d6f7075dbd1ef191f0120514a",
            "Operations": [
                "GenerateDataKey",
                "Decrypt",
                "CreateGrant
            ]
            "RetiringPrincipal": "arn:aws:iam::111122223333:role/adminRole",
            "Name": "",
            "IssuingAccount": "arn:aws:iam::111122223333:root",
            "GranteePrincipal": "arn:aws:iam::111122223333:role/keyUserRole",
            "Constraints": {
                "EncryptionContextSubset": {
                    "Department": "IT"
                }
            },
        }
    ]
}

The grantee principal, exampleUser, can use this permission to create a grant that includes any subset of the operations specified in the original grant, such as CreateGrant and Decrypt. The child grant cannot include other operations, such as ScheduleKeyDeletion or ReEncrypt.

Also, the grant constraints in child grants must be as restrictive or more restrictive than those in the parent grant. For example, the child grant can add pairs to an EncryptionContextSubset constraint in the parent grant, but it cannot remove them. The child grant can change an EncryptionContextSubset constraint to an EncryptionContextEquals constraint, but not the reverse.

IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see Security best practices in IAM in the IAM User Guide.

For example, the grantee principal can use the CreateGrant permission that it got from the parent grant to create the following child grant. The operations in the child grant are a subset of the operations in the parent grant and the grant constraints are more restrictive.

# The child grant in a ListGrants response.
{
    "Grants": [
        {
            "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "CreationDate": 1572249600.0,
            "GrantId": "fedcba9999c1e2e9876abcde6e9d6c9b6a1987650000abcee009abcdef40183f",
            "Operations": [
                "CreateGrant"
                "Decrypt"
            ]
            "RetiringPrincipal": "arn:aws:iam::111122223333:user/exampleUser",
            "Name": "",
            "IssuingAccount": "arn:aws:iam::111122223333:root",
            "GranteePrincipal": "arn:aws:iam::111122223333:user/anotherUser",
            "Constraints": {
                "EncryptionContextEquals": {
                    "Department": "IT"
                }
            },
        }
    ]
}

The grantee principal in the child grant, anotherUser, can use their CreateGrant permission to create grants. However, the grants that anotherUser creates must include the operations in its parent grant or a subset, and the grant constraints must be the same or stricter.