Re-encrypting data

This topic shows how to re-encrypt data. If you suspect unauthorized use of a key, you should re-encrypt the data protected by that key and then disable or schedule destruction of the prior key version.

Before you begin

This scenario requires the following conditions.

  • You have already encrypted data using Cloud KMS.

  • The key version used for the encryption is not disabled, scheduled for destruction, or destroyed. You use this key version to decrypt the encrypted data.

  • You have already rotated keys. A key rotation creates a new primary key version. You use the new primary key version to re-encrypt the data.

Re-encrypting data workflow

Use the following steps to re-encrypt data and disable or schedule destruction of the key version used for the original encryption.

  1. Decrypt the data using the prior key version

  2. Re-encrypt the data using the new primary key version

  3. Disable or schedule destruction of the prior key version

Decrypt the data using the prior key version

Cloud KMS automatically uses the correct key version to decrypt data, as long as the key version is not disabled, scheduled for destruction, or destroyed. The following examples show how to decrypt the data. This is the same decryption code used in Encrypting and Decrypting.

Command-line

To decrypt data, provide the appropriate key information, specify the name of the encrypted file (ciphertext file) to decrypt, and specify the name of the file that will contain the decrypted content.

gcloud kms decrypt \
  --location=global \
  --keyring=my-key-ring \
  --key=my-key \
  --ciphertext-file=FILEPATH_AND_FILENAME_TO_DECRYPT \
  --plaintext-file=FILEPATH_AND_FILENAME_TO_DECRYPT.dec

The decrypt command supports an optional --additional-authenticated-data- file flag to specify a file that contains additional authenticated data. The additional authenticated data file must not be larger than 64 KiB.

If --ciphertext-file or --additional-authenticated-data-file is set to -, that file is read from stdin. Similarly, if --plaintext-file is set to -, the decrypted plaintext is written to stdout.

The following decrypt example shows how to specify additional authenticated data.

gcloud kms decrypt \
  --location=global \
  --keyring=my-key-ring \
  --key=my-key \
  --additional-authenticated-data-file=ADDITIONAL_AUTHENTICATED_DATA_FILEPATH_AND_FILENAME \
  --ciphertext-file=FILEPATH_AND_FILENAME_TO_DECRYPT \
  --plaintext-file=FILEPATH_AND_FILENAME_TO_DECRYPT.dec

Protocol

Decrypted text that is returned in the JSON from Cloud KMS is base64-encoded. For information on encoding and decoding using base64, see Base64 Encoding.

To decrypt encrypted data, make a POST request and provide the appropriate project and key information and specify the encrypted (cipher) text to be decrypted in the ciphertext field of the request body. Replace API_KEY with a valid API key. For information on generating an API key, see Accessing the API.

POST https://cloudkms.googleapis.com/v1/projects/project_id/locations/global/keyRings/keyring_name/cryptoKeys/cryptoKey_name:decrypt&key=API_KEY
{
  "ciphertext": "CiQAhMwwBo61cHas7dDgifrUFs5zNzBJ2uZtVFq4ZPEl6fUVT4kSmQ...",
}

Here is an example using curl:

curl -s -X POST "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/global/keyRings/KEYRING_NAME/cryptoKeys/CRYPTOKEY_NAME:decrypt" \
  -d "{\"ciphertext\":\"ENCRYPTED_CONTENT\"}" \
  -H "Authorization:Bearer API_KEY"\
  -H "Content-Type:application/json"

C#

        public static void Decrypt(string projectId, string locationId, string keyRingId, string cryptoKeyId,
    string ciphertextFile, string plaintextFile)
        {
            KeyManagementServiceClient client = KeyManagementServiceClient.Create();
            CryptoKeyName cryptoKeyName =
                new CryptoKeyName(projectId, locationId, keyRingId, cryptoKeyId);

            byte[] ciphertext = File.ReadAllBytes(ciphertextFile);
            DecryptResponse result = client.Decrypt(cryptoKeyName, ByteString.CopyFrom(ciphertext));

            // Output decrypted data to a file.
            File.WriteAllBytes(plaintextFile, result.Plaintext.ToByteArray());
            Console.Write($"Decrypted file created: {plaintextFile}");
        }

Go

// decrypt will decrypt the input ciphertext bytes using the specified symmetric key
// example keyName: "projects/PROJECT_ID/locations/global/keyRings/RING_ID/cryptoKeys/KEY_ID"
func decryptSymmetric(keyName string, ciphertext []byte) ([]byte, error) {
	ctx := context.Background()
	client, err := cloudkms.NewKeyManagementClient(ctx)
	if err != nil {
		return nil, err
	}

	// Build the request.
	req := &kmspb.DecryptRequest{
		Name:       keyName,
		Ciphertext: ciphertext,
	}
	// Call the API.
	resp, err := client.Decrypt(ctx, req)
	if err != nil {
		return nil, err
	}
	return resp.Plaintext, nil
}

