Using Grants

AWS KMS supports two resource-based access control mechanisms: key policies and grants. Grants enable you to programmatically delegate the use of KMS customer master keys (CMKs) to other AWS principals. You can also use key policies to allow other principals to access a CMK, but key policies work best for relatively static assignments of permissions.

Key policy changes follow the same permissions model used for policy editing elsewhere in AWS. That is, users either have permission to change the key policy or they do not. 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.

You call the CreateGrant API operation to create a grant. You pass the identifier of the CMK for which the grant is to be created, the grantee principal being given permission to use the CMK, and a list of operations to be allowed. The CreateGrant operation returns a grant ID that you can use to identify the grant in subsequent operations. To further customize the grant permissions, you can also pass optional parameters that define grant constraints. After the grant has been created, the principal identified in the grant can execute the permitted operations, subject to the defined constraints, for as long as the grant is active. Grants can be explicitly revoked by a user who has the kms:RevokeGrant permission on the CMK, or they can be retired by the principal designated as the retiring principal for the grant.

There are two supported grant constraints: EncryptionContextEquals and EncryptionContextSubset. EncryptionContextEquals specifies that the grant applies only when the exact specified encryption context is present in the request. EncryptionContextSubset specifies that the grant applies as long as all the entries in the EncryptionContextSubset constraint are matched by the request. In this case, the request can contain additional encryption context entries. For example, a grant that allows the encrypt and decrypt operations with an EncryptionContextSubset constraint of {"Department":"Finance","Classification":"Public"} allows encryption and decryption when the request contains an encryption context of either {"Department":"Finance","Classification":"Public"} or {"Department":"Finance","Classification":"Public","Customer":"12345"}, but not when the request contains an encryption context of {"Department":"Finance"}.

When the grant includes CreateGrant as an allowed operation, the grant only allows creation of equally or more restrictive grants. That is, the grant operations passed with a subsequent CreateGrant API request can include any subset of the currently-allowed grant operations, and the grant constraints can be the same or more restrictive (fields can be added to an EncryptionContextSubset constraint, or an EncryptionContextSubset constraint can be turned into an EncryptionContextEquals constraint).

For Java code samples that demonstrate how to work with grants, see Working with Grants.