[ aws . kms ]

describe-key

Description

Provides detailed information about a customer master key (CMK). You can run DescribeKey on a customer managed CMK or an AWS managed CMK .

This detailed information includes the key ARN, creation date (and deletion date, if applicable), the key state, and the origin and expiration date (if any) of the key material. For CMKs in custom key stores, it includes information about the custom key store, such as the key store ID and the AWS CloudHSM cluster ID. It includes fields, like KeySpec , that help you distinguish symmetric from asymmetric CMKs. It also provides information that is particularly important to asymmetric CMKs, such as the key usage (encryption or signing) and the encryption algorithms or signing algorithms that the CMK supports.

DescribeKey does not return the following information:

• Aliases associated with the CMK. To get this information, use ListAliases .

• Whether automatic key rotation is enabled on the CMK. To get this information, use GetKeyRotationStatus . Also, some key states prevent a CMK from being automatically rotated. For details, see How Automatic Key Rotation Works in AWS Key Management Service Developer Guide .

• Tags on the CMK. To get this information, use ListResourceTags .

• Key policies and grants on the CMK. To get this information, use GetKeyPolicy and ListGrants .

If you call the DescribeKey operation on a predefined AWS alias , that is, an AWS alias with no key ID, AWS KMS creates an AWS managed CMK . Then, it associates the alias with the new CMK, and returns the KeyId and Arn of the new CMK in the response.

Cross-account use : Yes. To perform this operation with a CMK in a different AWS account, specify the key ARN or alias ARN in the value of the KeyId parameter.

Required permissions : kms:DescribeKey (key policy)

Related operations:

• GetKeyPolicy

• GetKeyRotationStatus

• ListAliases

• ListGrants

• ListKeys

• ListResourceTags

• ListRetirableGrants

See also: AWS API Documentation

See ‘aws help’ for descriptions of global parameters.

Synopsis

  describe-key
--key-id <value>
[--grant-tokens <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]

Options

--key-id (string)

Describes the specified customer master key (CMK).

If you specify a predefined AWS alias (an AWS alias with no key ID), KMS associates the alias with an AWS managed CMK and returns its KeyId and Arn in the response.

To specify a CMK, use its key ID, Amazon Resource Name (ARN), alias name, or alias ARN. When using an alias name, prefix it with "alias/" . To specify a CMK in a different AWS account, you must use the key ARN or alias ARN.

For example:

• Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab

• Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

• Alias name: alias/ExampleAlias

• Alias ARN: arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias

To get the key ID and key ARN for a CMK, use ListKeys or DescribeKey . To get the alias name and alias ARN, use ListAliases .

--grant-tokens (list)

A list of grant tokens.

For more information, see Grant Tokens in the AWS Key Management Service Developer Guide .

(string)

Syntax:

"string" "string" ...

--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 find detailed information about a customer master key (CMK)

The following describe-key example gets detailed information about the AWS managed CMK for Amazon S3 in the example account and Region. You can use this command to find details about AWS managed CMKs and customer managed CMKs.

To specify the CMK, use the key-id parameter. This example uses an alias name value, but you can use a key ID, key ARN, alias name, or alias ARN in this command.

aws kms describe-key \
    --key-id alias/aws/s3

Output:

{
    "KeyMetadata": {
        "AWSAccountId": "846764612917",
        "KeyId": "b8a9477d-836c-491f-857e-07937918959b",
        "Arn": "arn:aws:kms:us-west-2:846764612917:key/b8a9477d-836c-491f-857e-07937918959b",
        "CreationDate": 1566518783.394,
        "Enabled": true,
        "Description": "Default master key that protects my S3 objects when no other key is defined",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "KeyState": "Enabled",
        "Origin": "AWS_KMS",
        "KeyManager": "AWS",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ]
    }
}

For more information, see Viewing Keys in the AWS Key Management Service Developer Guide.

Output

KeyMetadata -> (structure)

Metadata associated with the key.

AWSAccountId -> (string)

The twelve-digit account ID of the AWS account that owns the CMK.

KeyId -> (string)

The globally unique identifier for the CMK.

Arn -> (string)

The Amazon Resource Name (ARN) of the CMK. For examples, see AWS Key Management Service (AWS KMS) in the Example ARNs section of the AWS General Reference .

CreationDate -> (timestamp)

The date and time when the CMK was created.

Enabled -> (boolean)

Specifies whether the CMK is enabled. When KeyState is Enabled this value is true, otherwise it is false.

Description -> (string)

The description of the CMK.

KeyUsage -> (string)

The cryptographic operations for which you can use the CMK.

KeyState -> (string)

The current status of the CMK.

For more information about how key state affects the use of a CMK, see Key state: Effect on your CMK in the AWS Key Management Service Developer Guide .

DeletionDate -> (timestamp)

The date and time after which AWS KMS deletes the CMK. This value is present only when KeyState is PendingDeletion .

ValidTo -> (timestamp)

The time at which the imported key material expires. When the key material expires, AWS KMS deletes the key material and the CMK becomes unusable. This value is present only for CMKs whose Origin is EXTERNAL and whose ExpirationModel is KEY_MATERIAL_EXPIRES , otherwise this value is omitted.

Origin -> (string)

The source of the CMK’s key material. When this value is AWS_KMS , AWS KMS created the key material. When this value is EXTERNAL , the key material was imported from your existing key management infrastructure or the CMK lacks key material. When this value is AWS_CLOUDHSM , the key material was created in the AWS CloudHSM cluster associated with a custom key store.

CustomKeyStoreId -> (string)

A unique identifier for the custom key store that contains the CMK. This value is present only when the CMK is created in a custom key store.

CloudHsmClusterId -> (string)

The cluster ID of the AWS CloudHSM cluster that contains the key material for the CMK. When you create a CMK in a custom key store , AWS KMS creates the key material for the CMK in the associated AWS CloudHSM cluster. This value is present only when the CMK is created in a custom key store.

ExpirationModel -> (string)

Specifies whether the CMK’s key material expires. This value is present only when Origin is EXTERNAL , otherwise this value is omitted.

KeyManager -> (string)

The manager of the CMK. CMKs in your AWS account are either customer managed or AWS managed. For more information about the difference, see Customer Master Keys in the AWS Key Management Service Developer Guide .

CustomerMasterKeySpec -> (string)

Describes the type of key material in the CMK.

EncryptionAlgorithms -> (list)

The encryption algorithms that the CMK supports. You cannot use the CMK with other encryption algorithms within AWS KMS.

This field appears only when the KeyUsage of the CMK is ENCRYPT_DECRYPT .

(string)

SigningAlgorithms -> (list)

The signing algorithms that the CMK supports. You cannot use the CMK with other signing algorithms within AWS KMS.

This field appears only when the KeyUsage of the CMK is SIGN_VERIFY .

(string)