AWS cli documentation change
Summary
Updated documentation for KMS ListGrants command to add support for filtering by grantee service principal, clarify service principal behavior, and document new output fields including SourceArn constraint, GranteeServicePrincipal, and RetiringServicePrincipal.
Security assessment
The changes enhance documentation of security features like grant constraints (SourceArn) and service principal handling, but there's no evidence of addressing a specific vulnerability. The SourceArn constraint documentation improves understanding of resource-based access control, which is security-relevant but not a response to a known issue.
Diff
diff --git a/cli/latest/reference/kms/list-grants.md b/cli/latest/reference/kms/list-grants.md index f08efee3c..41a6316c7 100644 --- a//cli/latest/reference/kms/list-grants.md +++ b//cli/latest/reference/kms/list-grants.md @@ -15 +15 @@ - * [AWS CLI 2.34.49 Command Reference](../../index.html) » + * [AWS CLI 2.34.52 Command Reference](../../index.html) » @@ -62 +62 @@ Gets a list of all grants for the specified KMS key. -You must specify the KMS key in all requests. You can filter the grant list by grant ID or grantee principal. +You must specify the KMS key in all requests. You can filter the grant list by grant ID, grantee principal, or grantee service principal. @@ -68 +68,3 @@ For detailed information about grants, including grant terminology, see [Grants -> The `GranteePrincipal` field in the `ListGrants` response usually contains the user or role designated as the grantee principal in the grant. However, when the grantee principal in the grant is an Amazon Web Services 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. +> When a grant is created with the `GranteePrincipal` field, the `ListGrants` response usually contains the user or role designated as the grantee principal in the grant. However, if the grantee principal is an Amazon Web Services service, the `GranteePrincipal` field contains an Amazon Web Services [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services) , which might correspond to several different grantee principals, such as an IAM user, IAM role, or Amazon Web Services account. +> +> When a grant is created with the `GranteeServicePrincipal` field, the `ListGrants` response always includes a `GranteeServicePrincipal` that indicates the grantee is actually an Amazon Web Services [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services) . @@ -95,0 +98 @@ See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/kms-20 + [--grantee-service-principal <value>] @@ -160,0 +164,2 @@ See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/kms-20 +> You can specify either `GranteePrincipal` or `GranteeServicePrincipal` , but not both. +> @@ -168,0 +174,14 @@ See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/kms-20 +`--grantee-service-principal` (string) + +> Returns only grants where the specified Amazon Web Services service principal is the grantee service principal for the grant. This filter is only usable by callers in a service principal. +> +> You can 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\-]+)+$` +> + + @@ -404 +423 @@ Grants -> (list) ->>> The `GranteePrincipal` field in the `ListGrants` response usually contains the user or role designated as the grantee principal in the grant. However, when the grantee principal in the grant is an Amazon Web Services 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. +>>> When a grant is created with the `GranteePrincipal` field, the `ListGrants` response usually contains the user or role designated as the grantee principal in the grant. However, if the grantee principal is an Amazon Web Services service, the `GranteePrincipal` field contains an Amazon Web Services [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services) , which might correspond to several different grantee principals, such as an IAM user, IAM role, or Amazon Web Services account. @@ -468 +487 @@ Grants -> (list) ->>> A list of key-value pairs that must be present in the encryption context of certain subsequent operations that the grant allows. +>>> The constraints on the grant, such as encryption context pairs or a SourceArn, that restrict the subsequent operations the grant allows. @@ -484,0 +504,36 @@ Grants -> (list) +>>> +>>> 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}:.+$` +>>>> + +>> +>> GranteeServicePrincipal -> (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 in the grant. +>>> +>>> Constraints: +>>> +>>> * min: `1` +>>> * max: `128` +>>> * pattern: `^([A-Za-z0-9\-]+)\.([A-Za-z0-9\-]+)(\.[A-Za-z0-9\-]+)+$` +>>> + +>> +>> RetiringServicePrincipal -> (string) +>> +>>> The Amazon Web Services [service principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services) that can retire the grant. +>>> +>>> Constraints: +>>> +>>> * min: `1` +>>> * max: `128` +>>> * pattern: `^([A-Za-z0-9\-]+)\.([A-Za-z0-9\-]+)(\.[A-Za-z0-9\-]+)+$` +>>> + @@ -512 +567 @@ Truncated -> (boolean) - * [AWS CLI 2.34.49 Command Reference](../../index.html) » + * [AWS CLI 2.34.52 Command Reference](../../index.html) »