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 topic 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.
Disabling a key version is consistent within a range of several seconds up to three hours. 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.
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.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
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 an external key, you can disable the Cloud EKM key or key version. Disabling all key versions is recommended. Disabling a key takes effect within three hours.
When you disable a key, you should also revoke access to the key. IAM operations are consistent within seconds. Also consider revoking the Google Cloud service account's access in the external key management partner system.
To permanently remove the association between a Cloud EKM key and an external key, you can schedule the Cloud EKM key version for destruction. After the scheduled-for-destruction period, the key is destroyed. Destroying a key version is permanent. After the key version is destroyed, you can no longer encrypt data or decrypt data that was encrypted with the Cloud EKM key version. You cannot recreate a Cloud EKM key version that has been destroyed, even if you use the same external key URI or key path. When destroying external key material, we recommend first destroying the key or key version in Google Cloud and then, only after the Cloud EKM key is destroyed, destroying the key material in the external key manager.
Disabling a key or key version in Cloud KMS doesn't modify the key in the external key management partner system.
Destroying a manually managed key version in Cloud KMS doesn't modify the key in the external key management partner system. Destroying a coordinated external key version in Cloud KMS destroys the internal key material and sends a request 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 disabled state.
Console
Go to the Key Management page in the Google Cloud console.
Click the name of the key ring that contains the key whose key version you will 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.
Click Enable in the header.
In the confirmation prompt, click Enable.
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 enable key-version \ --key key \ --keyring key-ring \ --location location
Replace key-version with the version of the key to enable. Replace key with the key name. 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.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
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 the
cloudkms.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
).