Java

/**
 * Decrypts the provided ciphertext with the specified crypto key.
 */
public static byte[] decrypt(
    String projectId, String locationId, String keyRingId, String cryptoKeyId, byte[] ciphertext)
    throws IOException {

  // Create the KeyManagementServiceClient using try-with-resources to manage client cleanup.
  try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {

    // The resource name of the cryptoKey
    String resourceName = CryptoKeyName.format(projectId, locationId, keyRingId, cryptoKeyId);

    // Decrypt the ciphertext with Cloud KMS.
    DecryptResponse response = client.decrypt(resourceName, ByteString.copyFrom(ciphertext));

    // Extract the plaintext from the response.
    return response.getPlaintext().toByteArray();
  }
}

Node.js

async function decrypt(
  projectId = 'your-project-id', // Your GCP projectId
  keyRingId = 'my-key-ring', // Name of the crypto key's key ring
  cryptoKeyId = 'my-key', // Name of the crypto key, e.g. "my-key"
  ciphertextFileName = './path/to/plaintext.txt.encrypted',
  plaintextFileName = './path/to/plaintext.txt.decrypted'
) {
  const fs = require('fs');
  const {promisify} = require('util');

  // Import the library and create a client
  const kms = require('@google-cloud/kms');
  const client = new kms.KeyManagementServiceClient();

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

  // Reads the file to be decrypted
  const readFile = promisify(fs.readFile);
  const contentsBuffer = await readFile(ciphertextFileName);
  const name = client.cryptoKeyPath(
    projectId,
    locationId,
    keyRingId,
    cryptoKeyId
  );
  const ciphertext = contentsBuffer.toString('base64');

  // Decrypts the file using the specified crypto key
  const [result] = await client.decrypt({name, ciphertext});

  // Writes the decrypted file to disk
  const writeFile = promisify(fs.writeFile);
  await writeFile(plaintextFileName, Buffer.from(result.plaintext, 'base64'));
  console.log(
    `Decrypted ${ciphertextFileName}, result saved to ${plaintextFileName}.`
  );
}

PHP

use Google\Cloud\Kms\V1\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\CryptoKey;

