Destroying and restoring key versions

A key version has a state which determines if its key material exists.

A key version which is enabled or disabled can move to scheduled for destruction using DestroyCryptoKeyVersion, client library methods that map to DestroyCryptoKeyVersion, gcloud kms keys versions destroy, or the Google Cloud Platform Console. A key version which is scheduled for destruction can move to disabled using RestoreCryptoKeyVersion, client library methods that map to RestoreCryptoKeyVersion, gcloud kms keys versions restore, and the Google Cloud Platform Console.

To modify the state of a key version, a user needs the appropriate Cloud Identity and Access Management role or permission.

  • The pre-defined roles roles/cloudkms.admin or roles/owner can schedule a key version for destruction and can restore a key version that is scheduled for destruction.

  • A custom role that contains the cloudkms.cryptoKeyVersions.destroy permission can schedule a key version for destruction.

  • A custom role that contains the cloudkms.cryptoKeyVersions.restore permission can restore a key version that is scheduled for destruction.

Schedule a key version for destruction (Destroy a key version)

Only key versions which are enabled or disabled can be scheduled for destruction.

To prevent accidents, and damage from malicious individuals, when DestroyCryptoKeyVersion is used, the key material is NOT immediately destroyed. Rather, the key version moves to scheduled for destruction for 24 hours, after which it is automatically destroyed. There is no way to override this safety fallback.

Destruction is removal of the key material, but a record of the version still exists (e.g., the version number cannot be reused). This is NOT reversible - any data encrypted with this version will not be recoverable.

Console

  1. Go to the Cryptographic Keys page in the GCP Console.
    Go to the Cryptographic Keys page

  2. Click the name of the key ring that contains the key whose key version you will schedule for destruction.

  3. Click the key whose key version you want to schedule for destruction.

  4. Click the key version that you want to schedule for destruction.

  5. Click Destroy.

  6. When prompted to confirm the scheduling of the key version for destruction, enter the key name and then click Schedule Destruction.

Command-line

Destroy version 42 of key answer in key ring answers in the global location.

gcloud kms keys versions destroy 42 --location global \
  --keyring answers --key answer

C#

      public static void DestroyCryptoKeyVersion(string projectId, string locationId, string keyRingId, string cryptoKeyId, string versionId)
      {
          KeyManagementServiceClient client = KeyManagementServiceClient.Create();

          // The CryptoKeyVersion to destroy.
          CryptoKeyVersionName versionName =
              new CryptoKeyVersionName(projectId, locationId, keyRingId, cryptoKeyId, versionId);

          CryptoKeyVersion result = client.DestroyCryptoKeyVersion(versionName);

          Console.Write($"Destroyed Crypto Key Version: {result.Name}");
      }

Go

import (
	"context"
	"fmt"
	"io"

	cloudkms "cloud.google.com/go/kms/apiv1"
	kmspb "google.golang.org/genproto/googleapis/cloud/kms/v1"
)

// destroyCryptoKeyVersion marks a specified key version for deletion.
// The key can be restored if requested within 24 hours.
func destroyCryptoKeyVersion(w io.Writer, name string) error {
	// name := "projects/PROJECT_ID/locations/global/keyRings/RING_ID/cryptoKeys/KEY_ID/cryptoKeyVersions/1"
	ctx := context.Background()
	client, err := cloudkms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("cloudkms.NewKeyManagementClient: %v", err)
	}
	// Build the request.
	req := &kmspb.DestroyCryptoKeyVersionRequest{
		Name: name,
	}
	// Call the API.
	result, err := client.DestroyCryptoKeyVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("DestroyCryptoKeyVersion: %v", err)
	}
	fmt.Fprintf(w, "Destroyed crypto key version: %s", result)
	return nil
}

Java


/**
 * Marks the given version of a crypto key to be destroyed at a scheduled future point.
 */
public static CryptoKeyVersion destroyCryptoKeyVersion(
    String projectId, String locationId, String keyRingId, String cryptoKeyId, String version)
    throws IOException {

  // Create the Cloud KMS client.
  try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {

    // The resource name of the cryptoKey version
    String versionName = CryptoKeyVersionName.format(
        projectId, locationId, keyRingId, cryptoKeyId, version);

    // Destroy the cryptoKey version
    CryptoKeyVersion destroyed = client.destroyCryptoKeyVersion(versionName);

    return destroyed;
  }
}

Node.js

