AWS kms documentation change
Summary
Expanded grant functionality to support AWS service principals, added SourceArn grant constraint, clarified constraints for symmetric keys, and introduced retiring service principals.
Security assessment
The changes introduce SourceArn constraints to restrict grant permissions to specific resources (aws:SourceArn condition), which enhances security by preventing broader access. However, there's no evidence of a specific vulnerability being fixed. The updates primarily document new security features like service principal support with mandatory constraints.
Diff
diff --git a/kms/latest/developerguide/grants.md b/kms/latest/developerguide/grants.md index 1c93357a3..0f0bb1956 100644 --- a//kms/latest/developerguide/grants.md +++ b//kms/latest/developerguide/grants.md @@ -11 +11 @@ Grant concepts -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.html) and [IAM policies](./iam-policies.html). 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. +A _grant_ is a policy instrument that allows [AWS principals](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) or AWS [service principals](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services) 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.html) and [IAM policies](./iam-policies.html). 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. @@ -21 +21 @@ Grants are a very flexible and useful access control mechanism. When you create - * 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. + * Each grant has one grantee, which can be either a grantee principal (an AWS IAM identity) or a grantee service principal (an AWS service principal). You must specify either `GranteePrincipal` or `GranteeServicePrincipal`, but not both. @@ -38 +38 @@ Be cautious when creating grants and when giving others permission to create gra - * 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](./create-grant-overview.html#grant-constraints) to limit the permissions in a grant for a symmetric encryption key. + * 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](./create-grant-overview.html#grant-constraints) to limit the permissions in a grant. @@ -54 +54,10 @@ To use grants effectively, you'll need to understand the terms and concepts that -A condition that limits the permissions in the grant. Currently, AWS KMS supports grant constraints based on the [encryption context](./encrypt_context.html) in the request for a cryptographic operation. For details, see [Using grant constraints](./create-grant-overview.html#grant-constraints). +A condition that limits the permissions in a grant. AWS KMS supports two types of grant constraints: + + * **Encryption context constraint** — Restricts permissions based on the [encryption context](./encrypt_context.html) included in the request for a cryptographic operation. This constraint works only with symmetric encryption KMS keys. + + * **SourceArn constraint** — Restricts grant permissions to requests made on behalf of a specific AWS resource. This is effectively putting an [aws:SourceArn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) global condition key into the grant. This constraint works with _all types_ of KMS keys. + + + + +For details, see [Using grant constraints](./create-grant-overview.html#grant-constraints). @@ -143 +152 @@ For details, see [Using a grant token](./using-grant-token.html). -The identities that get the permissions specified in the grant. Each grant has one grantee principal, but the grantee principal can represent multiple identities. +An AWS principal (IAM identity) that gets the permissions specified in the grant. @@ -146,0 +156,2 @@ The grantee principal can be any AWS principal, including an AWS account (root), +To specify the grantee principal, use the `GranteePrincipal` parameter in the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) request. + @@ -150,0 +162,13 @@ IAM best practices discourage the use of IAM users with long-term credentials. W +**Grantee service principal** + + +An AWS [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services) that gets the permissions specified in the grant. To specify the grantee service principal, use the `GranteeServicePrincipal` parameter in the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) request. + +When you create a grant with a `GranteeServicePrincipal`, you must also include a [SourceArn grant constraint](./create-grant-overview.html#terms-source-arn-constraint). The `SourceArn` constraint ensures that the service principal can use the KMS key only when the request is made on behalf of the specified AWS resource. + +When you specify a `GranteeServicePrincipal`, you must also specify either a RetiringPrincipal or a RetiringServicePrincipal. + +###### Note + +You must specify either GranteePrincipal or GranteeServicePrincipal, but not both. + @@ -162,0 +187,2 @@ A principal who can retire a grant. You can specify a retiring principal in a gr +To specify the retiring principal, use the `RetiringPrincipal` parameter in the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) request. + @@ -167 +193,10 @@ IAM best practices discourage the use of IAM users with long-term credentials. W -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](./grant-delete.html). +**Retiring service principal** + + +An AWS [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services) that has permission to retire a grant. To specify the retiring service principal, use the `RetiringServicePrincipal` parameter in the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) request. + +###### Note + +You can specify either RetiringPrincipal or RetiringServicePrincipal, but not both. + +For more information about who can retire a grant, see [Retiring and revoking grants](./grant-delete.html).