Using grants in AWS KMS - AWS Key Management Service

Using grants in AWS KMS

A grant is a policy instrument that allows AWS principals 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 and IAM policies. 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 How AWS services use AWS KMS or the Encryption at rest topic in the service's user guide or developer guide.

For code examples that demonstrate how to work with grants in several programming languages, see Working with grants.

About grants

Grants are a very flexible and useful access control mechanism. When you create a grant for a KMS key, the grant allows the grantee principals 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 must have at least one grantee principal. The grantee principal can be an identity in a different AWS account.

  • A grant can only allow grant operations. The grant operations must be supported by the KMS key in the grant. If you specify an unsupported operation, the CreateGrant request fails with a ValidationError exception.

  • Grantee principals 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, when you create, retire, or revoke a grant, there might be a brief delay, usually less than five minutes, until the operation achieves eventual consistency. To use the permissions in a grant immediately, use a grant token.

  • An authorized principal can delete the grant (retire or revoke 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.

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 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. You can also use grant constraints to limit the permissions in a grant.

  • Principals can get permission to create grants from a key policy or IAM policy. These principals can create grants for any grant operation on the KMS key, even if they don't have the permission. When you allow kms:CreateGrant permission in a policy, you can use policy conditions to limit this permission.

  • Principals can also get permission to create grants from a grant. These principal can only delegate the permissions that they were granted, even if they have other permissions from a policy. For details, see Granting CreateGrant permission.

For help with concepts related to grants, see Grant terminology.

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 in the request for a cryptographic operation. For details, see Using 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, to identify a grant in a RetireGrant or RevokeGrant request.

Grant operations

The AWS KMS operations that you can allow in a grant. If you specify other operations, the CreateGrant request fails with a ValidationError exception. These are also the operations that accept a grant token. For detailed information about these permissions, see the AWS KMS permissions.

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:

The grant operations that you allow must be supported by the KMS key in the grant. If you specify an unsupported operation, the CreateGrant request fails with a ValidationError exception.

Grant token

When you create a grant, there might be a brief delay, usually less than five minutes, until the new grant is available throughout AWS KMS, that is, until it achieves eventual consistency. If you try a use a grant before it achieves eventual consistency, 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 unique, non-secret, variable-length, base64-encoded string that represents a grant. You can use the grant token to identify the grant in any grant operation. 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 achieves eventual consistency. After that, the 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 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 can use a grant token in a call to the RetireGrant 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 for the CreateGrant operation. The ListGrants and ListRetirableGrants operations return the grant ID, but not a grant token.

For details, see Using a grant token.

Grantee principal

The identity that gets the permissions specified in the grant. A grant must have at least one grantee principal. The grantee principal can be any AWS principal, including an AWS account (root), an IAM user, an IAM role, a federated role or user, 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, an IAM group, or an AWS organization.

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.

Retiring principal

A principal who can retire a 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.

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

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.

Eventual consistency (for grants)

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. When this interval is complete, we consider the operation to have achieved eventual consistency.

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. You can use a grant token to refer to a grant in any grant operation. For instructions, see Using a grant token.

  • The CreateGrant operation has a Name parameter that prevents retry operations from creating duplicate grants.

Note

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.

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.

  • 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 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 in the AWS Security Blog.

    Tip

    Use the EncryptionContextEqual grant constraint whenever possible. The EncryptionContextSubset 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. To detect duplicate grants, use the ListGrants operation. If you accidentally create a duplicate grant, retire or revoke it as soon as possible.

    Note

    Grants for AWS managed keys 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, which might represent several different grantee principals.

  • Remember that grants do not automatically expire. Retire or revoke the grant as soon as the permission is no longer needed. Grants that are not deleted might create a security risk for encrypted resources.