retirable_grants
Creates, updates, deletes, gets or lists a retirable_grants resource.
Overview
| Name | retirable_grants |
| Type | Resource |
| Id | aws.kms.retirable_grants |
Fields
The following fields are returned by SELECT queries:
- list_retirable_grants
| Name | Datatype | Description |
|---|---|---|
constraints | object | The constraints on the grant, such as encryption context pairs or a SourceArn, that restrict the subsequent operations the grant allows. |
creation_date | string (date-time) | The date and time when the grant was created. |
grant_id | string | The unique identifier for the grant. |
grantee_principal | string | The identity that gets the permissions in the grant. 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, which might correspond to several different grantee principals, such as an IAM user, IAM role, or Amazon Web Services account. (pattern: <code>^[\w+=,.@:/-]+$</code>) |
grantee_service_principal | string | The Amazon Web Services service principal that gets the permissions in the grant. (pattern: <code>^([A-Za-z0-9-]+).([A-Za-z0-9-]+)(.[A-Za-z0-9-]+)+$</code>) |
issuing_account | string | The Amazon Web Services account under which the grant was issued. (pattern: <code>^[\w+=,.@:/-]+$</code>) |
key_id | string | The unique identifier for the KMS key to which the grant applies. |
name | string | The friendly name that identifies the grant. If a name was provided in the CreateGrant request, that name is returned. Otherwise this value is null. (pattern: <code>^[a-zA-Z0-9:/_-]+$</code>) |
operations | array | The list of operations permitted by the grant. |
retiring_principal | string | The principal that can retire the grant. (pattern: <code>^[\w+=,.@:/-]+$</code>) |
retiring_service_principal | string | The Amazon Web Services service principal that can retire the grant. (pattern: <code>^([A-Za-z0-9-]+).([A-Za-z0-9-]+)(.[A-Za-z0-9-]+)+$</code>) |
Methods
The following methods are available for this resource:
| Name | Accessible by | Required Params | Optional Params | Description |
|---|---|---|---|---|
list_retirable_grants | select | region | Returns information about all grants in the Amazon Web Services account and Region that have the specified retiring principal or retiring service principal. You can specify any principal in your Amazon Web Services account. The grants that are returned include grants for KMS keys in your Amazon Web Services account and other Amazon Web Services accounts. You might use this operation to determine which grants you may retire. To retire a grant, use the RetireGrant operation. For detailed information about grants, including grant terminology, see Grants in KMS in the Key Management Service Developer Guide . For examples of creating grants in several programming languages, see Use CreateGrant with an Amazon Web Services SDK or CLI. Cross-account use: You must specify a principal in your Amazon Web Services account. This operation returns a list of grants where the retiring principal specified in the ListRetirableGrants request is the same retiring principal on the grant. This can include grants on KMS keys owned by other Amazon Web Services accounts, but you do not need kms:ListRetirableGrants permission (or any other additional permission) in any Amazon Web Services account other than your own. Required permissions: kms:ListRetirableGrants (IAM policy) in your Amazon Web Services account. When listing retirable grants by RetiringPrincipal, KMS authorizes ListRetirableGrants requests by evaluating the caller account's kms:ListRetirableGrants permissions. The authorized resource in ListRetirableGrants calls is the retiring principal specified in the request. KMS does not evaluate the caller's permissions to verify their access to any KMS keys or grants that might be returned by the ListRetirableGrants call. The RetiringServicePrincipal filter is only usable by callers in a service principal. Related operations: CreateGrant ListGrants RetireGrant RevokeGrant Eventual consistency: The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency. |
Parameters
Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.
| Name | Datatype | Description |
|---|---|---|
region | string | AWS region (default: us-east-1) |
SELECT examples
- list_retirable_grants
Returns information about all grants in the Amazon Web Services account and Region that have the specified retiring principal or retiring service principal. You can specify any principal in your Amazon Web Services account. The grants that are returned include grants for KMS keys in your Amazon Web Services account and other Amazon Web Services accounts. You might use this operation to determine which grants you may retire. To retire a grant, use the RetireGrant operation. For detailed information about grants, including grant terminology, see Grants in KMS in the Key Management Service Developer Guide . For examples of creating grants in several programming languages, see Use CreateGrant with an Amazon Web Services SDK or CLI. Cross-account use: You must specify a principal in your Amazon Web Services account. This operation returns a list of grants where the retiring principal specified in the ListRetirableGrants request is the same retiring principal on the grant. This can include grants on KMS keys owned by other Amazon Web Services accounts, but you do not need kms:ListRetirableGrants permission (or any other additional permission) in any Amazon Web Services account other than your own. Required permissions: kms:ListRetirableGrants (IAM policy) in your Amazon Web Services account. When listing retirable grants by RetiringPrincipal, KMS authorizes ListRetirableGrants requests by evaluating the caller account's kms:ListRetirableGrants permissions. The authorized resource in ListRetirableGrants calls is the retiring principal specified in the request. KMS does not evaluate the caller's permissions to verify their access to any KMS keys or grants that might be returned by the ListRetirableGrants call. The RetiringServicePrincipal filter is only usable by callers in a service principal. Related operations: CreateGrant ListGrants RetireGrant RevokeGrant Eventual consistency: The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.
SELECT
constraints,
creation_date,
grant_id,
grantee_principal,
grantee_service_principal,
issuing_account,
key_id,
name,
operations,
retiring_principal,
retiring_service_principal
FROM aws.kms.retirable_grants
WHERE region = '{{ region }}' -- required
;