DescribeKey
Gets detailed information about a KMS key.
Description
The `DescribeKey` operation provides detailed information about a KMS key. This operation works for all types of KMS keys, including symmetric and asymmetric keys, and keys in custom key stores.
note
- If you use the `KeyId` parameter, the operation provides information about that specific KMS key.
- If you use the `KeyArn` parameter, the operation provides information about the KMS key specified in the ARN.
- For symmetric keys, this operation provides information about the key material and its rotation status.
- For asymmetric keys, this operation includes information about the key spec, key usage, and public key.
Request Syntax
Headers
| Name | Description | Required | Type |
|---|---|---|---|
| Content-Type | Must be "application/x-amz-json-1.1" | Yes | string |
| X-Amz-Target | Must be "TrentService.DescribeKey" | Yes | string |
Request Body
| Name | Description | Required | Type |
|---|---|---|---|
| KeyId | The identifier of the KMS key you want to describe. This can be the key ID or key ARN of the KMS key. | Yes | string |
| GrantTokens | A list of grant tokens that represent grants that can be used to access the KMS key. | No | array[string] |
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.DescribeKey
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
}
Values in italics indicate user input and should be replaced with actual values.
Response Elements
| Name | Description | Required | Type |
|---|---|---|---|
| KeyMetadata | Metadata about the KMS key. | No | String |
Examples
Example 1: Describe a symmetric encryption KMS key
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.DescribeKey
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
}
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
{
"KeyMetadata": {
"AWSAccountId": "111122223333",
"Arn": "arn:verenc:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": "2023-12-01T00:00:00-07:00",
"Description": "Example symmetric encryption key",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Origin": "AWS_KMS",
"MultiRegion": false
}
}
Values in italics indicate variable response values.
Special Errors
| Error Code | Description |
|---|---|
| DependencyTimeoutException | The system timed out while trying to fulfill the request. |
| InvalidArnException | The request was rejected because a specified ARN was not valid. |
| InvalidGrantTokenException | The request was rejected because the specified grant token is not valid. |
| KMSInternalException | The request was rejected because an internal error occurred. |
| KMSInvalidStateException | The request was rejected because the key state is not valid for this operation. |
| NotFoundException | The request was rejected because the specified key was not found. |
Permissions
To use the `DescribeKey` operation, you must have the following permissions:
- `kms:DescribeKey` on the KMS key
Try It Out
Test DescribeKey
Get detailed information about a KMS key.
Coming Soon
This feature is currently under development and will be available soon.