Using Cloud EKM via the internet

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

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 check if billing is enabled on a 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.

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

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

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

Create a symmetric encryption key

Console

Create a key ring:

1. Go to the Key Management page in the Google Cloud console.

   Go to the Key Management 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 Algorithm field is set to External symmetric key. After the key is created, the algorithm cannot be modified.

2. Enter a name for the key.

3. In Externally managed key connection type, choose via internet.

4. Enter the external key's URI.

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

6. 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 Key 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).

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
   

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:

1. Go to the Key Management page in the Google Cloud console.

   Go to the Key Management 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.

2. Enter a name for the key.

3. Set Purpose to Asymmetric sign.

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

5. In Externally managed key connection type, choose via internet.

6. Enter the external key's URI.

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

8. 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 Key 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).

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 asymmetric-signing. Add the --skip-initial-version-creation, to prevent an initial key version from being created. Set the default 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
   

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

   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
   

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

1. Go to the Key Management page in the Google Cloud console.
   Go to the Key Management page
   

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

3. Select Rotate Key for symmetric keys, or Create version for asymmetric keys.

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

1. Go to the Key Management page in the Google Cloud console.
   Go to the Key Management 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.

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.

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

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.