This topic explains how to use Cloud External Key Manager (Cloud EKM) to encrypt your data at rest using keys managed outside of Google Cloud.
Before you begin
Once you've completed the following steps, you can begin using Cloud EKM keys to protect your data.
Create a new project
When testing Cloud EKM, we recommend that you set up a new project.
In the Google Cloud Console, go to the Manage Resources page.
Create a new Google Cloud project or select an existing project.
-
Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.
You can learn more about Cloud EKM pricing.
Enable Cloud KMS
Enable the Cloud Key Management Service API for the project.
Make a note of your project's Cloud EKM service account. In the following example, replace project-number with your Google Cloud project's project number. This information is also visible each time you use the Google Cloud Console to create a Cloud EKM key.
service-project-number@gcp-sa-ekms.iam.gserviceaccount.com
Prepare the external key management partner system
In the external key management partner system, grant the Google Cloud service account access to use the external key. Treat the service account as an email address. Partners may use different terminology than that used in this topic.
Create an external key
You perform these steps on the external key management partner system. The exact steps vary by external key management partner. You can review the list of supported Cloud EKM partners.
If necessary, request access from your external key management partner to participate in this release.
Create a key in the external key management partner system or select an existing key.
Create the key in a region near the Google Cloud region you plan to use for Cloud EKM keys. This helps reduce the network latency between your Google Cloud project and the external key management partner. Otherwise, you may experience an increased number of failed operations. Review Cloud EKM and regions for more information.
Make a note of the external key's URI. You need this information to create a Cloud EKM key.
Create a Cloud EKM key
When you create a key, you add it to a key ring that exists in the location where you intend to use the key. For Cloud EKM keys, the location must also be near the location of your external key.
This topic shows how to create a key ring, but you can create a key on an existing key ring in an appropriate location.
gcloud
Create a key ring in one of the regions recommended by your external key management partner.
gcloud kms keyrings \ create key-ring-name \ --location location
Create a key in the key ring. Set the protection level to
external
and set the purpose toencryption
. Add the--skip-initial-version-creation
, to prevent an initial key version from being created. Set thedefault algorithm
toexternal-symmetric-encryption
.gcloud kms keys \ create key-name \ --keyring key-ring-name \ --location location \ --purpose encryption \ --protection-level external \ --skip-initial-version-creation \ --default-algorithm external-symmetric-encryption
Create a key version for the key you just created. Set the
--external-key-uri
flag to the external key URI. Include the--primary
flag to make this version the primary key version. Use the same key name, key ring, and location as the previous steps.gcloud kms keys versions \ create \ --key key-name \ --keyring key-ring-name \ --location location \ --external-key-uri external-key-uri \ --primary
Console
Create a key ring:
Go to the Cryptographic Keys page in the Cloud Console.
Click Create key ring.
In the Key ring name field, enter the name for your key ring.
From the Location dropdown, select one of the regions recommended by your external key management partner.
Click Create. The key ring is created, and the key-creation dialog appears.
Create a Cloud EKM key.
For the type of key, select Externally managed key. The Purpose is automatically set to Symmetric encrypt / decrypt and the Key type and algorithm field is set to External symmetric key. These values cannot be modified.
Enter a name for the key.
Enter the external key's URI.
Optionally, add labels for the key. You can learn more about labeling keys.
Click Create.
The key version is created automatically and becomes the primary version.
You can retrieve the key resource ID of the new key and begin using it to protect data in the following scenarios:
- Protecting BigQuery data
- Protecting Compute Engine resources
- Protecting GKE data on VM disks
- Protecting GKE application layer secrets
- Protecting Cloud SQL data written to databases
- Encrypting and decrypting data with a symmetric key directly through Cloud KMS
Rotate an external key
You can rotate the Cloud EKM key if you need to change the URI of the external key. Rotating the key adds a new key version to the Cloud EKM key.
After you rotate a Cloud EKM key, you can still decrypt data that was encrypted using a previous version of the key, as long as the previous version of the external key is still available at the external key URI on the external key management partner's system.
If the key material in the external key management partner system does not change, but the URI changes, you can update the key's external URI without rotating the key.
gcloud
To rotate the key, create a new key version that contains the updated external key URI and make this version the primary key version. Use the same name, key ring, and location you used when creating the key.
gcloud kms keys versions \ create \ --key key-name \ --keyring key-ring-name \ --location location \ --external-key-uri new-external-key-uri \ --primary
Console
Go to the Cryptographic Keys page in the Cloud Console.
Go to the Cryptographic Keys pageSelect the key ring, then select the key.
Select Rotate.
Enter the new key URI, then select Rotate key.
The new key version becomes the primary version.
Update the URI for a key version
You can update the key URI for a Cloud EKM key version without rotating the Cloud EKM key, as long as the new key URI has exactly the same key material as the original key URI. If the URIs do not contain the same key material, updating the key URI fails. You can also update the key URI for a key version that is not the primary version.
If the key material has been rotated in the external key management partner system, you must rotate the key instead..
gcloud
To update the key version's URI, use the gcloud beta kms versions update
command,
specify the key version to update, and set the --external-key-uri
flag to the
new URI.
gcloud kms keys versions update key-version \ --key key \ --keyring keyring \ --location location \ --external-key-uri uri
For example, the following command updates the URI for version 2 of key
example-key
to be https://example-key.example.com/v0/example_key
:
gcloud kms keys versions update 2 \ --key example-key> \ --keyring example-keyring \ --location us-west1 \ --external-key-uri https://example-key.example.com/v0/example_key
Console
Go to the Cryptographic Keys page in the Cloud Console.
Go to the Cryptographic Keys pageSelect the key ring, then select the key and version.
Click More more_vert then View key URI.
Click Update key URI.
Enter the new key URI, then click Save.
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 the entire key 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 a 24-hour period, the key is destroyed. Destroying a key 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.
Interpreting errors
If you experience an error when creating or using a Cloud EKM key, an error is logged. Refer to the Cloud EKM error reference for details about how to interpret and fix these errors.
Getting support
If you experience an issue with Cloud EKM, contact Support.