Contact UsGet started

Key version control

Written by
Updated at October 17, 2024

You can make key versions primary (a primary key version is used for encryption and decryption by default) and destroy them. To create a new key version, rotate the key.

Make a version primary

To make a version primary:

  1. Log in to the management console.
  2. Select Key Management Service.
  3. In the left-hand panel, select Symmetric keys.
  4. Click the key you need in the list to open its attribute page.
  5. In the line of the appropriate version, click and select Make primary.

  1. Get a list of versions for the desired key:

    yc kms symmetric-key list-versions example-key

    Result:

    +----------------------+---------+--------+-----------+
|          ID          | PRIMARY | STATUS | ALGORITHM |
+----------------------+---------+--------+-----------+
| abjhduu82ao0******** | true    | ACTIVE | AES_128   |
| abj8cvn99nam******** | false   | ACTIVE | AES_128   |
| abjed9ciau8e******** | false   | ACTIVE | AES_256   |
| abjvejjvfktq******** | false   | ACTIVE | AES_128   |
+----------------------+---------+--------+-----------+

  2. Change the key version by specifying the ID of the desired version:

    yc kms symmetric-key set-primary-version example-key-1 \
  --version-id abj8cvn99nam********

Use the setPrimaryVersion REST API method for the SymmetricKey resource or the SymmetricKeyService/SetPrimaryVersion gRPC API call.

The next encryption or decryption request omitting the key version will use the new primary version.

Destroy a key version

You can't destroy a version immediately: you can only schedule its destruction (for the next day at least).

Alert

At the scheduled time and date, the key version is permanently destroyed: if you still have data encrypted with this key version, you can no longer decrypt it.

To destroy a version:

  1. Log in to the management console.
  2. Select Key Management Service.
  3. In the left-hand panel, select Symmetric keys.
  4. Click the desired key in the list to open its attribute page.
  5. In the line of the appropriate version, click and select Schedule destruction.

The version will change its status to Scheduled for destruction, and the Destruction date column will show the date the destruction is scheduled for.

To destroy a version:

  1. Get a list of versions for the desired key:

    yc kms symmetric-key list-versions example-key

    Result:

    +----------------------+---------+--------+-----------+
|          ID          | PRIMARY | STATUS | ALGORITHM |
+----------------------+---------+--------+-----------+
| abj8cvn99nam******** | true    | ACTIVE | AES_128   |
| abjed9ciau8e******** | false   | ACTIVE | AES_256   |
| abjhduu82ao0******** | false   | ACTIVE | AES_128   |
| abjvejjvfktq******** | false   | ACTIVE | AES_128   |
+----------------------+---------+--------+-----------+

  2. Schedule the destruction of a version:

    yc kms symmetric-key schedule-version-destruction example-key \
  --version-id abjed9ciau8e********

    The status of the version switches to SCHEDULED_FOR_DESTRUCTION and the destroy_at field shows the time when destruction is scheduled for.

Use the scheduleVersionDestruction REST API method for the SymmetricKey resource or the SymmetricKeyService/ScheduleVersionDestruction gRPC API call.

Cancel version destruction

If you scheduled the destruction of a key version, you can cancel it before the scheduled date:

  1. Log in to the management console.
  2. Select Key Management Service.
  3. In the left-hand panel, select Symmetric keys.
  4. Click the desired key in the list to open its attribute page.
  5. In the line of the appropriate version, click and select Cancel destruction.

The version reverts to the ACTIVE status.

  1. Get a list of versions for the desired key:

    yc kms symmetric-key list-versions example-key

    Result:

    +----------------------+---------+---------------------------+-----------+
|          ID          | PRIMARY |          STATUS           | ALGORITHM |
+----------------------+---------+---------------------------+-----------+
| abj8cvn99nam******** | true    | ACTIVE                    | AES_128   |
| abjed9ciau8e******** | false   | SCHEDULED_FOR_DESTRUCTION | AES_256   |
| abjhduu82ao0******** | false   | ACTIVE                    | AES_128   |
| abjvejjvfktq******** | false   | ACTIVE                    | AES_128   |
+----------------------+---------+---------------------------+-----------+

  2. Cancel the destruction of a version:

    yc kms symmetric-key cancel-version-destruction example-key \
  --version-id abjed9ciau8e********

    The version reverts to the ACTIVE status.

Use the cancelVersionDestruction REST API method for the SymmetricKey resource or the SymmetricKeyService/CancelVersionDestruction gRPC API call.

Previous
Key
Next
Data encryption