Viewing KMS keys with the API - Amazon Key Management Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Viewing KMS keys with the API

You can use the Amazon Key Management Service (Amazon KMS) API to view your KMS keys. This section demonstrates several operations that return details about existing KMS keys. The examples use the Amazon Command Line Interface (Amazon CLI), but you can use any supported programming language.

ListKeys: Get the ID and ARN of all KMS keys

The ListKeys operation returns the ID and Amazon Resource Name (ARN) of all KMS keys in the account and Region.

For example, this call to the ListKeys operation returns the ID and ARN of each KMS key in this fictitious account. For examples in multiple programming languages, see Getting key IDs and key ARNs of KMS keys.

$ aws kms list-keys { "Keys": [ { "KeyArn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab" }, { "KeyArn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321", "KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321" }, { "KeyArn": "arn:aws:kms:us-east-2:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d", "KeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d" } }

DescribeKey: Get detailed information about a KMS key

The DescribeKey operation returns details about the specified KMS key. To identify the KMS key, use the key ID, key ARN, alias name, or alias ARN.

Note

The DescribeKey response includes both KeySpec and CustomerMasterKeySpec members with the same values. The CustomerMasterKeySpec member is deprecated.

For example, this call to DescribeKey returns information about a symmetric KMS key. The fields in the response vary with the Amazon KMS key spec, key state, and the key material origin. For examples in multiple programming languages, see Viewing an Amazon KMS key.

$ aws kms describe-key --key-id 1234abcd-12ab-34cd-56ef-1234567890ab { "KeyMetadata": { "Origin": "AWS_KMS", "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "Description": "", "KeyManager": "CUSTOMER", "Enabled": true, "KeySpec": "SYMMETRIC_DEFAULT", "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT", "KeyUsage": "ENCRYPT_DECRYPT", "KeyState": "Enabled", "CreationDate": 1499988169.234, "MultiRegion": false, "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "AWSAccountId": "111122223333", "EncryptionAlgorithms": [ "SYMMETRIC_DEFAULT" ] } }

This example calls DescribeKey operation on an asymmetric KMS key used for signing and verification. The response includes the signing algorithms that Amazon KMS supports for this KMS key.

$ aws kms describe-key --key-id 0987dcba-09fe-87dc-65ba-ab0987654321 { "KeyMetadata": { "KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321", "Origin": "AWS_KMS", "Arn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321", "KeyState": "Enabled", "KeyUsage": "SIGN_VERIFY", "CreationDate": 1569973196.214, "Description": "", "KeySpec": "ECC_NIST_P521", "CustomerMasterKeySpec": "ECC_NIST_P521", "AWSAccountId": "111122223333", "Enabled": true, "MultiRegion": false, "KeyManager": "CUSTOMER", "SigningAlgorithms": [ "ECDSA_SHA_512" ] } }

GetKeyPolicy: Get the key policy attached to a KMS key

The GetKeyPolicy operation gets the key policy that is attached to the KMS key. To identify the KMS key, use its key ID or key ARN. You must also specify the policy name, which is always default. (If your output is difficult to read, add the --output text option to your command.)

For examples in multiple programming languages, see Getting a key policy.

$ aws kms get-key-policy --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --policy-name default { "Version" : "2012-10-17", "Id" : "key-default-1", "Statement" : [ { "Sid" : "Enable IAM policies", "Effect" : "Allow", "Principal" : { "AWS" : "arn:aws:iam::111122223333:root" }, "Action" : "kms:*", "Resource" : "*" } ] }

ListAliases: Get alias names and ARNs for KMS keys

The ListAliases operation returns aliases in the account and region. The TargetKeyId in the response displays the key ID of the KMS key that the alias refers to, if any.

By default, the ListAliases command returns all aliases in the account and region. This includes aliases that you created and associated with your customer managed keys, and aliases that Amazon created and associated with Amazon managed key in your account. You can recognize Amazon aliases because their names have the format aws/<service-name>, such as aws/dynamodb.

The response might also include aliases without the TargetKeyId field, such as the aws/redshift alias in this example. These are predefined aliases that Amazon has created but has not yet associated with a KMS key.

For examples in multiple programming languages, see Listing aliases.

$ aws kms list-aliases { "Aliases": [ { "AliasName": "alias/access-key", "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/access-key", "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321", "CreationDate": 1516435200.399, "LastUpdatedDate": 1516435200.399 }, { "AliasName": "alias/financeKey", "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/financeKey", "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321", "CreationDate": 1604958290.014, "LastUpdatedDate": 1604958290.014 }, { "AliasName": "alias/ECC-P521-Sign", "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/ECC-P521-Sign", "TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "CreationDate": 1693622000.704, "LastUpdatedDate": 1693622000.704 }, { "AliasName": "alias/ImportedKey", "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/ImportedKey", "TargetKeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d", "CreationDate": 1493622000.704, "LastUpdatedDate": 1521097200.235 }, { "AliasName": "alias/aws/dynamodb", "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/dynamodb", "TargetKeyId": "0987ab65-43cd-21ef-09ab-87654321cdef", "CreationDate": 1521097200.454, "LastUpdatedDate": 1521097200.454 }, { "AliasName": "alias/aws/ebs", "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/ebs", "TargetKeyId": "abcd1234-09fe-ef90-09fe-ab0987654321", "CreationDate": 1466518990.200, "LastUpdatedDate": 1466518990.200 }, { "AliasName": "alias/aws/redshift", "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/redshift" }, ] }

To get the aliases that refer to a particular KMS key, use the KeyId parameter. The parameter value can be the key ID or key ARN. You cannot specify an alias name or alias ARN.

The command in the following example gets the aliases that refer to a customer managed key. But you can use a command like this one to find the aliases that refer to Amazon managed keys, too.

$ aws kms list-aliases --key-id arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321 { "Aliases": [ { "AliasName": "alias/access-key", "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/access-key", "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321", "CreationDate": 1516435200.399, "LastUpdatedDate": 1516435200.399 }, { "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/financeKey", "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321", "AliasName": "alias/financeKey", "CreationDate": 1604958290.014, "LastUpdatedDate": 1604958290.014 }, ] }

To get only the aliases for Amazon managed keys, use the features of your programming language to filter the response.

$ aws kms list-aliases --query 'Aliases[?starts_with(AliasName, `alias/aws/`)]'

ListResourceTags: Get the tags on KMS keys

The ListResourceTags operation returns the tags on the specified KMS key. The API returns tags for one KMS key, but you can run the command in a loop to get tags for all KMS keys in the account and Region, or for a set of KMS keys you select. This API returns one page at a time, so if you have numerous tags on numerous KMS keys, you might have to use the paginator in your programming language to get all of the tags you want.

The ListResourceTags operation returns tags for all KMS keys, but Amazon managed key are not tagged.

To find the tags for a KMS key, use the ListResourceTags operation. The KeyId parameter is required. It accepts a key ID or key ARN. Before running this example, replace the example key ARN with a valid one.

$ aws kms list-resource-tags --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab { "Tags": [ { "TagKey": "Department", "TagValue": "IT" }, { "TagKey": "Purpose", "TagValue": "Test" } ], "Truncated": false }

You might want to use the ListResourceTags operation to get all KMS keys in the account and Region with a particular tag, tag key, or tag value. To do this, use the filtering features of your programming language.

For example, the following Bash script uses the ListKeys and ListResourceTags operations to get all KMS keys in the account and Region with a Project tag key. Both of these operations get only the first page of results. If you have numerous KMS keys or numerous tags, use the pagination features of your language to get the entire result from each operation. Before running this example, replace the example key IDs with valid ones.

TARGET_TAG_KEY='Project' for key in $(aws kms list-keys --query 'Keys[*].KeyId' --output text); do key_tags=$(aws kms list-resource-tags --key-id "$key" --query "Tags[?TagKey==\`$TARGET_TAG_KEY\`]") if [ "$key_tags" != "[]" ]; then echo "Key: $key" echo "$key_tags" fi done

The output is formatted like the following example output.

Key: 0987dcba-09fe-87dc-65ba-ab0987654321 [ { "TagKey": "Project", "TagValue": "Gamma" } ] Key: 1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d [ { "TagKey": "Project", "TagValue": "Alpha" } ] Key: 0987ab65-43cd-21ef-09ab-87654321cdef [ { "TagKey": "Project", "TagValue": "Alpha" } ]