Update external key reference

This page shows you how to update the external key reference for a Cloud EKM key without rotating the key. The new key reference must point to the same key material as the current key reference. If the key material has been rotated in the external key management partner system, you must rotate the key instead.

Use the instructions on this page if your external key management partner system has changed the key path or key URI for an existing key. For example, the key reference can change as a result of a change to the hostname of the external key management partner or a change in their key reference structure.

Required roles

To get the permission that you need to update an external key reference, ask your administrator to grant you the Cloud KMS Admin (roles/cloudkms.admin) IAM role on your key. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the cloudkms.cryptoKeyVersions.update permission, which is required to update an external key reference.

You might also be able to get this permission with custom roles or other predefined roles.

Update the URI for a key version without rotation

To update the key reference for a Cloud EKM key that you use over the internet, complete the following steps:

Console

  1. In the Google Cloud console, go to the Key Management page.

    Go to Key Management

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

  3. Click More, and then click View key URI.

  4. Click Update key URI.

  5. Enter the new key URI, and then click Save.

gcloud CLI

To update the URI for the key version, use the gcloud kms versions update command:

gcloud kms keys versions update KEY_VERSION \
  --key KEY_NAME \
  --keyring KEY_RING \
  --location LOCATION \
  --external-key-uri NEW_KEY_URI

Replace the following:

  • KEY_VERSION: the key version number.
  • KEY_NAME: the name of the key.
  • KEY_RING: the name of the key ring that contains the key.
  • LOCATION: the Cloud KMS location of the key ring.
  • NEW_KEY_URI: the new URI for the existing external key material.

Update the key path for a key version without rotation

To update the key reference for a Cloud EKM key that you use over a VPC network, complete the following steps:

Console

  1. In the Google Cloud console, go to the Key Management page.

    Go to Key Management

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

  3. Click More then View key path.

  4. Click Update key path.

  5. Enter the new key path, then click Save.

gcloud CLI

To update the key path of the key version, use the gcloud kms versions update command:

gcloud kms keys versions update KEY_VERSION \
  --key KEY_NAME \
  --keyring KEY_RING \
  --location LOCATION \
  --ekm-connection-key-path NEW_KEY_PATH

Replace the following:

  • KEY_VERSION: the key version number.
  • KEY_NAME: the name of the key.
  • KEY_RING: the name of the key ring that contains the key.
  • LOCATION: the Cloud KMS location of the key ring.
  • NEW_KEY_PATH: the new path for the existing external key material.