This topic is about using Cloud External Key Manager (Cloud EKM) to create and manage external keys accessed via the internet.
Before you begin
After you complete the steps below, you can begin using Cloud EKM keys to protect your data.
Create 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 check if billing is enabled on a 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.
Create a symmetric or asymmetric 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 or key path. You need this information to create a Cloud EKM key.
Ensure gcloud CLI is up to date
If you're going to use the Google Cloud CLI, ensure that it's up-to-date with the following command:
gcloud
gcloud components update
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.
Create a symmetric encryption key
Console
Create a key ring:
Go to the Key Management page in the Google 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 Algorithm field is set to External symmetric key. After the key is created, the algorithm cannot be modified.
Enter a name for the key.
In Externally managed key connection type, choose via internet.
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.
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
You can retrieve the key resource ID of the new key and begin using it to protect data in other Google Cloud services. See the Cloud EKM supported list of services with CMEK integrations to learn more.
Create an asymmetric signing key
Console
Create a key ring:
Go to the Key Management page in the Google 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.
Enter a name for the key.
Set Purpose to Asymmetric sign.
In the Algorithm field, select a valid asymmetric signing algorithm that's supported by your external key management partner. After the asymmetric key is created, the algorithm cannot be modified.
In Externally managed key connection type, choose via internet.
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.
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 toasymmetric-signing
. Add the--skip-initial-version-creation
, to prevent an initial key version from being created. Set thedefault algorithm
to a valid asymmetric signing algorithm that is supported by your external key management partner.gcloud kms keys \ create KEY_NAME \ --keyring KEY_RING_NAME \ --location LOCATION \ --purpose asymmetric-signing \ --protection-level external \ --skip-initial-version-creation \ --default-algorithm ec-sign-p256-sha256
Create a key version for the key you just created. Set the
--external-key-uri
flag to the external key URI. 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
You can retrieve the key resource ID of the new key and begin using it in the following scenarios:
- Signing with an asymmetric key directly through Cloud KMS. Each direct call to Cloud KMS becomes a call to the external key manager.
Rotate or create a new external key version
First, rotate the external key material on your external key manager. If that results in a new URI, you need to rotate or create a new Cloud EKM key version with the new URI.
For symmetric encryption keys, rotate the Cloud EKM key and specify the new key URI from your external key manager. For asymmetric keys, create a new key version and specify the new key URI. Rotating or creating a new key version causes all newly-created data protected with that key to be encrypted with new key material. Data protected with previous key material is not re- encrypted. As a result, your external key manager must continue to make previous key material available to be used.
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.
Console
Go to the Key Management page in the Google Cloud console.
Go to the Key Management pageSelect the key ring, then select the key.
Select Rotate Key for symmetric keys, or Create version for asymmetric keys.
Enter the new key URI, then select Rotate Key for symmetric keys or Create version for asymmetric keys.
The new key version becomes the primary version.
gcloud
To update 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.
This process is the same for both symmetric and asymmetric keys.
gcloud kms keys versions \ create \ --key KEY_NAME \ --keyring KEY_RING_NAME \ --location LOCATION \ --external-key-uri NEW_EXTERNAL_KEY_URI \ --primary
Update the URI for a key version without rotation
It is also possible to update the URI without rotating the key. This is useful when you do not wish to change the key material, but the URI changes due to a configuration change to your external key manager. Updating the URI without rotation is only permitted if the new URI hosts the same key material as the original URI.
If the key material has been rotated in the external key management partner system, you must rotate the key instead.
Console
Go to the Key Management page in the Google Cloud console.
Go to the Key Management 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.
gcloud
To update the key version's URI, use the gcloud 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 KEY_RING \ --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
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 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 or key path. When destroying external key material, we recommend first destroying the key or key version in Google Cloud and then, only after 24 hours, destroying the key material in the external key manager.
Troubleshooting 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.