[ aws . kms ]

list-retirable-grants

Description

Returns information about all grants in the Amazon Web Services account and Region that have the specified retiring 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 Using grants in the * Key Management Service Developer Guide * . For examples of working with grants in several programming languages, see Programming grants .

Cross-account use : You must specify a principal in your Amazon Web Services account. However, this operation can return grants in any Amazon Web Services account. 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.

Related operations:

• CreateGrant

• ListGrants

• RetireGrant

• RevokeGrant

See also: AWS API Documentation

See ‘aws help’ for descriptions of global parameters.

Synopsis

  list-retirable-grants
[--limit <value>]
[--marker <value>]
--retiring-principal <value>
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]

Options

--limit (integer)

Use this parameter to specify the maximum number of items to return. When this value is present, KMS does not return more than the specified number of items, but it might return fewer.

This value is optional. If you include a value, it must be between 1 and 100, inclusive. If you do not include a value, it defaults to 50.

--marker (string)

Use this parameter in a subsequent request after you receive a response with truncated results. Set it to the value of NextMarker from the truncated response you just received.

--retiring-principal (string)

The retiring principal for which to list grants. Enter a principal in your Amazon Web Services account.

To specify the retiring principal, use the Amazon Resource Name (ARN) of an Amazon Web Services principal. Valid Amazon Web Services principals include Amazon Web Services accounts (root), IAM users, federated users, and assumed role users. For examples of the ARN syntax for specifying a principal, see Amazon Web Services Identity and Access Management (IAM) in the Example ARNs section of the Amazon Web Services General Reference .

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See ‘aws help’ for descriptions of global parameters.

Examples

To view the grants that a principal can retire

The following list-retirable-grants example displays all of the grants that the ExampleAdmin user can retire on the customer master keys (CMKs) in an AWS account and Region. You can use a command like this one to view the grants that any account principal can retire on CMKs in the AWS account and Region.

The value of the required retiring-principal parameter must be the Amazon Resource Name (ARN) of an account, user, or role.

You cannot specify a service for the value of retiring-principal in this command, even though a service can be the retiring principal. To find the grants in which a particular service is the retiring principal, use the list-grants command.

The output shows that ExampleAdmin user has permission to retire grants on two different CMKs in the account and region. In addition to the retiring principal, the account (root) has permission to retire any grant in the account.

aws kms list-retirable-grants \
    --retiring-principal arn:aws:iam::111122223333:user/ExampleAdmin

Output:

{
    "Grants": [
        {
            "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "GrantId": "156b69c63cb154aa21f59929ff19760717be8d9d82b99df53e18b94a15a5e88e",
            "Name": "",
            "CreationDate": 1576800734.0,
            "GranteePrincipal": "arn:aws:iam::111122223333:user/ExampleUser",
            "RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
            "IssuingAccount": "arn:aws:iam::111122223333:root",
            "Operations": [
                "Encrypt"
            ],
            "Constraints": {
                "EncryptionContextSubset": {
                    "Department": "IT"
                }
            }
        },
        {
            "KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
            "GrantId": "8c94d1f12f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
            "Name": "",
            "CreationDate": 1568565290.0,
            "GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",
            "RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
            "IssuingAccount": "arn:aws:iam::111122223333:root",
            "Operations": [
                "Decrypt"
            ],
            "Constraints": {
                "EncryptionContextSubset": {
                    "Department": "IT"
                }
            }
        }
    ],
    "Truncated": false
}

For more information, see Using Grants in the AWS Key Management Service Developer Guide.

Output

Grants -> (list)

A list of grants.

(structure)

Contains information about a grant.

KeyId -> (string)

The unique identifier for the KMS key to which the grant applies.

GrantId -> (string)

The unique identifier for the grant.

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.

CreationDate -> (timestamp)

The date and time when the grant was created.

GranteePrincipal -> (string)

The identity that gets the permissions in the grant.

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 , which might represent several different grantee principals.

RetiringPrincipal -> (string)

The principal that can retire the grant.

IssuingAccount -> (string)

The Amazon Web Services account under which the grant was issued.

Operations -> (list)

The list of operations permitted by the grant.

(string)

Constraints -> (structure)

A list of key-value pairs that must be present in the encryption context of certain subsequent operations that the grant allows.

EncryptionContextSubset -> (map)

A list of key-value pairs that must be included in the encryption context of the cryptographic operation request. The grant allows the cryptographic operation only when the encryption context in the request includes the key-value pairs specified in this constraint, although it can include additional key-value pairs.

key -> (string)

value -> (string)

EncryptionContextEquals -> (map)

A list of key-value pairs that must match the encryption context in the cryptographic operation request. The grant allows the operation only when the encryption context in the request is the same as the encryption context specified in this constraint.

key -> (string)

value -> (string)

NextMarker -> (string)

When Truncated is true, this element is present and contains the value to use for the Marker parameter in a subsequent request.

Truncated -> (boolean)

A flag that indicates whether there are more items in the list. When this value is true, the list in this response is truncated. To get more items, pass the value of the NextMarker element in thisresponse to the Marker parameter in a subsequent request.