# Grants in AWS KMS
A *grant* is a policy instrument that allows [AWS principals](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) to use KMS keys in cryptographic operations. It also can let them view a KMS key (`DescribeKey`) and create and manage grants. When authorizing access to a KMS key, grants are considered along with [key policies](key-policies.md) and [IAM policies](iam-policies.md). Grants are often used for temporary permissions because you can create one, use its permissions, and delete it without changing your key policies or IAM policies.
Grants are commonly used by AWS services that integrate with AWS KMS to encrypt your data at rest. The service creates a grant on behalf of a user in the account, uses its permissions, and retires the grant as soon as its task is complete. For details about how AWS services, use grants, see the *Encryption at rest* topic in the service's user guide or developer guide.
Grants are a very flexible and useful access control mechanism. When you create a grant for a KMS key, the grant allows the grantee principal to call the specified grant operations on the KMS key provided that all conditions specified in the grant are met.
+ Each grant allows access to exactly one KMS key. You can create a grant for a KMS key in a different AWS account.
+ A grant can allow access to a KMS key, but not deny access.
+ Each grant has one [grantee principal](#terms-grantee-principal). The grantee principal can represent one or more identities in the same AWS account as the KMS key or in a different account.
+ A grant can only allow [grant operations](#terms-grant-operations). The grant operations must be supported by the KMS key in the grant. If you specify an unsupported operation, the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) request fails with a `ValidationError` exception.
+ The grantee principal can use the permissions that the grant gives them without specifying the grant, just as they would if the permissions came from a key policy or IAM policy. However, because the AWS KMS API follows an [eventual consistency](#terms-eventual-consistency) model, when you create, retire, or revoke a grant, there might be a brief delay, before the change is available throughout AWS KMS. To use the permissions in a grant immediately, [use a grant token](using-grant-token.md).
+ An authorized principal can delete the grant ([retire](#terms-retire-grant) or [revoke](#terms-revoke-grant) it). Deleting a grant eliminates all permissions that the grant allowed. You do not have to figure out which policies to add or remove to undo the grant.
+ AWS KMS limits the number of grants on each KMS key. For details, see [Grants per KMS key: 50,000](resource-limits.md#grants-per-key).
Be cautious when creating grants and when giving others permission to create grants. Permission to create grants has security implications, much like allowing the [kms:PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) permission to set policies.
+ Users with permission to create grants for a KMS key (`kms:CreateGrant`) can use a grant to allow users and roles, including AWS services, to use the KMS key. The principals can be identities in your own AWS account or identities in a different account or organization.
+ Grants can allow only a subset of AWS KMS operations. You can use grants to allow principals to view the KMS key, use it in cryptographic operations, and create and retire grants. For details, see [Grant operations](#terms-grant-operations). You can also use [grant constraints](create-grant-overview.md#grant-constraints) to limit the permissions in a grant for a symmetric encryption key.
+ Principals can get permission to create grants from a key policy or IAM policy. Principals who get `kms:CreateGrant` permission from a policy can create grants for any [grant operation](#terms-grant-operations) on the KMS key. These principals are not required to have the permission that they are granting on the key. When you allow `kms:CreateGrant` permission in a policy, you can use [policy conditions](grant-authorization.md) to limit this permission.
+ Principals can also get permission to create grants from a grant. These principals can only delegate the permissions that they were granted, even if they have other permissions from a policy. For details, see [Granting CreateGrant permission](create-grant-overview.md#grant-creategrant).
## Grant concepts
To use grants effectively, you'll need to understand the terms and concepts that AWS KMS uses.
**Grant constraint**
A condition that limits the permissions in the grant. Currently, AWS KMS supports grant constraints based on the [encryption context](encrypt_context.md) in the request for a cryptographic operation. For details, see [Using grant constraints](create-grant-overview.md#grant-constraints).
**Grant ID**
The unique identifier of a grant for a KMS key. You can use a grant ID, along with a [key identifier](concepts.md#key-id), to identify a grant in a [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) or [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html) request.
**Grant operations**
The AWS KMS operations that you can allow in a grant. If you specify other operations, the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) request fails with a `ValidationError` exception. These are also the operations that accept a [grant token](#grant_token). For detailed information about these permissions, see the [AWS KMS permissions](kms-api-permissions-reference.md).
These grant operations actually represent permission to use the operation. Therefore, for the `ReEncrypt` operation, you can specify `ReEncryptFrom`, `ReEncryptTo`, or both `ReEncrypt*`.
The grant operations are:
+ Cryptographic operations
+ [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
+ [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html)
+ [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html)
+ [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)
+ [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html)
+ [GenerateDataKeyPairWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPairWithoutPlaintext.html)
+ [GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html)
+ [GenerateMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateMac.html)
+ [ReEncryptFrom](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html)
+ [ReEncryptTo](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html)
+ [Sign](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html)
+ [Verify](https://docs.aws.amazon.com/kms/latest/APIReference/API_Verify.html)
+ [VerifyMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html)
+ Other operations
+ [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)
+ [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html)
+ [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html)
+ [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html)
The grant operations that you allow must be supported by the KMS key in the grant. If you specify an unsupported operation, the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) request fails with a `ValidationError` exception. For example, grants for symmetric encryption KMS keys cannot allow the [Sign](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html), [Verify](https://docs.aws.amazon.com/kms/latest/APIReference/API_Verify.html), [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateMac.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateMac.html) or [https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html) operations. Grants for asymmetric KMS keys cannot allow any operations that generate data keys or data key pairs.
**Grant token**
The AWS KMS API follows an [eventual consistency](#terms-eventual-consistency) model. When you create a grant, there might be a brief delay before the change is available throughout AWS 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 try to use a grant before it fully propagates through the system, you might get an access denied error. A grant token lets you refer to the grant and use the grant permissions immediately.
A *grant token* is a unique, nonsecret, variable-length, base64-encoded string that represents a grant. You can use the grant token to identify the grant in any [grant operation](#terms-grant-operations). However, because the token value is a hash digest, it doesn't reveal any details about the grant.
A grant token is designed to be used only until the grant has fully propagated throughout AWS KMS. After that, the [grantee principal](#terms-grantee-principal) can use the permission in the grant without providing a grant token or any other evidence of the grant. You can use a grant token at any time, but once the grant is eventually consistent, AWS KMS uses the grant to determine permissions, not the grant token.
For example, the following command calls the [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) operation. It uses a grant token to represent the grant that gives the caller (the grantee principal) permission to call `GenerateDataKey` on the specified KMS key.
```
$ aws kms generate-data-key \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--key-spec AES_256 \
--grant-token $token
```
You can also use a grant token to identify a grant in operations that manage grants. For example, the [retiring principal](#terms-retiring-principal) can use a grant token in a call to the [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) operation.
```
$ aws kms retire-grant \
--grant-token $token
```
`CreateGrant` is the only operation that returns a grant token. You cannot get a grant token from any other AWS KMS operation or from the [CloudTrail log event](ct-creategrant.md) for the CreateGrant operation. The [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) and [ListRetirableGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListRetirableGrants.html) operations return the [grant ID](#terms-grant-id), but not a grant token.
For details, see [Using a grant token](using-grant-token.md).
**Grantee principal**
The identities that get the permissions specified in the grant. Each grant has one grantee principal, but the grantee principal can represent multiple identities.
The grantee principal can be any AWS principal, including an AWS account (root), an [IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html), an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html), a [federated role or user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html), or an assumed role user. The grantee principal can be in the same account as the KMS key or a different account. However, the grantee principal cannot be a [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services), an [IAM group](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html), or an [AWS organization](https://docs.aws.amazon.com/organizations/latest/userguide/).
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
**Retire (a grant)**
Terminates a grant. You retire a grant when you finish using the permissions.
Revoking and retiring a grant both delete the grant. But retiring is done by a principal specified in the grant. Revoking is typically done by a key administrator. For details, see [Retiring and revoking grants](grant-delete.md).
**Retiring principal**
A principal who can [retire a grant](#terms-retire-grant). You can specify a retiring principal in a grant, but it is not required. The retiring principal can be any AWS principal, including AWS accounts, IAM users, IAM roles, federated users, and assumed role users. The retiring principal can be in the same account as the KMS key or a different account.
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
In addition to retiring principal specified in the grant, a grant can be retired by the AWS account in which the grant was created. If the grant allows the `RetireGrant` operation, the [grantee principal](#terms-grantee-principal) can retire the grant. Also, the AWS account or an AWS account that is the retiring principal can delegate the permission to retire a grant to an IAM principal in the same AWS account. For details, see [Retiring and revoking grants](grant-delete.md).
**Revoke (a grant)**
Terminates a grant. You revoke a grant to actively deny the permissions that the grant allows.
Revoking and retiring a grant both delete the grant. But retiring is done by a principal specified in the grant. Revoking is typically done by a key administrator. For details, see [Retiring and revoking grants](grant-delete.md).
**Eventual consistency (for grants)**
The AWS KMS API follows an [eventual consistency](https://en.wikipedia.org/wiki/Eventual_consistency) model. When you create, retire, or revoke a grant, there might be a brief delay before the change is available throughout AWS 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.
You might become aware of this brief delay if you get unexpected errors. For example, If you try to manage a new grant or use the permissions in a new grant before the grant is known throughout AWS KMS, you might get an access denied error. If you retire or revoke a grant, the grantee principal might still be able to use its permissions for a brief period until the grant is fully deleted. The typical strategy is to retry the request, and some AWS SDKs include automatic backoff and retry logic.
AWS KMS has features to mitigate this brief delay.
+ To use the permissions in a new grant immediately, use a [grant token](using-grant-token.md). You can use a grant token to refer to a grant in any [grant operation](#terms-grant-operations). For instructions, see [Using a grant token](using-grant-token.md).
+ The [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation has a `Name` parameter that prevents retry operations from creating duplicate grants.
Grant tokens supersede the validity of the grant until all endpoints in the service have been updated with the new grant state. In most cases, eventual consistency will be achieved within five minutes.
For more information, see [AWS KMS eventual consistency](accessing-kms.md#programming-eventual-consistency).
# Best practices for AWS KMS grants
AWS KMS recommends the following best practices when creating, using, and managing grants.
+ Limit the permissions in the grant to those that the grantee principal requires. Use the principle of [least privileged access](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
+ Use a specific grantee principal, such as an IAM role, and give the grantee principal permission to use only the API operations that they require.
+ Use the encryption context [grant constraints](grants.md#terms-grant-constraint) to ensure that callers are using the KMS key for the intended purpose. For details about how to use the encryption context in a request to secure your data, see [How to Protect the Integrity of Your Encrypted Data by Using AWS Key Management Service and EncryptionContext](https://aws.amazon.com/blogs/security/how-to-protect-the-integrity-of-your-encrypted-data-by-using-aws-key-management-service-and-encryptioncontext/) in the *AWS Security Blog*.
**Tip**
Use the [EncryptionContextEqual](create-grant-overview.md#grant-constraints) grant constraint whenever possible. The [EncryptionContextSubset](create-grant-overview.md#grant-constraints) grant constraint is more difficult to use correctly. If you need to use it, read the documentation carefully and test the grant constraint to make sure it works as intended.
+ Delete duplicate grants. Duplicate grants have the same key ARN, API actions, grantee principal, encryption context, and name. If you retire or revoke the original grant but leave the duplicates, the leftover duplicate grants constitute unintended escalations of privilege. To avoid duplicating grants when retrying a `CreateGrant` request, use the [`Name` parameter](create-grant-overview.md#grant-create). To detect duplicate grants, use the [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) operation. If you accidentally create a duplicate grant, retire or revoke it as soon as possible.
**Note**
Grants for [AWS managed keys](concepts.md#aws-managed-key) might look like duplicates but have different grantee principals.
The `GranteePrincipal` field in the `ListGrants` response usually contains the grantee principal of the grant. However, when the grantee principal in the grant is an AWS service, the `GranteePrincipal` field contains the [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services), which might represent several different grantee principals.
+ Remember that grants do not automatically expire. [Retire or revoke the grant](grant-delete.md) as soon as the permission is no longer needed. Grants that are not deleted might create a security risk for encrypted resources.
# 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](create-grant-overview.md#grant-creategrant).
| API operation | Key policy or IAM policy | Grant |
| --- | --- | --- |
| CreateGrant | ✓ | ✓ |
| ListGrants | ✓ | - |
| ListRetirableGrants | ✓ | - |
| Retire Grants | (Limited. See [Retiring and revoking grants](grant-delete.md)) | ✓ |
| RevokeGrant | ✓ | - |
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. AWS KMS supports all of the following grant-related condition keys. For detailed information and examples, see [AWS KMS condition keys](conditions-kms.md).
[kms:GrantConstraintType](conditions-kms.md#conditions-kms-grant-constraint-type)
Allows principals to create a grant only when the grant includes the specified [grant constraint](create-grant-overview.md#grant-constraints).
[kms:GrantIsForAWSResource](conditions-kms.md#conditions-kms-grant-is-for-aws-resource)
Allows principals to call `CreateGrant`, `ListGrants`, or `RevokeGrant` only when [an AWS service that is integrated with AWS KMS](https://aws.amazon.com/kms/features/#AWS_Service_Integration) sends the request on the principal's behalf.
[kms:GrantOperations](conditions-kms.md#conditions-kms-grant-operations)
Allows principals to create a grant, but limits the grant to the specified operations.
[kms:GranteePrincipal](conditions-kms.md#conditions-kms-grantee-principal)
Allows principals to create a grant only for the specified [grantee principal](grants.md#terms-grantee-principal).
[kms:RetiringPrincipal](conditions-kms.md#conditions-kms-retiring-principal)
Allows principals to create a grant only when the grant specifies a particular [retiring principal](grants.md#terms-retiring-principal).
# 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.
**Topics**
+ [
## Creating a grant
](#grant-create)
+ [
## Granting CreateGrant permission
](#grant-creategrant)
## Creating a grant
To create a grant, call the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation. Specify a KMS key, a [grantee principal](grants.md#terms-grantee-principal), and a list of allowed [grant operations](grants.md#terms-grant-operations). You can also designate an optional [retiring principal](grants.md#terms-retiring-principal). To customize the grant, use optional `Constraints` parameters to define [grant constraints](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html).
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)](grants.md#terms-eventual-consistency).
For example, the following `CreateGrant` command creates a grant that allows users who are authorized to assume the `keyUserRole` role to call the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation on the specified [symmetric KMS key](symm-asymm-choose-key-spec.md#symmetric-cmks). 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](encrypt_context.md) 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](https://docs.aws.amazon.com/general/latest/gr/api-retries.html), use the optional [Name](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html#KMS-CreateGrant-request-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.
**Important**
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](example_kms_CreateGrant_section.md).
### Using grant constraints
[Grant constraints](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html) set conditions on the permissions that the grant gives to the grantee principal. Grant constraints take the place of [condition keys](policy-conditions.md) in a [key policy](key-policies.md) or [IAM policy](iam-policies.md). Each grant constraint value can include up to 8 encryption context pairs. The encryption context value in each grant constraint cannot exceed 384 characters.
**Important**
Do 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](encrypt_context.md) in a request for a cryptographic operation.
The encryption context grant constraints are designed to be used with [grant operations](grants.md#terms-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.
**EncryptionContextEquals**
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"`.
**EncryptionContextSubset**
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](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation. The grant that this command creates gives users who are authorized to assume the `keyUserRole` role permission to call the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) 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
```
AWS 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](concepts.md#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](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) 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"
}
]
}
```
## Granting CreateGrant permission
A grant can include permission to call the `CreateGrant` operation. But when a [grantee principal](grants.md#terms-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](#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](grant-authorization.md).
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](https://docs.aws.amazon.com/kms/latest/APIReference/API_GrantConstraints.html) 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) 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.
# Viewing grants
To view the grant, use the [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) 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 [Use `ListGrants` with an AWS SDK or CLI](example_kms_ListGrants_section.md).
To view all grants in the AWS account and Region with a particular [retiring principal](grants.md#terms-retiring-principal), use [ListRetirableGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListRetirableGrants.html). The responses include details about each grant.
**Note**
The `GranteePrincipal` field in the `ListGrants` response usually contains the grantee principal of the grant. However, when the grantee principal in the grant is an AWS service, the `GranteePrincipal` field contains the [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services), which might represent several different grantee principals.
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 AWS KMS API follows an [eventual consistency](grants.md#terms-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 AWS 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 AWS KMS, the request might fail with an `AccessDeniedException` error.
To use the permissions in a new grant immediately, use the [grant token](grants.md#grant_token) for the grant. Save the grant token that the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation returns. Then submit the grant token in the request for the AWS KMS operation. You can submit a grant token to any AWS KMS [grant operation](grants.md#terms-grant-operations) 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) and [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) 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 throughout AWS KMS. (The `RevokeGrant` operation doesn't accept a grant token.) For details, see [Retiring and revoking grants](grant-delete.md).
```
# Retire the grant
$ aws kms retire-grant --grant-token $token
```
# Retiring and revoking grants
To delete a grant, retire or revoke it.
The [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) and [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html) 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.
**RevokeGrant**
Like most AWS KMS operations, access to the `RevokeGrant` operation is controlled through [key policies](key-policies.md) and [IAM policies](iam-policies.md). The [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html) API can be called by any principal with `kms:RevokeGrant` permission. This permission is included in the standard permissions given to key administrators. Typically, administrators revoke a grant to deny permissions the grant allows.
**RetireGrant**
The grant determines who can retire it. This design allows you to control the lifecycle of a grant without changing key policies or IAM policies. Typically, you retire a grant when you are done using its permissions.
A grant can be retired by an optional [retiring principal](grants.md#terms-retiring-principal) specified in the grant. The [grantee principal](grants.md#terms-grantee-principal) can also retire the grant, but only if they are also a retiring principal or the grant includes the `RetireGrant` operation. As a backup, the AWS account in which the grant was created can retire the grant.
There is a `kms:RetireGrant` permission that can be used in IAM policies, but it has limited utility. Principals specified in the grant can retire a grant without the `kms:RetireGrant` permission. The `kms:RetireGrant` permission alone does not allow principals to retire a grant. The `kms:RetireGrant` permission is not effective in a [key policy](key-policies.md) or [resource control policy](resource-control-policies.md).
+ To deny permission to retire a grant, you can use a `Deny` action with the `kms:RetireGrant` permission in your IAM policies.
+ The AWS account that owns the KMS key can delegate the `kms:RetireGrant` permission to an IAM principal in the account.
+ If the retiring principal is a different AWS account, administrators in the other account can use `kms:RetireGrant` to delegate permission to retire the grant to an IAM principal in that account.
The AWS KMS API follows an [eventual consistency](grants.md#terms-eventual-consistency) model. When you create, retire, or revoke a grant, there might be a brief delay before the change is available throughout AWS 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 AWS KMS, [use a grant token](using-grant-token.md) to retire the grant. You cannot use a grant token to revoke a grant.