Skip to content

describe_key async 

describe_key(
    key_id: KeyIdType,
    *,
    config_overrides: Optional[AsyncKMSClientConfig] = None,
    grant_tokens: Optional[GrantTokenList] = None,
) -> DescribeKeyResponse

Provides detailed information about a KMS key. You can run DescribeKey on a customer managed key or an Amazon Web Services managed key.

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. It includes fields, like KeySpec, that help you distinguish different types of KMS keys. It also displays the key usage (encryption, signing, or generating and verifying MACs) and the algorithms that the KMS key supports.

For multi-Region keys, DescribeKey displays the primary key and all related replica keys. For KMS keys in CloudHSM key stores, it includes information about the key store, such as the key store ID and the CloudHSM cluster ID. For KMS keys in external key stores, it includes the custom key store ID and the ID of the external key.

DescribeKey does not return the following information:

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

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

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

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

In general, DescribeKey is a non-mutating operation. It returns data about KMS keys, but doesn't change them. However, Amazon Web Services services use DescribeKey to create Amazon Web Services managed keys from a predefined Amazon Web Services alias with no key ID.

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

Required permissions: kms:DescribeKey (key policy)

Related operations:

Eventual consistency: The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.

Parameters:

  • key_id (KeyIdType) –

    Describes the specified KMS key.

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

    To specify a KMS key, use its key ID, key ARN, alias name, or alias ARN. When using an alias name, prefix it with "alias/". To specify a KMS key in a different Amazon Web Services 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 KMS key, use ListKeys or DescribeKey. To get the alias name and alias ARN, use ListAliases.

  • grant_tokens (Optional[GrantTokenList], default: None ) –

    A list of grant tokens.

    Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. For more information, see Grant token and Using a grant token in the Key Management Service Developer Guide.

Raises:

  • DependencyTimeoutException –

    The system timed out while trying to fulfill the request. You can retry the request.

  • InvalidArnException –

    The request was rejected because a specified ARN, or an ARN in a key policy, is not valid.

  • KMSInternalException –

    The request was rejected because an internal exception occurred. The request can be retried.

  • NotFoundException –

    The request was rejected because the specified entity or resource could not be found.

  • UnknownServiceError –

    The service returned an error code this client does not model.

Examples:

To get details about a KMS key in an AWS CloudHSM key store The following example gets the metadata of a KMS key in an AWS CloudHSM key store.

