Using grants

AWS KMS supports two resource-based access control mechanisms: key policies and grants. With grants you can programmatically delegate the use of KMS customer master keys (CMKs) to other AWS principals. You can use them to allow access, but not deny it. Because grants can be very specific, and are easy to create and revoke, they are often used to provide temporary permissions or more granular permissions.

You can also use key policies to allow other AWS principals to access a CMK, but key policies work best for relatively static permission assignments. Also, key policies use the standard permissions model for AWS policies in which users either have or do not have permission to perform an action with a resource. For example, users with the kms:PutKeyPolicy permission for a CMK can completely replace the key policy for a CMK with a different key policy of their choice. To enable more granular permissions management, use grants.

For code examples that demonstrate how to work with grants, see Working with grants.

Create a grant

To create a grant, call the CreateGrant operation. Specify a CMK, the grantee principal that the grant allows to use the CMK, and a list of allowed operations. The CreateGrant operation returns a grant ID that you can use to identify the grant in subsequent operations. To customize the grant, use optional Constraints parameters to define grant constraints.

For example, the following CreateGrant command creates a grant that allows exampleUser to call the Decrypt operation on the specified symmetric CMK. 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:user/exampleUser \
    --operations Decrypt \
    --retiring-principal arn:aws:iam::111122223333:role/adminRole \
    --constraints EncryptionContextSubset={Department=IT}

To view the grant, use the ListGrants operation.

$ 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": "abcde1237f76e4ba7987489ac329fbfba6ad343d6f7075dbd1ef191f0120514",
            "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"
            ]
        }
    ]
}

Grants can be revoked (deleted) by any user who has the kms:RevokeGrant permission on the CMK.

Grants can be retired by any of the following principals:

Grants for symmetric and asymmetric CMKs

You can create a grant that controls access to a symmetric CMK or an asymmetric CMK. However, you cannot create a grant that allows a principal to perform an operation that is not supported by the CMK. If you try, AWS KMS returns a ValidationError exception.

Grant constraints

Grant constraints set conditions on the permissions that the grantee principal can perform. AWS KMS supports two supported constraints, both of which involve the encryption context in a request for a cryptographic operation. These grant constraints are not applied to operations that do not support an encryption context, such as cryptographic operations with asymmetric CMKs and management operations, such as DescribeKey or RetireGrant.

For example, consider a grant that allows GenerateDataKey and Decrypt operations. It includes an EncryptionContextSubset constraint with the following values.

{"Department":"Finance","Classification":"Public"}

In this example, any of the following encryption context values would satisfy the EncryptionContextSubset constraint.

However, the following encryption context values would not satisfy the constraint, either because they are incomplete or do not include an exact, case-sensitive match of the specified pairs.

Authorizing CreateGrant in a key policy

When you create a key policy to control access to the CreateGrant operation, you can use one or more policy conditions to limit the permission. AWS KMS supports all of the following grant-related condition keys. For detailed information about these condition keys, see AWS KMS condition keys.

Granting CreateGrant permission

When a grant includes permission to call the CreateGrant operation, the grant only allows the grantee principal to create grants that are equally restrictive or more restrictive.

For example, consider a grant that allows the grantee principal to call the GenerateDataKey, Decrypt, and CreateGrant operations. The grantee principal can use this permission to create a grant that includes any subset of the operations specified in the parent grant, such as GenerateDataKey and Decrypt. But it cannot include other operations, such as ScheduleKeyDeletion or ReEncrypt.

Also, the grant constraints in child grants must be equally 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.