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 schedule a key version for permanent destruction. After a key is destroyed, data that was encrypted with the key cannot be accessed.
When you submit a request to destroy a key version, destruction occurs after 24 hours unless you cancel the destruction request by restoring the key version. You can also manage access to the key using Identity and Access Management (IAM). IAM operations are consistent within seconds. For more information, see Using IAM.
You can also temporarily disable a key version.
In the rest of this topic, scheduling a key for destruction is referred to as destroying the key, even though destruction is not immediate.
Destroy a key version
You can destroy an enabled or disabled key version.
Web UI
Go to the Cryptographic Keys page in the Cloud Console.
Click the name of the key ring that contains the key whose key version you will schedule for destruction.
Click the key whose key version you want to schedule for destruction.
Check the box next to the key version that you want to schedule for destruction.
Click Destroy in the header.
In the confirmation prompt, enter the key name and then click Schedule Destruction.
Command-line
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Cloud SDK.
gcloud kms keys versions destroy key-version \ --key key \ --keyring key-ring \ --location location
Replace key-version with the version of the key to destroy. Replace key with the name of the key. Replace key-ring with the name of the key ring where the key iis 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.
When you submit the destruction request, the key version's state becomes Scheduled for destruction. After 24 hours have elapsed, the key version's state becomes Destroyed.
To receive an alert when a key version is scheduled for destruction, see Using Cloud Monitoring with Cloud KMS.
Destroyed key versions are not billed resources.
Restore a key version
During the period when a key version's status is Scheduled for destruction, you can restore the key version by submitting a restoration request.
Web UI
Go to the Cryptographic Keys page in the Cloud Console.
Click the name of the key ring that contains the key whose key version you will restore.
Click the key whose key version you want to restore.
Check the box next to the key version that you want to restore.
Click Restore in the header.
In the confirmation prompt, click Restore.
Command-line
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Cloud SDK.
gcloud kms keys versions restore key-version \ --key key \ --keyring key-ring \ --location location
Replace key-version with the version of the key to restore. 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 the restoration request completes, the key version's state becomes Disabled. You must enable the key before it can be used.
Required IAM permissions
To destroy a key version, the caller needs the cloudkms.cryptoKeyVersions.destroy
IAM permission on the key, the key ring, or the project, folder,
or organization.
To restore a key version, the caller needs the
cloudkms.cryptoKeyVersions.restore
permission.
Both of these permissions are granted to the Cloud KMS Admin role
(roles/cloudkms.admin
).