async function destroyCryptoKeyVersion(
  projectId = 'your-project-id', // Your GCP projectId
  keyRingId = 'my-key-ring', // Name of the crypto key version's key ring
  cryptoKeyId = 'my-key', // Name of the version's crypto key
  version = 1234 // The version's id
) {
  // Import the library and create a client
  const kms = require('@google-cloud/kms');
  const client = new kms.KeyManagementServiceClient();

  // The location of the crypto key versions's key ring, e.g. "global"
  const locationId = 'global';

  // Get the full path to the crypto key version
  const name = client.cryptoKeyVersionPath(
    projectId,
    locationId,
    keyRingId,
    cryptoKeyId,
    version
  );

  // destroys a crypto key version
  const [result] = await client.destroyCryptoKeyVersion({name});
  console.log(`Crypto key version ${result.name} destroyed.`);
}

PHP

use Google\Cloud\Kms\V1\KeyManagementServiceClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $locationId = 'The location ID of the crypto key. Can be "global", "us-west1", etc.';
// $keyRingId = 'The KMS key ring ID';
// $cryptoKeyId = 'The KMS key ID';
// $version = 'The KMS key version number';

$kms = new KeyManagementServiceClient();

// The resource name of the Crypto Key version.
$cryptoKeyVersionName = $kms->cryptoKeyVersionName($projectId, $locationId, $keyRingId, $cryptoKeyId, $version);

// Get the CryptoKey.
$cryptoKeyVersion = $kms->destroyCryptoKeyVersion($cryptoKeyVersionName);

printf('Destroyed version %s for cryptoKey %s in keyRing %s' . PHP_EOL, $version, $cryptoKeyId, $keyRingId);

Python

def destroy_crypto_key_version(
        project_id, location_id, key_ring_id, crypto_key_id, version_id):
    """Schedules a CryptoKeyVersion associated with a given CryptoKey and
    KeyRing for destruction 24 hours in the future."""

    from google.cloud import kms_v1

    # Creates an API client for the KMS API.
    client = kms_v1.KeyManagementServiceClient()

    # Construct the resource name of the CryptoKeyVersion.
    name = client.crypto_key_version_path(project_id, location_id, key_ring_id,
                                          crypto_key_id, version_id)

    # Use the KMS API to mark the CryptoKeyVersion for destruction.
    response = client.destroy_crypto_key_version(name)

    # Print results
    print('CryptoKeyVersion {}\'s state has been set to {}.'.format(
        name, response.state))

Ruby

# project_id    = "Your Google Cloud project ID"
# location_id   = "The location of the key ring"
# key_ring_id   = "The ID of the key ring"
# crypto_key_id = "The ID of the crypto key"
# version_id    = "Version of the crypto key"

require "google/cloud/kms/v1"
CloudKMS = Google::Cloud::Kms::V1

# Initialize the client
client = CloudKMS::KeyManagementServiceClient.new

# The crypto key version to destroy
version = CloudKMS::KeyManagementServiceClient.crypto_key_version_path(
  project_id, location_id, key_ring_id, crypto_key_id, version_id
)

# Destroy the crypto key version
destroyed = client.destroy_crypto_key_version version

puts "Destroyed version #{version_id} of #{crypto_key_id}"

For an example of how to receive an alert when a key version is scheduled for destruction, see Using Stackdriver Monitoring with Cloud KMS.

Restore a key version

A key version which is scheduled for destruction can be restored, so that it is not automatically destroyed. This moves the key version from scheduled for destruction to disabled.

Console

  1. Go to the Cryptographic Keys page in the GCP Console.
    Go to the Cryptographic Keys page

  2. Click the name of the key ring that contains the key whose key version you want to restore.

  3. Click the key whose key version you want to restore.

  4. Click the key version that you want to restore.

  5. Click Restore.

  6. When prompted to confirm restoration of the key version, click Restore.

Command-line

Restore version 42 of key answer in key ring answers in the global location.

gcloud kms keys versions restore 42 --location global \
  --keyring answers --key answer

C#

      public static void RestoreCryptoKeyVersion(string projectId, string locationId, string keyRingId, string cryptoKeyId, string versionId)
      {
          KeyManagementServiceClient client = KeyManagementServiceClient.Create();

          // The CryptoKeyVersion to restore.
          CryptoKeyVersionName versionName =
              new CryptoKeyVersionName(projectId, locationId, keyRingId, cryptoKeyId, versionId);

          CryptoKeyVersion result = client.RestoreCryptoKeyVersion(versionName);

          Console.Write($"Restored Crypto Key Version: {result.Name}");
      }

Go

import (
	"context"
	"fmt"
	"io"

	cloudkms "cloud.google.com/go/kms/apiv1"
	kmspb "google.golang.org/genproto/googleapis/cloud/kms/v1"
)