/** 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';
// $ciphertextFileName = 'The path to the file containing ciphertext to decrypt';
// $plaintextFileName = 'The path to write the plaintext';

$kms = new KeyManagementServiceClient();

// The resource name of the CryptoKey.
$cryptoKey = new CryptoKey();
$cryptoKeyName = $kms->cryptoKeyName($projectId, $locationId, $keyRingId, $cryptoKeyId);

$ciphertext = file_get_contents($ciphertextFileName);
$response = $kms->decrypt($cryptoKeyName, $ciphertext);

// Write the encrypted text to a file.
file_put_contents($plaintextFileName, $response->getPlaintext());
printf('Saved decrypted text to %s' . PHP_EOL, $plaintextFileName);

Python

def decrypt_symmetric(project_id, location_id, key_ring_id, crypto_key_id,
                      ciphertext):
    """Decrypts input ciphertext using the provided symmetric CryptoKey."""

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

    # The resource name of the CryptoKey.
    name = client.crypto_key_path_path(project_id, location_id, key_ring_id,
                                       crypto_key_id)
    # Use the KMS API to decrypt the data.
    response = client.decrypt(name, ciphertext)
    return response.plaintext

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"
# ciphertext_file = "File to decrypt"
# plaintext_file  = "File to store decrypted data"

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

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

# The crypto key to use
crypto_key = CloudKMS::KeyManagementServiceClient.crypto_key_path(
    project_id, location_id, key_ring_id, crypto_key_id)

# Read the encrypted data from the file
ciphertext = File.open(ciphertext_file, 'rb'){ |f| f.read }

# Use the KMS API to decrypt the data
response = client.decrypt(crypto_key, ciphertext)

# Write the decrypted text to the output file
File.open(plaintext_file, 'wb'){ |f| f.write response.plaintext }

puts "Saved decrypted #{ciphertext_file} as #{plaintext_file}"

Re-encrypt the data using the new primary key version

Cloud KMS automatically uses the new primary key version to encrypt data. The following examples show how to encrypt the data. This is the same encryption code used in Encrypting and Decrypting.

Command-line

To encrypt data, provide the appropriate key information, specify the name of the plaintext file to encrypt, and specify the name of the file that will contain the encrypted content.

gcloud kms encrypt \
  --location=global  \
  --keyring=my-key-ring \
  --key=my-key \
  --plaintext-file=FILEPATH_AND_FILENAME_TO_ENCRYPT.dec \
  --ciphertext-file=FILEPATH_AND_FILENAME.enc

The plaintext file must not be larger than 64 KiB.

The encrypt command supports an optional --additional-authenticated-data-file flag to specify a file that contains additional authenticated data. The additional authenticated data file must not be larger than 64 KiB.

If --plaintext-file or --additional-authenticated-data-file is set to -, that file is read from stdin. Similarly, if --ciphertext-file is set to -, the ciphertext is written to stdout.

The encrypt command supports an optional --version flag to indicate the version of the key to use for encryption. By default, the primary version is used.

The following encrypt example shows how to specify a version key and additional authenticated data.

gcloud kms encrypt \
  --location=global  \
  --keyring=my-key-ring \
  --key=my-key \
  --version=my-key-version \
  --additional-authenticated-data-file=ADDITIONAL_AUTHENTICATED_DATA_FILEPATH_AND_FILENAME \
  --plaintext-file=FILEPATH_AND_FILENAME_TO_ENCRYPT.dec \
  --ciphertext-file=FILEPATH_AND_FILENAME.enc

Protocol

Content to be encrypted that is sent to Cloud KMS in JSON must be base64-encoded. For information on encoding and decoding using base64, see Base64 Encoding.

To encrypt data, make a POST request and provide the appropriate project and key information and specify the base64-encoded text to be encrypted in the plaintext field of the request body. Replace API_KEY with a valid API key. For information on generating an API key, see Accessing the API.

POST https://cloudkms.googleapis.com/v1/projects/project_id/locations/global/keyRings/keyring_name/cryptoKeys/cryptoKey_name:encrypt&key=API_KEY
{
  "plaintext": "BASE64_ENCODED_INPUT",
}

Here is an example using curl:

curl -s -X POST "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/global/keyRings/KEYRING_NAME/cryptoKeys/CRYPTOKEY_NAME:encrypt" \
  -d "{\"plaintext\":\"BASE64_ENCODED_INPUT\"}" \
  -H "Authorization:Bearer API_KEY"\
  -H "Content-Type:application/json"

C#

        public static void Encrypt(string projectId, string locationId, string keyRingId, string cryptoKeyId,
string plaintextFile, string ciphertextFile)
        {
            KeyManagementServiceClient client = KeyManagementServiceClient.Create();
            CryptoKeyName cryptoKeyName =
                new CryptoKeyName(projectId, locationId, keyRingId, cryptoKeyId);

            byte[] plaintext = File.ReadAllBytes(plaintextFile);
            CryptoKeyPathName pathName = CryptoKeyPathName.Parse(cryptoKeyName.ToString());
            EncryptResponse result = client.Encrypt(pathName, ByteString.CopyFrom(plaintext));

            // Output encrypted data to a file.
            File.WriteAllBytes(ciphertextFile, result.Ciphertext.ToByteArray());
            Console.Write($"Encrypted file created: {ciphertextFile}");
        }

Go

// encrypt will encrypt the input plaintext with the specified symmetric key
// example keyName: "projects/PROJECT_ID/locations/global/keyRings/RING_ID/cryptoKeys/KEY_ID"
func encryptSymmetric(keyName string, plaintext []byte) ([]byte, error) {
	ctx := context.Background()
	client, err := cloudkms.NewKeyManagementClient(ctx)
	if err != nil {
		return nil, err
	}

	// Build the request.
	req := &kmspb.EncryptRequest{
		Name:      keyName,
		Plaintext: plaintext,
	}
	// Call the API.
	resp, err := client.Encrypt(ctx, req)
	if err != nil {
		return nil, err
	}
	return resp.Ciphertext, nil
}

Java

/**
 * Encrypts the given plaintext using the specified crypto key.
 */
public static byte[] encrypt(
    String projectId, String locationId, String keyRingId, String cryptoKeyId, byte[] plaintext)
    throws IOException {

  // Create the KeyManagementServiceClient using try-with-resources to manage client cleanup.
  try (KeyManagementServiceClient client = KeyManagementServiceClient.create()) {

    // The resource name of the cryptoKey
    String resourceName = CryptoKeyName.format(projectId, locationId, keyRingId, cryptoKeyId);

    // Encrypt the plaintext with Cloud KMS.
    EncryptResponse response = client.encrypt(resourceName, ByteString.copyFrom(plaintext));

    // Extract the ciphertext from the response.
    return response.getCiphertext().toByteArray();
  }
}

