AWS cli documentation change
Summary
Added support for service principals in grants, introduced new parameters (--grantee-service-principal, --retiring-service-principal), added SourceArn grant constraint, updated grant constraint documentation, and clarified requirements for principal parameters
Security assessment
The changes enhance documentation about grant constraints (especially the new SourceArn constraint) which helps prevent confused deputy problems by restricting grants to specific resources. While this improves security posture, there's no evidence it addresses a specific existing vulnerability.
Diff
diff --git a/cli/latest/reference/kms/create-grant.md b/cli/latest/reference/kms/create-grant.md index 21fdb4207..2f3c1353c 100644 --- a//cli/latest/reference/kms/create-grant.md +++ b//cli/latest/reference/kms/create-grant.md @@ -15 +15 @@ - * [AWS CLI 2.34.49 Command Reference](../../index.html) » + * [AWS CLI 2.34.52 Command Reference](../../index.html) » @@ -63,0 +64,2 @@ A _grant_ is a policy instrument that allows Amazon Web Services principals to u +You can create a grant for an Amazon Web Services principal (IAM user, IAM role, or Amazon Web Services account) by specifying the `GranteePrincipal` parameter. You can also create a grant for an Amazon Web Services service principal by specifying the `GranteeServicePrincipal` parameter. + @@ -97 +99 @@ See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/kms-20 - --grantee-principal <value> + [--grantee-principal <value>] @@ -103,0 +106,2 @@ See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/kms-20 + [--grantee-service-principal <value>] + [--retiring-service-principal <value>] @@ -151 +155 @@ See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/kms-20 -`--grantee-principal` (string) [required] +`--grantee-principal` (string) @@ -156,0 +161,2 @@ See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/kms-20 +> You must specify either `GranteePrincipal` or `GranteeServicePrincipal` , but not both. +> @@ -172,0 +179,2 @@ See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/kms-20 +> You can specify either `RetiringPrincipal` or `RetiringServicePrincipal` , but not both. +> @@ -225 +233 @@ Syntax: -> KMS supports the `EncryptionContextEquals` and `EncryptionContextSubset` grant constraints, which allow the permissions in the grant only when the encryption context in the request matches (`EncryptionContextEquals` ) or includes (`EncryptionContextSubset` ) the encryption context specified in the constraint. +> KMS supports the following grant constraints. @@ -227 +235,2 @@ Syntax: -> The encryption context grant constraints are supported only on [grant operations](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations) that include an `EncryptionContext` parameter, such as cryptographic operations on symmetric encryption KMS keys. Grants with grant constraints can include the DescribeKey and RetireGrant operations, but the constraint doesn’t apply to these operations. If a grant with a grant constraint includes the `CreateGrant` operation, the constraint requires that any grants created with the `CreateGrant` permission have an equally strict or stricter encryption context constraint. +> * `EncryptionContextEquals` and `EncryptionContextSubset` — These encryption context grant constraints allow the permissions in the grant only when the encryption context in the request matches (`EncryptionContextEquals` ) or includes (`EncryptionContextSubset` ) the encryption context specified in the constraint. Encryption context grant constraints are supported only on [grant operations](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations) that include an `EncryptionContext` parameter, such as cryptographic operations on symmetric encryption KMS keys. You cannot use an encryption context grant constraint for cryptographic operations with asymmetric KMS keys or HMAC KMS keys. Operations with these keys don’t support an encryption context. Grants with encryption context grant constraints can include the DescribeKey and RetireGrant operations, but the constraint doesn’t apply to these operations. If a grant with an encryption context grant constraint includes the `CreateGrant` operation, the constraint requires that any grants created with the `CreateGrant` permission have an equally strict or stricter encryption context constraint. Each constraint value can include up to 8 encryption context pairs. The encryption context value in each constraint cannot exceed 384 characters. For more information about encryption context, see [Encryption context](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context) in the * _Key Management Service Developer Guide_ * . +> * `SourceArn` — This grant constraint allows the permissions in the grant only when the request is made on behalf of a specific Amazon Web Services resource, identified by its [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) . This is effectively the same as having the [aws:SourceArn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) global condition key in the grant. The SourceArn constraint is supported on grants for all types of KMS keys and can also be applied to the DescribeKey operation when specified in the request. However, it does not apply to RetireGrant operation. @@ -229 +238 @@ Syntax: -> You cannot use an encryption context grant constraint for cryptographic operations with asymmetric KMS keys or HMAC KMS keys. Operations with these keys don’t support an encryption context. + @@ -231 +240 @@ Syntax: -> Each constraint value can include up to 8 encryption context pairs. The encryption context value in each constraint cannot exceed 384 characters. For information about grant constraints, see [Using grant constraints](https://docs.aws.amazon.com/kms/latest/developerguide/create-grant-overview.html#grant-constraints) in the _Key Management Service Developer Guide_ . For more information about encryption context, see [Encryption context](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context) in the * _Key Management Service Developer Guide_ * . +> For information about grant constraints, see [Using grant constraints](https://docs.aws.amazon.com/kms/latest/developerguide/create-grant-overview.html#grant-constraints) in the _Key Management Service Developer Guide_ . @@ -247,0 +257,12 @@ Syntax: +> +> SourceArn -> (string) +> +>> The [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) of an Amazon Web Services resource on behalf of which the request is made. This is effectively the same as having the [aws:SourceArn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) global condition key in the grant. The SourceArn constraint ensures that the principal can use the KMS key only when the request is made on behalf of the specified resource. +>> +>> Constraints: +>> +>> * min: `20` +>> * max: `512` +>> * pattern: `^arn:aws[a-z0-9-]*:[a-z0-9-]+:[a-z0-9-]*:[0-9]{12}:.+$` +>> + @@ -252 +273 @@ Shorthand Syntax: - EncryptionContextSubset={KeyName1=string,KeyName2=string},EncryptionContextEquals={KeyName1=string,KeyName2=string} + EncryptionContextSubset={KeyName1=string,KeyName2=string},EncryptionContextEquals={KeyName1=string,KeyName2=string},SourceArn=string @@ -262 +283,2 @@ JSON Syntax: - ...} + ...}, + "SourceArn": "string" @@ -319,0 +342,30 @@ Syntax: +`--grantee-service-principal` (string) + +> The Amazon Web Services [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. +> +> When you specify a `GranteeServicePrincipal` , you must also specify a `SourceArn` grant constraint. In addition, you must specify either a `RetiringPrincipal` or a `RetiringServicePrincipal` . +> +> You must specify either `GranteePrincipal` or `GranteeServicePrincipal` , but not both. +> +> Constraints: +> +> * min: `1` +> * max: `128` +> * pattern: `^([A-Za-z0-9\-]+)\.([A-Za-z0-9\-]+)(\.[A-Za-z0-9\-]+)+$` +> + + +`--retiring-service-principal` (string) + +> The Amazon Web Services [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services) that has permission to use the RetireGrant operation to retire the grant. +> +> You can specify either `RetiringPrincipal` or `RetiringServicePrincipal` , but not both. +> +> Constraints: +> +> * min: `1` +> * max: `128` +> * pattern: `^([A-Za-z0-9\-]+)\.([A-Za-z0-9\-]+)(\.[A-Za-z0-9\-]+)+$` +> + + @@ -503 +555 @@ GrantId -> (string) - * [AWS CLI 2.34.49 Command Reference](../../index.html) » + * [AWS CLI 2.34.52 Command Reference](../../index.html) »