// restoreCryptoKeyVersion attempts to recover a key that has been marked for destruction within the last 24 hours.
func restoreCryptoKeyVersion(w io.Writer, keyVersionName string) error {
	// keyVersionName := "projects/PROJECT_ID/locations/global/keyRings/RING_ID/cryptoKeys/KEY_ID/cryptoKeyVersions/1"
	ctx := context.Background()
	client, err := cloudkms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("cloudkms.NewKeyManagementClient: %v", err)
	}
	// Build the request.
	req := &kmspb.RestoreCryptoKeyVersionRequest{
		Name: keyVersionName,
	}
	// Call the API.
	result, err := client.RestoreCryptoKeyVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("RestoreCryptoKeyVersion: %v", err)
	}
	fmt.Fprintf(w, "Restored crypto key version: %s", result)
	return nil
}

Java


/**
 * Restores the given version of a crypto key that is currently scheduled for destruction.
 */
public static CryptoKeyVersion restoreCryptoKeyVersion(
    String projectId, String locationId, String keyRingId, String cryptoKeyId, String version)
    throws IOException {

  // Create the Cloud KMS client.
  try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {

    // The resource name of the cryptoKey version
    String versionName = CryptoKeyVersionName.format(
        projectId, locationId, keyRingId, cryptoKeyId, version);

    CryptoKeyVersion restored = client.restoreCryptoKeyVersion(versionName);

    return restored;
  }
}

Node.js

async function restoreCryptoKeyVersion(
  projectId = 'your-project-id', // Your GCP projectId
  keyRingId = 'my-key-ring', // Name of the crypto key version's key ring
  cryptoKeyId = 'my-key', // Name of the version's crypto key
  version = 1234 // The version's id
) {
  // Import the library and create a client
  const kms = require('@google-cloud/kms');
  const client = new kms.KeyManagementServiceClient();

  // The location of the crypto key versions's key ring, e.g. "global"
  const locationId = 'global';

  // Get the full path to the crypto key version
  const name = client.cryptoKeyVersionPath(
    projectId,
    locationId,
    keyRingId,
    cryptoKeyId,
    version
  );

  // restores a crypto key version
  const [result] = await client.restoreCryptoKeyVersion({name});
  console.log(`Crypto key version ${result.name} restored.`);
}

PHP

use Google\Cloud\Kms\V1\KeyManagementServiceClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $locationId = 'The location ID of the crypto key. Can be "global", "us-west1", etc.';
// $keyRingId = 'The KMS key ring ID';
// $cryptoKeyId = 'The KMS key ID';
// $version = 'The KMS key version number';

$kms = new KeyManagementServiceClient();

// The resource name of the Crypto Key version.
$cryptoKeyVersionName = $kms->cryptoKeyVersionName($projectId, $locationId, $keyRingId, $cryptoKeyId, $version);

// Get the CryptoKey.
$cryptoKeyVersion = $kms->restoreCryptoKeyVersion($cryptoKeyVersionName);

printf('Restored version %s for cryptoKey %s in keyRing %s' . PHP_EOL, $version, $cryptoKeyId, $keyRingId);

Python

def restore_crypto_key_version(
        project_id, location_id, key_ring_id, crypto_key_id, version_id):
    """Restores a CryptoKeyVersion that is scheduled for destruction."""

    from google.cloud import kms_v1

    # Creates an API client for the KMS API.
    client = kms_v1.KeyManagementServiceClient()

    # Construct the resource name of the CryptoKeyVersion.
    name = client.crypto_key_version_path(project_id, location_id, key_ring_id,
                                          crypto_key_id, version_id)

    # Use the KMS API to restore the CryptoKeyVersion.
    response = client.restore_crypto_key_version(name)

    # Print results
    print('CryptoKeyVersion {}\'s state has been set to {}.'.format(
        name, response.state))

Ruby

# project_id    = "Your Google Cloud project ID"
# location_id   = "The location of the key ring"
# key_ring_id   = "The ID of the key ring"
# crypto_key_id = "The ID of the crypto key"
# version_id    = "Version of the crypto key"

require "google/cloud/kms/v1"
CloudKMS = Google::Cloud::Kms::V1

# Initialize the client
client = CloudKMS::KeyManagementServiceClient.new

# The crypto key version to restore
version = CloudKMS::KeyManagementServiceClient.crypto_key_version_path(
  project_id, location_id, key_ring_id, crypto_key_id, version_id
)

# Restore the crypto key version
restored = client.restore_crypto_key_version version

puts "Restored version #{version_id} of #{crypto_key_id}"

Оцените, насколько информация на этой странице была вам полезна:

Оставить отзыв о...

Текущей странице