Node.js

async function encrypt(
  projectId = 'your-project-id', // Your GCP projectId
  keyRingId = 'my-key-ring', // Name of the crypto key's key ring
  cryptoKeyId = 'my-key', // Name of the crypto key, e.g. "my-key"
  plaintextFileName = './path/to/plaintext.txt',
  ciphertextFileName = './path/to/plaintext.txt.encrypted'
) {
  const fs = require('fs');
  const {promisify} = require('util');

  // Import the library and create a client
  const kms = require('@google-cloud/kms');
  const client = new kms.KeyManagementServiceClient();

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

  // Reads the file to be encrypted
  const readFile = promisify(fs.readFile);
  const contentsBuffer = await readFile(plaintextFileName);
  const plaintext = contentsBuffer.toString('base64');
  const name = client.cryptoKeyPath(
    projectId,
    locationId,
    keyRingId,
    cryptoKeyId
  );

  // Encrypts the file using the specified crypto key
  const [result] = await client.encrypt({name, plaintext});
  const writeFile = promisify(fs.writeFile);
  await writeFile(ciphertextFileName, Buffer.from(result.ciphertext, 'base64'));
  console.log(`Encrypted ${plaintextFileName} using ${result.name}.`);
  console.log(`Result saved to ${ciphertextFileName}.`);
}

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';
// $plaintextFileName = 'The path to the file containing plaintext to encrypt';
// $ciphertextFileName = 'The path to write the ciphertext';

$kms = new KeyManagementServiceClient();

// The resource name of the CryptoKey.
$cryptoKeyName = $kms->cryptoKeyName($projectId, $locationId, $keyRingId, $cryptoKeyId);

$plaintext = file_get_contents($plaintextFileName);
$response = $kms->encrypt($cryptoKeyName, $plaintext);

// Write the encrypted text to a file.
file_put_contents($ciphertextFileName, $response->getCiphertext());
printf('Saved encrypted text to %s' . PHP_EOL, $ciphertextFileName);

Python

def encrypt_symmetric(project_id, location_id, key_ring_id, crypto_key_id,
                      plaintext):
    """Encrypts input plaintext data using the provided symmetric CryptoKey."""

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

    # The resource name of the CryptoKey.
    name = client.crypto_key_path_path(project_id, location_id, key_ring_id,
                                       crypto_key_id)

    # Use the KMS API to encrypt the data.
    response = client.encrypt(name, plaintext)
    return response.ciphertext

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"
# plaintext_file  = "File to encrypt"
# ciphertext_file = "File to store encrypted input data"

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

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

# The crypto key to use
crypto_key = CloudKMS::KeyManagementServiceClient.crypto_key_path(
    project_id, location_id, key_ring_id, crypto_key_id)

# Read the secret data from the file
plaintext = File.open(plaintext_file, 'rb'){ |f| f.read }

# Use the KMS API to encrypt the data
response = client.encrypt(crypto_key, plaintext)

# Write the encrypted binary data to the output file
File.open(ciphertext_file, 'wb'){ |f| f.write response.ciphertext }

puts "Saved encrypted #{plaintext_file} as #{ciphertext_file}"

Disable or schedule destruction of the prior key version

If you rotated your key in response to a suspected incident, after you have re-encrypted the data, disable or schedule destruction of the prior key version.

Disable an enabled key version

Only a key version which is Enabled can be Disabled. This is done with the method UpdateCryptoKeyVersion.

Command-line

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

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

C#

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

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

          CryptoKeyVersion version = client.GetCryptoKeyVersion(versionName);
          version.State = CryptoKeyVersion.Types.CryptoKeyVersionState.Disabled;

          FieldMask fieldMask = new FieldMask { Paths = { "state" } };

          CryptoKeyVersion patchResult = client.UpdateCryptoKeyVersion(version, fieldMask);

          Console.Write($"Disabled Crypto Key Version: {patchResult.Name}");
      }

Go

// disableCryptoKeyVersion disables a specified key version on KMS.
// example keyVersionName: "projects/PROJECT_ID/locations/global/keyRings/RING_ID/cryptoKeys/KEY_ID/cryptoKeyVersions/1"
func disableCryptoKeyVersion(keyVersionName string) error {
	ctx := context.Background()
	client, err := cloudkms.NewKeyManagementClient(ctx)
	if err != nil {
		return err
	}
	// Build the request.
	req := &kmspb.UpdateCryptoKeyVersionRequest{
		CryptoKeyVersion: &kmspb.CryptoKeyVersion{
			Name:  keyVersionName,
			State: kmspb.CryptoKeyVersion_DISABLED,
		},
		UpdateMask: &fieldmask.FieldMask{
			Paths: []string{"state"},
		},
	}
	// Call the API.
	result, err := client.UpdateCryptoKeyVersion(ctx, req)
	if err != nil {
		return err
	}
	log.Printf("Disabled crypto key version: %s", result)
	return nil
}