>>> await client.describe_key(key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab')
To get details about a KMS key in an external key store
The following example gets the metadata of a KMS key in an external key store.

>>> await client.describe_key(key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab')
To get details about a multi-Region key
The following example gets metadata for a multi-Region replica key. This multi-Region key is a symmetric encryption key. DescribeKey returns information about the primary key and all of its replicas.

>>> await client.describe_key(key_id='arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab')
To get details about an HMAC KMS key
The following example gets the metadata of an HMAC KMS key.

>>> await client.describe_key(key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab')
To get details about an RSA asymmetric KMS key
The following example gets metadata for an asymmetric RSA KMS key used for signing and verification.

>>> await client.describe_key(key_id='1234abcd-12ab-34cd-56ef-1234567890ab')
Source code in docs_src/capo_kms/_services/async_kms.py 
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
async def describe_key(
    self,
    key_id: "capo_kms.types.key_id_type.KeyIdType",
    *,
    config_overrides: Optional[AsyncKMSClientConfig] = None,
    grant_tokens: Optional["capo_kms.types.grant_token_list.GrantTokenList"] = None,
) -> "capo_kms.types.describe_key_response.DescribeKeyResponse":
    """<p>Provides detailed information about a KMS key. You can run <code>DescribeKey</code> on a <a href="https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-mgn-key">customer managed key</a> or an <a href="https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-key">Amazon Web Services managed key</a>.</p> <p>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. It includes fields, like <code>KeySpec</code>, that help you distinguish different types of KMS keys. It also displays the key usage (encryption, signing, or generating and verifying MACs) and the algorithms that the KMS key supports. </p> <p>For <a href="https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html">multi-Region keys</a>, <code>DescribeKey</code> displays the primary key and all related replica keys. For KMS keys in <a href="https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html">CloudHSM key stores</a>, it includes information about the key store, such as the key store ID and the CloudHSM cluster ID. For KMS keys in <a href="https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html">external key stores</a>, it includes the custom key store ID and the ID of the external key.</p> <p> <code>DescribeKey</code> does not return the following information:</p> <ul> <li> <p>Aliases associated with the KMS key. To get this information, use <a>ListAliases</a>.</p> </li> <li> <p>Whether automatic key rotation is enabled on the KMS key. To get this information, use <a>GetKeyRotationStatus</a>. Also, some key states prevent a KMS key from being automatically rotated. For details, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotate-keys-how-it-works">How key rotation works</a> in the <i>Key Management Service Developer Guide</i>.</p> </li> <li> <p>Tags on the KMS key. To get this information, use <a>ListResourceTags</a>.</p> </li> <li> <p>Key policies and grants on the KMS key. To get this information, use <a>GetKeyPolicy</a> and <a>ListGrants</a>.</p> </li> </ul> <p>In general, <code>DescribeKey</code> is a non-mutating operation. It returns data about KMS keys, but doesn't change them. However, Amazon Web Services services use <code>DescribeKey</code> to create <a href="https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-key">Amazon Web Services managed keys</a> from a <i>predefined Amazon Web Services alias</i> with no key ID.</p> <p> <b>Cross-account use</b>: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify the key ARN or alias ARN in the value of the <code>KeyId</code> parameter.</p> <p> <b>Required permissions</b>: <a href="https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html">kms:DescribeKey</a> (key policy)</p> <p> <b>Related operations:</b> </p> <ul> <li> <p> <a>GetKeyPolicy</a> </p> </li> <li> <p> <a>GetKeyRotationStatus</a> </p> </li> <li> <p> <a>ListAliases</a> </p> </li> <li> <p> <a>ListGrants</a> </p> </li> <li> <p> <a>ListKeys</a> </p> </li> <li> <p> <a>ListResourceTags</a> </p> </li> <li> <p> <a>ListRetirableGrants</a> </p> </li> </ul> <p> <b>Eventual consistency</b>: The KMS API follows an eventual consistency model. For more information, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/accessing-kms.html#programming-eventual-consistency">KMS eventual consistency</a>.</p>

    Args:
        key_id: <p>Describes the specified KMS key. </p> <p>If you specify a predefined Amazon Web Services alias (an Amazon Web Services alias with no key ID), KMS associates the alias with an <a href="https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-key">Amazon Web Services managed key</a> and returns its <code>KeyId</code> and <code>Arn</code> in the response.</p> <p>To specify a KMS key, use its key ID, key ARN, alias name, or alias ARN. When using an alias name, prefix it with <code>"alias/"</code>. To specify a KMS key in a different Amazon Web Services account, you must use the key ARN or alias ARN.</p> <p>For example:</p> <ul> <li> <p>Key ID: <code>1234abcd-12ab-34cd-56ef-1234567890ab</code> </p> </li> <li> <p>Key ARN: <code>arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab</code> </p> </li> <li> <p>Alias name: <code>alias/ExampleAlias</code> </p> </li> <li> <p>Alias ARN: <code>arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias</code> </p> </li> </ul> <p>To get the key ID and key ARN for a KMS key, use <a>ListKeys</a> or <a>DescribeKey</a>. To get the alias name and alias ARN, use <a>ListAliases</a>.</p>
        grant_tokens: <p>A list of grant tokens.</p> <p>Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved <i>eventual consistency</i>. For more information, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#grant_token">Grant token</a> and <a href="https://docs.aws.amazon.com/kms/latest/developerguide/using-grant-token.html">Using a grant token</a> in the <i>Key Management Service Developer Guide</i>.</p>

    Raises:
        capo_kms.errors.dependency_timeout_exception.DependencyTimeoutException: <p>The system timed out while trying to fulfill the request. You can retry the request.</p>
        capo_kms.errors.invalid_arn_exception.InvalidArnException: <p>The request was rejected because a specified ARN, or an ARN in a key policy, is not valid.</p>
        capo_kms.errors.kms_internal_exception.KMSInternalException: <p>The request was rejected because an internal exception occurred. The request can be retried.</p>
        capo_kms.errors.not_found_exception.NotFoundException: <p>The request was rejected because the specified entity or resource could not be found.</p>
        capo_kms.errors.UnknownServiceError: The service returned an error code this client does not model.

    Examples:
        To get details about a KMS key in an AWS CloudHSM key store
        The following example gets the metadata of a KMS key in an AWS CloudHSM key store.

        >>> await client.describe_key(key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab')
        To get details about a KMS key in an external key store
        The following example gets the metadata of a KMS key in an external key store.

        >>> await client.describe_key(key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab')
        To get details about a multi-Region key
        The following example gets metadata for a multi-Region replica key. This multi-Region key is a symmetric encryption key. DescribeKey returns information about the primary key and all of its replicas.

        >>> await client.describe_key(key_id='arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab')
        To get details about an HMAC KMS key
        The following example gets the metadata of an HMAC KMS key.

        >>> await client.describe_key(key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab')
        To get details about an RSA asymmetric KMS key
        The following example gets metadata for an asymmetric RSA KMS key used for signing and verification.

        >>> await client.describe_key(key_id='1234abcd-12ab-34cd-56ef-1234567890ab')
    """

    async def _handler(
        req: "AsyncOperationRequest[capo_kms.types.describe_key_request.DescribeKeyRequest]",
    ) -> AsyncOperationResponse[
        "capo_kms.types.describe_key_response.DescribeKeyResponse"
    ]:
        import capo_kms._operations.trent_service.describe_key

        (
            output,
            http_response,
        ) = await capo_kms._operations.trent_service.describe_key.async_describe_key(
            req.options, req.input
        )
        return AsyncOperationResponse(output=output, response=http_response)

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("DescribeKey")
    )
    input_: capo_kms.types.describe_key_request.DescribeKeyRequest = {
        "key_id": key_id
    }
    if grant_tokens is not None:
        input_["grant_tokens"] = grant_tokens

    response = await aexecute_pipeline(
        AsyncOperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    await response.response.aclose()
    return response.output