Managing Cloud EKM keys

Beta

This product or feature is in a pre-release state and might change or have limited support. For more information, see the product launch stages.

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 Google Cloud project. Learn how to confirm 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 beta 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 Cloud External Key Manager. 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.

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 beta kms keyrings \
    create keyring-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 beta kms keys \
    create key-name \
    --keyring keyring-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 beta kms keys versions \
    create \
    --key key-name \
    --keyring keyring-name \
    --location location \
    --external-key-uri external-key-uri \
    --primary
   

Console

Create a key ring:

1. Go to the Cryptographic Keys page in the Cloud Console.

   Go to the Cryptographic Keys 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 panel.

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
• 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. If a non-primary version's external URI is still valid, you can also continue using that version to decrypt data.

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 beta kms keys versions \
  create \
  --key key-name \
  --keyring keyring-name \
  --location location \
  --external-key-uri new-external-key-uri \
  --primary

Console

1. Go to the Cryptographic Keys page in the Cloud Console.
   Go to the Cryptographic Keys 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.

If you only change the URI, a new key version is not created. Data that was encrypted using the key at the previous URI can still be decrypted after updating the URI.

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 beta 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 beta 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

Destroy an external key version

To remove the association between a Cloud EKM key and an external key, you can schedule the Cloud EKM key version for destruction.

After the key version is destroyed, you can no longer encrypt data or decrypt data that was encrypted with the Cloud EKM key. You cannot recreate a Cloud EKM key that has been destroyed, even if you use the same external key URI.

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

gcloud

To schedule the external key for destruction, use a command like the following, and specify the version, key name, and key location.

gcloud kms keys versions destroy key-version \
  --key key-name \
  --keyring keyring-name \
  --location location

Console

1. Go to the Cryptographic Keys page in the Cloud Console.
   Go to the Cryptographic Keys page
   

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

3. Click Destroy. Follow the instructions to schedule the key for destruction.

The key is scheduled for destruction. Until the key is actually destroyed, you can restore it in the same way as other Cloud KMS key version type.

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.