Java

/**
 * Disables the given version of the crypto key.
 */
public static CryptoKeyVersion disableCryptoKeyVersion(
    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);

    // Retrieve the current state
    CryptoKeyVersion current = client.getCryptoKeyVersion(versionName);

    // Build a copy that updates the state to disabled
    CryptoKeyVersion updated = CryptoKeyVersion.newBuilder()
        .setName(current.getName())
        .setState(CryptoKeyVersionState.DISABLED)
        .build();

    // Create a FieldMask that only allows 'state' to be updated
    FieldMask fieldMask = FieldMaskUtil.fromString(CryptoKeyVersion.class, "state");

    // Update the version state
    CryptoKeyVersion response = client.updateCryptoKeyVersion(updated, fieldMask);

    return response;
  }
}

Node.js

async function disableCryptoKeyVersion(
  projectId = 'your-project-id', // Your GCP Project ID
  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
  const name = client.cryptoKeyVersionPath(
    projectId,
    locationId,
    keyRingId,
    cryptoKeyId,
    version
  );

  // Gets a crypto key version
  const [cryptoKeyVersion] = await client.getCryptoKeyVersion({name});
  cryptoKeyVersion.state = 'DISABLED';

  // Disables a crypto key version
  const [result] = await client.updateCryptoKeyVersion({
    cryptoKeyVersion,
    updateMask: ['state'],
  });
  console.log(`Crypto key version ${result.name} disabled.`);
}

PHP

use Google\Cloud\Kms\V1\KeyManagementServiceClient;
use Google\Cloud\Kms\V1\CryptoKeyVersion\CryptoKeyVersionState;
use Google\Protobuf\FieldMask;

/** 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->getCryptoKeyVersion($cryptoKeyVersionName);
// Disable the cryptokey
$cryptoKeyVersion->setState(CryptoKeyVersionState::DISABLED);

$updateMask = new FieldMask();
$updateMask->setPaths(['state']);
$kms->updateCryptoKeyVersion($cryptoKeyVersion, $updateMask);

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

Python

def disable_crypto_key_version(project_id, location_id, key_ring_id,
                               crypto_key_id, version_id):
    """Disables a CryptoKeyVersion associated with a given CryptoKey and
    KeyRing."""

    # 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 disable the CryptoKeyVersion.
    new_state = enums.CryptoKeyVersion.CryptoKeyVersionState.DISABLED
    version = {'name': name, 'state': new_state}
    update_mask = {'paths': ["state"]}

    # Print results
    response = client.update_crypto_key_version(version, update_mask)
    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

# Retrieve the crypto key version to update
version_path = CloudKMS::KeyManagementServiceClient.crypto_key_version_path(
    project_id, location_id, key_ring_id, crypto_key_id, version_id)
version = client.get_crypto_key_version(version_path)

# Set the version state to disabled for update
version.state = CloudKMS::CryptoKeyVersion::CryptoKeyVersionState::DISABLED
update_mask = Google::Protobuf::FieldMask.new
update_mask.paths << "state"

# Disable the crypto key version
result = client.update_crypto_key_version(version, update_mask)

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

Schedule a key version for destruction

Only key versions which are Enabled or Disabled can be Scheduled for destruction. This is done with the method DestroyCryptoKeyVersion.

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. If you decide within 24 hours of scheduling the destruction that you do not want the destruction to occur, you can restore the key version.

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.

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

// destroyCryptoKeyVersion marks a specified key version for deletion. The key can be restored if requested within 24 hours.
// example keyVersionName: "projects/PROJECT_ID/locations/global/keyRings/RING_ID/cryptoKeys/KEY_ID/cryptoKeyVersions/1"
func destroyCryptoKeyVersion(keyVersionName string) error {
	ctx := context.Background()
	client, err := cloudkms.NewKeyManagementClient(ctx)
	if err != nil {
		return err
	}
	// Build the request.
	req := &kmspb.DestroyCryptoKeyVersionRequest{
		Name: keyVersionName,
	}
	// Call the API.
	result, err := client.DestroyCryptoKeyVersion(ctx, req)
	if err != nil {
		return err
	}
	log.Printf("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."""

    # 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}"

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud KMS Documentation