Contact UsGet started

Key Management Service API, REST: SymmetricKey.Get

Written by
Updated at December 17, 2024

Returns the specified symmetric KMS key.

To get the list of available symmetric KMS keys, make a SymmetricKeyService.List request.

HTTP request

GET https://kms.api.cloud.yandex.net/kms/v1/keys/{keyId}

Path parameters

Field

Description

keyId

string

Required field. ID of the symmetric KMS key to return.
To get the ID of a symmetric KMS key use a SymmetricKeyService.List request.

Response

HTTP Code: 200 - OK

{
  "id": "string",
  "folderId": "string",
  "createdAt": "string",
  "name": "string",
  "description": "string",
  "labels": "object",
  "status": "string",
  "primaryVersion": {
    "id": "string",
    "keyId": "string",
    "status": "string",
    "algorithm": "string",
    "createdAt": "string",
    "primary": "boolean",
    "destroyAt": "string",
    "hostedByHsm": "boolean"
  },
  "defaultAlgorithm": "string",
  "rotatedAt": "string",
  "rotationPeriod": "string",
  "deletionProtection": "boolean"
}

A symmetric KMS key that may contain several versions of the cryptographic material.

Field

Description

id

string

ID of the key.

folderId

string

ID of the folder that the key belongs to.

createdAt

string (date-time)

Time when the key was created.

String in RFC3339 text format. The range of possible values is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the
Protocol Buffers reference.
In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).

name

string

Name of the key.

description

string

Description of the key.

labels

object (map<string, string>)

Custom labels for the key as key:value pairs. Maximum 64 per key.

status

enum (Status)

Current status of the key.

  • STATUS_UNSPECIFIED
  • CREATING: The key is being created.
  • ACTIVE: The key is active and can be used for encryption and decryption.
    Can be set to INACTIVE using the SymmetricKeyService.Update method.
  • INACTIVE: The key is inactive and unusable.
    Can be set to ACTIVE using the SymmetricKeyService.Update method.

primaryVersion

SymmetricKeyVersion

Primary version of the key, used as the default for all encrypt/decrypt operations,
when no version ID is specified.

defaultAlgorithm

enum (SymmetricAlgorithm)

Default encryption algorithm to be used with new versions of the key.

  • SYMMETRIC_ALGORITHM_UNSPECIFIED
  • AES_128: AES algorithm with 128-bit keys.
  • AES_192: AES algorithm with 192-bit keys.
  • AES_256: AES algorithm with 256-bit keys.
  • AES_256_HSM: AES algorithm with 256-bit keys hosted by HSM

rotatedAt

string (date-time)

Time of the last key rotation (time when the last version was created).
Empty if the key does not have versions yet.

String in RFC3339 text format. The range of possible values is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the
Protocol Buffers reference.
In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).

rotationPeriod

string (duration)

Time period between automatic key rotations.

deletionProtection

boolean

Flag that inhibits deletion of the key

SymmetricKeyVersion

Symmetric KMS key version: metadata about actual cryptographic data.

Field

Description

id

string

ID of the key version.

keyId

string

ID of the symmetric KMS key that the version belongs to.

status

enum (Status)

Status of the key version.

  • STATUS_UNSPECIFIED
  • ACTIVE: The version is active and can be used for encryption and decryption.
  • SCHEDULED_FOR_DESTRUCTION: The version is scheduled for destruction, the time when it will be destroyed
    is specified in the SymmetricKeyVersion.destroyAt field.
  • DESTROYED: The version is destroyed and cannot be recovered.

algorithm

enum (SymmetricAlgorithm)

Encryption algorithm that should be used when using the key version to encrypt plaintext.

  • SYMMETRIC_ALGORITHM_UNSPECIFIED
  • AES_128: AES algorithm with 128-bit keys.
  • AES_192: AES algorithm with 192-bit keys.
  • AES_256: AES algorithm with 256-bit keys.
  • AES_256_HSM: AES algorithm with 256-bit keys hosted by HSM

createdAt

string (date-time)

Time when the key version was created.

String in RFC3339 text format. The range of possible values is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the
Protocol Buffers reference.
In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).

primary

boolean

Indication of a primary version, that is to be used by default for all cryptographic
operations that don't have a key version explicitly specified.

destroyAt

string (date-time)

Time when the key version is going to be destroyed. Empty unless the status
is SCHEDULED_FOR_DESTRUCTION.

String in RFC3339 text format. The range of possible values is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the
Protocol Buffers reference.
In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).

hostedByHsm

boolean

Indication of the version that is hosted by HSM.
Previous
Create
Next
List