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.
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 AWS 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 AWS SDK that automatically retries requests, use the optional Name parameter to prevent the creation of duplicate grants. If AWS 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 AWS KMS operations.
Do not include confidential or sensitive information in the grant name. It may appear in plain text in CloudTrail logs and other output.
$ 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 AWS SDK or CLI.
Using grant constraintsGrant 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.
ImportantDo not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
AWS 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.
Encryption context constraints are valid only in a grant for a symmetric encryption KMS key. Cryptographic operations with other KMS keys don't support an encryption context.
The encryption context constraint is ignored for DescribeKey and RetireGrant operations. DescribeKey and RetireGrant don't have an encryption context parameter, but you can include these operations in a grant that has an encryption context constraint.
You can use an encryption context constraint in a grant for the CreateGrant operation. The encryption context constraint requires that any grants created with the CreateGrant permission have an equally strict or stricter encryption context constraint.
AWS KMS supports the following encryption context grant constraints.
Use EncryptionContextEquals to specify the exact encryption context for permitted requests.
EncryptionContextEquals requires that the encryption context pairs in the request are an exact, case-sensitive match for the encryption context pairs in the grant constraint. The pairs can appear in any order, but the keys and values in each pair cannot vary.
For example, if the EncryptionContextEquals grant constraint requires the "Department": "IT" encryption context pair, the grant allows requests of the specified type only when the encryption context in the request is exactly "Department": "IT".
Use EncryptionContextSubset to require that requests include particular encryption context pairs.
EncryptionContextSubset requires that the request include all encryption context pairs in the grant constraint (an exact, case-sensitive match), but the request can also have additional encryption context pairs. The pairs can appear in any order, but the keys and values in each pair cannot vary.
For example, if the EncryptionContextSubset grant constraint requires the Department=IT encryption context pair, the grant allows requests of the specified type when the encryption context in the request is "Department": "IT", or includes "Department": "IT" along with other encryption context pairs, such as "Department": "IT","Purpose": "Test".
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=ITWhen 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=ITHowever, 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=TestAWS services often use encryption context constraints in the grants that give them permission to use KMS keys in your AWS account. For example, Amazon DynamoDB uses a grant like the following one to get permission to use the AWS 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 AWS account.
To get this output, run the ListGrants operation on the AWS 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"
}
]
}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.
The grantee principal can only create grants that allow some or all of the operations in the parent grant.
The grant constraints in the grants they create must be at least as strict as those in the parent grant.
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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4