Enable and disable key versions Stay organized with collections Save and categorize content based on your preferences.
In Cloud KMS, the cryptographic key material that you use toencrypt, decrypt, sign, and verify data is stored in a key version. A key haszero 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 isdisabled, data that was encrypted with the key can't be accessed. To access thedata, you can re-enable the key version.
Unless otherwise specified in theService Health dashboard,disabling a key version is typicallyconsistent withinone minute. Enabling a key version is nearly instant. You can also manage accessto a key version using Identity and Access Management (IAM). IAM operationsare consistent within seconds. For more information, seeUsing IAM.
Caution: Disabling a key version that is required to start a container orinstance can result in service outages. It is the customer's responsibility toensure that a key version is safe to disable. Google is not responsible foroutages, loss of data, or compliance issues which result from a customerdisabling a key version.You can also permanentlydestroy a key version.Depending on your organization policies, you might need to disable a key versionbefore you can destroy it. For more information seeControl key versiondestruction.
Note: Key rings, keys, and key versions cannot be deleted. This ensures that theresource identifier of akey version is unique and always points to the original key material for that key version unless ithas been destroyed.You can store an unlimited number of key rings, enabled or disabled keys, andenabled, disabled, or destroyed key versions.For more information, seePricing andQuotas.Disable a key version
You can disable a key version in the enabledstate. Before disabling a keyversion, we recommend that you check whether the key is still in use. You canview key usage tracking details for the key to seewhether it is protecting CMEK resources. If any resources are protected by thekey version that you want to disable, re-encrypt them with another key versionbefore disabling the key.
Caution: Key usage tracking details can be delayed or incomplete.Familiarize yourself with thelimitations of this data.Console
Go to theKey Management page in the Google Cloud console.
Click the name of the key ring that contains the key whose key version youwill 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.
ClickDisable in the header.
In the confirmation prompt, clickDisable.
gcloud
To use Cloud KMS on the command line, firstInstall or upgrade to the latest version of Google Cloud CLI.
gcloud kms keys versions disablekey-version \ --keykey \ --keyringkey-ring \ --locationlocation
Replacekey-version with the version of the key to disable. Replacekey with the name of the key. Replacekey-ring withthe name of the key ring where the key is located. Replacelocationwith 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, firstset up a C# development environment andinstall the Cloud KMS C# SDK.
usingGoogle.Cloud.Kms.V1;usingGoogle.Protobuf.WellKnownTypes;publicclassDisableKeyVersionSample{publicCryptoKeyVersionDisableKeyVersion(stringprojectId="my-project",stringlocationId="us-east1",stringkeyRingId="my-key-ring",stringkeyId="my-key",stringkeyVersionId="123"){// Create the client.KeyManagementServiceClientclient=KeyManagementServiceClient.Create();// Build the key version.CryptoKeyVersionkeyVersion=newCryptoKeyVersion{CryptoKeyVersionName=newCryptoKeyVersionName(projectId,locationId,keyRingId,keyId,keyVersionId),State=CryptoKeyVersion.Types.CryptoKeyVersionState.Disabled,};// Build the update mask.FieldMaskfieldMask=newFieldMask{Paths={"state"},};// Call the API.CryptoKeyVersionresult=client.UpdateCryptoKeyVersion(keyVersion,fieldMask);// Return the result.returnresult;}}Go
To run this code, firstset up a Go development environment andinstall 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.funcdisableKeyVersion(wio.Writer,namestring)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)iferr!=nil{returnfmt.Errorf("failed to create kms client: %w",err)}deferclient.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)iferr!=nil{returnfmt.Errorf("failed to update key version: %w",err)}fmt.Fprintf(w,"Disabled key version: %s\n",result)returnnil}Java
To run this code, firstset up a Java development environment andinstall the Cloud KMS Java SDK.
importcom.google.cloud.kms.v1.CryptoKeyVersion;importcom.google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState;importcom.google.cloud.kms.v1.CryptoKeyVersionName;importcom.google.cloud.kms.v1.KeyManagementServiceClient;importcom.google.protobuf.FieldMask;importcom.google.protobuf.util.FieldMaskUtil;importjava.io.IOException;publicclassDisableKeyVersion{publicvoiddisableKeyVersion()throwsIOException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringlocationId="us-east1";StringkeyRingId="my-key-ring";StringkeyId="my-key";StringkeyVersionId="123";disableKeyVersion(projectId,locationId,keyRingId,keyId,keyVersionId);}// Disable a key version from use.publicvoiddisableKeyVersion(StringprojectId,StringlocationId,StringkeyRingId,StringkeyId,StringkeyVersionId)throwsIOException{// Initialize client that will be used to send requests. This client only// needs to be created once, and can be reused for multiple requests. After// completing all of your requests, call the "close" method on the client to// safely clean up any remaining background resources.try(KeyManagementServiceClientclient=KeyManagementServiceClient.create()){// Build the key version name from the project, location, key ring, key,// and key version.CryptoKeyVersionNamekeyVersionName=CryptoKeyVersionName.of(projectId,locationId,keyRingId,keyId,keyVersionId);// Build the updated key version, setting it to disbaled.CryptoKeyVersionkeyVersion=CryptoKeyVersion.newBuilder().setName(keyVersionName.toString()).setState(CryptoKeyVersionState.DISABLED).build();// Create a field mask of updated values.FieldMaskfieldMask=FieldMaskUtil.fromString("state");// Disable the key version.CryptoKeyVersionresponse=client.updateCryptoKeyVersion(keyVersion,fieldMask);System.out.printf("Disabled key version: %s%n",response.getName());}}}Node.js
To run this code, firstset up a Node.js development environment andinstall the Cloud KMS Node.js SDK.
//// TODO(developer): Uncomment these variables before running the sample.//// const projectId = 'my-project';// const locationId = 'us-east1';// const keyRingId = 'my-key-ring';// const keyId = 'my-key';// const versionId = '123';// Imports the Cloud KMS libraryconst{KeyManagementServiceClient}=require('@google-cloud/kms');// Instantiates a clientconstclient=newKeyManagementServiceClient();// Build the key version nameconstversionName=client.cryptoKeyVersionPath(projectId,locationId,keyRingId,keyId,versionId);asyncfunctiondisableKeyVersion(){const[version]=awaitclient.updateCryptoKeyVersion({cryptoKeyVersion:{name:versionName,state:'DISABLED',},updateMask:{paths:['state'],},});console.log(`Disabled key version:${version.name}`);returnversion;}returndisableKeyVersion();PHP
To run this code, first learn aboutusing PHP on Google Cloud andinstall the Cloud KMS PHP SDK.
use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;use Google\Cloud\Kms\V1\CryptoKeyVersion;use Google\Cloud\Kms\V1\CryptoKeyVersion\CryptoKeyVersionState;use Google\Cloud\Kms\V1\UpdateCryptoKeyVersionRequest;use Google\Protobuf\FieldMask;function disable_key_version( string $projectId = 'my-project', string $locationId = 'us-east1', string $keyRingId = 'my-key-ring', string $keyId = 'my-key', string $versionId = '123'): CryptoKeyVersion { // Create the Cloud KMS client. $client = new KeyManagementServiceClient(); // Build the key version name. $keyVersionName = $client->cryptoKeyVersionName($projectId, $locationId, $keyRingId, $keyId, $versionId); // Create the updated version. $keyVersion = (new CryptoKeyVersion()) ->setName($keyVersionName) ->setState(CryptoKeyVersionState::DISABLED); // Create the field mask. $updateMask = (new FieldMask()) ->setPaths(['state']); // Call the API. $updateCryptoKeyVersionRequest = (new UpdateCryptoKeyVersionRequest()) ->setCryptoKeyVersion($keyVersion) ->setUpdateMask($updateMask); $disabledVersion = $client->updateCryptoKeyVersion($updateCryptoKeyVersionRequest); printf('Disabled key version: %s' . PHP_EOL, $disabledVersion->getName()); return $disabledVersion;}Python
To run this code, firstset up a Python development environment andinstall the Cloud KMS Python SDK.
fromgoogle.cloudimportkmsdefdisable_key_version(project_id:str,location_id:str,key_ring_id:str,key_id:str,version_id:str)->kms.CryptoKeyVersion:""" Disable a key. Args: project_id (string): Google Cloud project ID (e.g. 'my-project'). location_id (string): Cloud KMS location (e.g. 'us-east1'). key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring'). key_id (string): ID of the key to use (e.g. 'my-key'). version_id (string): ID of the key version to disable (e.g. '1'). Returns: CryptoKeyVersion: The version. """# Create the client.client=kms.KeyManagementServiceClient()# Build the key version name.key_version_name=client.crypto_key_version_path(project_id,location_id,key_ring_id,key_id,version_id)key_version={"name":key_version_name,"state":kms.CryptoKeyVersion.CryptoKeyVersionState.DISABLED,}# Build the update mask.update_mask={"paths":["state"]}# Call the API.disabled_version=client.update_crypto_key_version(request={"crypto_key_version":key_version,"update_mask":update_mask})print(f"Disabled key version:{disabled_version.name}")returndisabled_versionRuby
To run this code, firstset up a Ruby development environment andinstall the Cloud KMS Ruby SDK.
# TODO(developer): uncomment these values before running the sample.# project_id = "my-project"# location_id = "us-east1"# key_ring_id = "my-key-ring"# key_id = "my-key"# version_id = "123"# Require the library.require"google/cloud/kms"# Create the client.client=Google::Cloud::Kms.key_management_service# Build the key version name.key_version_name=client.crypto_key_version_pathproject:project_id,location:location_id,key_ring:key_ring_id,crypto_key:key_id,crypto_key_version:version_id# Create the updated version.version={name:key_version_name,state::DISABLED}# Create the field mask.update_mask={paths:["state"]}# Call the API.disabled_version=client.update_crypto_key_versioncrypto_key_version:version,update_mask:update_maskputs"Disabled key version:#{disabled_version.name}"After you submit the request, the state of the key version changes to disabled.
Disabled key versions are billed resources.
Disable or destroy an external key
To temporarily disable the association between a Cloud EKM key and anexternal key, you candisable the Cloud EKMkey or key version. Disabling all key versions is recommended. Disabling a keytakes effect within three hours.
When you disable a key, you should alsorevoke access to the key. IAM operations areconsistent within seconds. Also consider revoking the Google Cloud serviceaccount's access in the external key management partner system.
Topermanently remove the association between a Cloud EKM key andan external key, you canschedule the Cloud EKM key version for destruction.After the scheduled-for-destruction period, the key is destroyed. Destroying akey version is permanent. After the key version is destroyed, you can no longerencrypt data or decrypt data that was encrypted with the Cloud EKM keyversion. You cannot recreate a Cloud EKM key version that has beendestroyed, even if you use the same external key URI or key path. Whendestroying external key material, we recommend first destroying the key or keyversion in Google Cloud and then, only after the Cloud EKM key isdestroyed, destroying the key material in the external key manager.
Disabling a key or key version in Cloud KMS doesn't modify thekey in the external key management partner system.
Destroying amanually managed key version in Cloud KMS doesn't modifythe key in the external key management partner system. Destroying acoordinated external keyversion in Cloud KMS destroys the internal key material and sends arequest to the external key management partner system to destroy the external key material.
Enable a key version
You can enable a key version in the disabledstate.
Console
Go to theKey Management page in the Google Cloud console.
Click the name of the key ring that contains the key whose key version youwill enable.
Click the key whose key version you want to enable.
Check the box next to the key version(s) that you want to enable.
ClickEnable in the header.
In the confirmation prompt, clickEnable.
gcloud
To use Cloud KMS on the command line, firstInstall or upgrade to the latest version of Google Cloud CLI.
gcloud kms keys versions enablekey-version \ --keykey \ --keyringkey-ring \ --locationlocation
Replacekey-version with the version of the key to enable. Replacekey with the key name. Replacekey-ring withthe name of the key ring where the key is located. Replacelocationwith 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, firstset up a C# development environment andinstall the Cloud KMS C# SDK.
usingGoogle.Cloud.Kms.V1;usingGoogle.Protobuf.WellKnownTypes;publicclassEnableKeyVersionSample{publicCryptoKeyVersionEnableKeyVersion(stringprojectId="my-project",stringlocationId="us-east1",stringkeyRingId="my-key-ring",stringkeyId="my-key",stringkeyVersionId="123"){// Create the client.KeyManagementServiceClientclient=KeyManagementServiceClient.Create();// Build the key version.CryptoKeyVersionkeyVersion=newCryptoKeyVersion{CryptoKeyVersionName=newCryptoKeyVersionName(projectId,locationId,keyRingId,keyId,keyVersionId),State=CryptoKeyVersion.Types.CryptoKeyVersionState.Enabled,};// Build the update mask.FieldMaskfieldMask=newFieldMask{Paths={"state"},};// Call the API.CryptoKeyVersionresult=client.UpdateCryptoKeyVersion(keyVersion,fieldMask);// Return the result.returnresult;}}Go
To run this code, firstset up a Go development environment andinstall 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")// enableKeyVersion disables the specified key version on Cloud KMS.funcenableKeyVersion(wio.Writer,namestring)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)iferr!=nil{returnfmt.Errorf("failed to create kms client: %w",err)}deferclient.Close()// Build the request.req:=&kmspb.UpdateCryptoKeyVersionRequest{CryptoKeyVersion:&kmspb.CryptoKeyVersion{Name:name,State:kmspb.CryptoKeyVersion_ENABLED,},UpdateMask:&fieldmask.FieldMask{Paths:[]string{"state"},},}// Call the API.result,err:=client.UpdateCryptoKeyVersion(ctx,req)iferr!=nil{returnfmt.Errorf("failed to update key version: %w",err)}fmt.Fprintf(w,"Enabled key version: %s\n",result)returnnil}Java
To run this code, firstset up a Java development environment andinstall the Cloud KMS Java SDK.
importcom.google.cloud.kms.v1.CryptoKeyVersion;importcom.google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState;importcom.google.cloud.kms.v1.CryptoKeyVersionName;importcom.google.cloud.kms.v1.KeyManagementServiceClient;importcom.google.protobuf.FieldMask;importcom.google.protobuf.util.FieldMaskUtil;importjava.io.IOException;publicclassEnableKeyVersion{publicvoidenableKeyVersion()throwsIOException{// TODO(developer): Replace these variables before running the sample.StringprojectId="your-project-id";StringlocationId="us-east1";StringkeyRingId="my-key-ring";StringkeyId="my-key";StringkeyVersionId="123";enableKeyVersion(projectId,locationId,keyRingId,keyId,keyVersionId);}// Enable a disabled key version to be used again.publicvoidenableKeyVersion(StringprojectId,StringlocationId,StringkeyRingId,StringkeyId,StringkeyVersionId)throwsIOException{// Initialize client that will be used to send requests. This client only// needs to be created once, and can be reused for multiple requests. After// completing all of your requests, call the "close" method on the client to// safely clean up any remaining background resources.try(KeyManagementServiceClientclient=KeyManagementServiceClient.create()){// Build the key version name from the project, location, key ring, key,// and key version.CryptoKeyVersionNamekeyVersionName=CryptoKeyVersionName.of(projectId,locationId,keyRingId,keyId,keyVersionId);// Build the updated key version, setting it to enabled.CryptoKeyVersionkeyVersion=CryptoKeyVersion.newBuilder().setName(keyVersionName.toString()).setState(CryptoKeyVersionState.ENABLED).build();// Create a field mask of updated values.FieldMaskfieldMask=FieldMaskUtil.fromString("state");// Enable the key version.CryptoKeyVersionresponse=client.updateCryptoKeyVersion(keyVersion,fieldMask);System.out.printf("Enabled key version: %s%n",response.getName());}}}Node.js
To run this code, firstset up a Node.js development environment andinstall the Cloud KMS Node.js SDK.
//// TODO(developer): Uncomment these variables before running the sample.//// const projectId = 'my-project';// const locationId = 'us-east1';// const keyRingId = 'my-key-ring';// const keyId = 'my-key';// const versionId = '123';// Imports the Cloud KMS libraryconst{KeyManagementServiceClient}=require('@google-cloud/kms');// Instantiates a clientconstclient=newKeyManagementServiceClient();// Build the key version nameconstversionName=client.cryptoKeyVersionPath(projectId,locationId,keyRingId,keyId,versionId);asyncfunctionenableKeyVersion(){const[version]=awaitclient.updateCryptoKeyVersion({cryptoKeyVersion:{name:versionName,state:'ENABLED',},updateMask:{paths:['state'],},});console.log(`Enabled key version:${version.name}`);returnversion;}returnenableKeyVersion();PHP
To run this code, first learn aboutusing PHP on Google Cloud andinstall the Cloud KMS PHP SDK.
use Google\Cloud\Kms\V1\Client\KeyManagementServiceClient;use Google\Cloud\Kms\V1\CryptoKeyVersion;use Google\Cloud\Kms\V1\CryptoKeyVersion\CryptoKeyVersionState;use Google\Cloud\Kms\V1\UpdateCryptoKeyVersionRequest;use Google\Protobuf\FieldMask;function enable_key_version( string $projectId = 'my-project', string $locationId = 'us-east1', string $keyRingId = 'my-key-ring', string $keyId = 'my-key', string $versionId = '123'): CryptoKeyVersion { // Create the Cloud KMS client. $client = new KeyManagementServiceClient(); // Build the key version name. $keyVersionName = $client->cryptoKeyVersionName($projectId, $locationId, $keyRingId, $keyId, $versionId); // Create the updated version. $keyVersion = (new CryptoKeyVersion()) ->setName($keyVersionName) ->setState(CryptoKeyVersionState::ENABLED); // Create the field mask. $updateMask = (new FieldMask()) ->setPaths(['state']); // Call the API. $updateCryptoKeyVersionRequest = (new UpdateCryptoKeyVersionRequest()) ->setCryptoKeyVersion($keyVersion) ->setUpdateMask($updateMask); $enabledVersion = $client->updateCryptoKeyVersion($updateCryptoKeyVersionRequest); printf('Enabled key version: %s' . PHP_EOL, $enabledVersion->getName()); return $enabledVersion;}Python
To run this code, firstset up a Python development environment andinstall the Cloud KMS Python SDK.
fromgoogle.cloudimportkmsdefenable_key_version(project_id:str,location_id:str,key_ring_id:str,key_id:str,version_id:str)->kms.CryptoKeyVersion:""" Enable a key. Args: project_id (string): Google Cloud project ID (e.g. 'my-project'). location_id (string): Cloud KMS location (e.g. 'us-east1'). key_ring_id (string): ID of the Cloud KMS key ring (e.g. 'my-key-ring'). key_id (string): ID of the key to use (e.g. 'my-key'). version_id (string): ID of the key version to enable (e.g. '1'). Returns: CryptoKeyVersion: The version. """# Create the client.client=kms.KeyManagementServiceClient()# Build the key version name.key_version_name=client.crypto_key_version_path(project_id,location_id,key_ring_id,key_id,version_id)key_version={"name":key_version_name,"state":kms.CryptoKeyVersion.CryptoKeyVersionState.ENABLED,}# Build the update mask.update_mask={"paths":["state"]}# Call the API.enabled_version=client.update_crypto_key_version(request={"crypto_key_version":key_version,"update_mask":update_mask})print(f"Enabled key version:{enabled_version.name}")returnenabled_versionRuby
To run this code, firstset up a Ruby development environment andinstall the Cloud KMS Ruby SDK.
# TODO(developer): uncomment these values before running the sample.# project_id = "my-project"# location_id = "us-east1"# key_ring_id = "my-key-ring"# key_id = "my-key"# version_id = "123"# Require the library.require"google/cloud/kms"# Create the client.client=Google::Cloud::Kms.key_management_service# Build the key version name.key_version_name=client.crypto_key_version_pathproject:project_id,location:location_id,key_ring:key_ring_id,crypto_key:key_id,crypto_key_version:version_id# Create the updated version.version={name:key_version_name,state::ENABLED}# Create the field mask.update_mask={paths:["state"]}# Call the API.enabled_version=client.update_crypto_key_versioncrypto_key_version:version,update_mask:update_maskputs"Enabled key version:#{enabled_version.name}"After you submit the request, the state of the key version changes to enabled.
Required IAM permissions
To enable or disable a key version, the caller needs thecloudkms.cryptoKeyVersions.update IAM permission on the key,the key ring, or the project, folder, or organization.
This permission is granted to the Cloud KMS Admin role(roles/cloudkms.admin).
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-17 UTC.