Enable and disable key versions

In Cloud KMS, the cryptographic key material that you use to encrypt, decrypt, sign, and verify data is stored in a key version. A key has zero or more key versions. When you rotate a key, you create a new key version.

This document shows how to disable a key version. During the time that a key is disabled, data that was encrypted with the key can't be accessed. To access the data, you can re-enable the key version.

Unless otherwise specified in the Service Health dashboard, disabling a key version is typically consistent within one minute. Enabling a key version is nearly instant. You can also manage access to a key version using Identity and Access Management (IAM). IAM operations are consistent within seconds. For more information, see Using IAM.

You can also permanently destroy a key version. Depending on your organization policies, you might need to disable a key version before you can destroy it. For more information see Control key version destruction.

Disable a key version

You can disable a key version in the enabled state. Before disabling a key version, we recommend that you check whether the key is still in use. You can view key usage tracking details for the key to see whether it is protecting CMEK resources. If any resources are protected by the key version that you want to disable, re-encrypt them with another key version before disabling the key.

Console

Go to the Key Management page in the Google Cloud console.

Go to the Key Management page
Click the name of the key ring that contains the key whose key version you will disable.
Click the key whose key version you want to disable.
Check the box next to the key version(s) that you want to disable.
Click Disable in the header.
In the confirmation prompt, click Disable.

gcloud

To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.

gcloud kms keys versions disable key-version \
    --key key \
    --keyring key-ring \
    --location location

Replace key-version with the version of the key to disable. Replace key with the name of the key. Replace key-ring with the name of the key ring where the key is located. Replace location with the Cloud KMS location for the key ring.

For information on all flags and possible values, run the command with the --help flag.

C#

To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.


using Google.Cloud.Kms.V1;
using Google.Protobuf.WellKnownTypes;

public class DisableKeyVersionSample
{
    public CryptoKeyVersion DisableKeyVersion(string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key", string keyVersionId = "123")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the key version.
        CryptoKeyVersion keyVersion = new CryptoKeyVersion
        {
            CryptoKeyVersionName = new CryptoKeyVersionName(projectId, locationId, keyRingId, keyId, keyVersionId),
            State = CryptoKeyVersion.Types.CryptoKeyVersionState.Disabled,
        };

        // Build the update mask.
        FieldMask fieldMask = new FieldMask
        {
            Paths = { "state" },
        };

        // Call the API.
        CryptoKeyVersion result = client.UpdateCryptoKeyVersion(keyVersion, fieldMask);

        // Return the result.
        return result;
    }
}

Go

To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.

import (
	"context"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
	fieldmask "google.golang.org/genproto/protobuf/field_mask"
)

// disableKeyVersion disables the specified key version on Cloud KMS.
func disableKeyVersion(w io.Writer, name string) error {
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/123"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// Build the request.
	req := &kmspb.UpdateCryptoKeyVersionRequest{
		CryptoKeyVersion: &kmspb.CryptoKeyVersion{
			Name:  name,
			State: kmspb.CryptoKeyVersion_DISABLED,
		},
		UpdateMask: &fieldmask.FieldMask{
			Paths: []string{"state"},
		},
	}

	// Call the API.
	result, err := client.UpdateCryptoKeyVersion(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to update key version: %w", err)
	}
	fmt.Fprintf(w, "Disabled key version: %s\n", result)
	return nil
}

Java

To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.

import com.google.cloud.kms.v1.CryptoKeyVersion;
import com.google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState;
import com.google.cloud.kms.v1.CryptoKeyVersionName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

public class DisableKeyVersion {

  public void disableKeyVersion() throws IOException