Managing Cloud EKM keys

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.

1. In the Google Cloud Console, go to the Manage Resources page.

   Go to the Manage Resources page

2. Create a new Google Cloud project or select an existing project.

   Important: The name you use must be between 4 and 30 characters. When you type the name, the form will suggest a project ID, which you can edit. The project ID you use must be between 6 and 30 characters, with a lowercase letter as the first character. You can use a dash, lowercase letter, or digit for the remaining characters, but the last character cannot be a dash. You should be aware that some resource identifiers (such as project IDs) might be retained beyond the life of your project. For this reason, avoid storing sensitive information in resource identifiers.
   ...see naming guidelines

3. 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

1. Enable the Cloud Key Management Service API for the project.

   Enable the Cloud Key Management Service API

2. 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.

   [e-mail]
   

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.

1. If necessary, request access from your external key management partner to participate in this release.

2. 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.

3. Make a note of the external key's URI. You need this information to create a Cloud EKM key.

Important: If you are operating your own deployment of the external key management partner system and are unable to follow the naming guidelines provided by the external key management partner, you may need to contact support.

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.

Note: Key rings with the same name can exist in different locations, so you must always specify the location.

gcloud

1. 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
   

2. Create a key in the key ring. Set the protection level to external and set the purpose to encryption. Add the --skip-initial-version-creation, to prevent an initial key version from being created. Set the default algorithm to external-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
   

3. 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.

   Note: The version is not created if the key URI is invalid or unreachable, or if the Google Cloud service account does not have permission to use the external key management partner key. If an error occurs, correct the problem and run the command again.

   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:

1. Go to the Cryptographic Key Rings page in the Cloud Console.

   Go to the Cryptographic Key Rings page
   

2. Click Create key ring.

3. In the Key ring name field, enter the name for your key ring.

4. From the Location dropdown, select one of the regions recommended by your external key management partner.

5. Click Create. The key ring is created, and the key-creation dialog appears.

Create a Cloud EKM key.

1. 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.

2. Enter a name for the key.

3. Enter the external key's URI.

4. Optionally, add labels for the key. You can learn more about labeling keys.

5. Click Create.

The key version is created automatically and becomes the primary version.

Note: If you enter the URI incorrectly, or the key is not found at that URI, the key is created but has no version. If this happens, click Rotate to create a new version, and enter the correct URI. You can find more details about the error in the Activity tab of the "SHOW INFO PANEL" button, or in the Admin Activity audit logs (enabled by default).

You can retrieve the key resource ID of the new key and begin using it to protect data in the following scenarios:

• Encrypting and decrypting data with a symmetric key directly through Cloud KMS. Each direct call to Cloud KMS becomes a call to the external key manager.
• Protecting Artifact Registry content stored in repositories
• Protecting BigQuery data
• Protecting Compute Engine resources
• Protecting Log Router data
• Protecting Cloud SQL data written to databases
• Protecting Spanner data
• Protecting Dataflow pipeline state
• Protecting GKE data on VM disks
• Protecting GKE application layer secrets
• Protecting Pub/Sub messages
• Protecting Secret Manager secrets

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

1. Go to the Cryptographic Key Rings page in the Cloud Console.
   Go to the Cryptographic Key Rings page
   

2. Select the key ring, then select the key.

3. Select Rotate.

4. 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 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

1. Go to the Cryptographic Key Rings page in the Cloud Console.
   Go to the Cryptographic Key Rings page
   

2. Select the key ring, then select the key and version.

3. Click More then View key URI.

4. Click Update key URI.

5. 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.

Note: Disabling or destroying a key or key version in Cloud KMS does not modify the key in the external key management partner system.

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.