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

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

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

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:

• Cryptographic operations

  • Decrypt

  • DeriveSharedSecret

  • Encrypt

  • GenerateDataKey

  • GenerateDataKeyPair

  • GenerateDataKeyPairWithoutPlaintext

  • GenerateDataKeyWithoutPlaintext

  • GenerateMac

  • ReEncryptFrom

  • ReEncryptTo

  • Sign

  • Verify

  • VerifyMac

• Other operations

  • CreateGrant

  • DescribeKey

  • GetPublicKey

  • RetireGrant

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. For example, grants for symmetric encryption KMS keys cannot allow the Sign, Verify, GenerateMac or VerifyMac 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 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. 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 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 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, 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.

Note

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.

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.

Note

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.

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)

The AWS KMS API follows an 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. 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.

For more information, see AWS KMS eventual consistency.