GS Create an external key

This page shows you how to create Cloud External Key Manager (Cloud EKM) keys on an existing key ring in Cloud Key Management Service (Cloud KMS).

Before you begin

Before completing the tasks on this page, you need the following:

  • A Google Cloud project resource to contain your Cloud KMS resources. We recommend using a separate project for your Cloud KMS resources that does not contain any other Google Cloud resources.

    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.
  • The name and location of the key ring where you want to create your key. Choose a key ring in a location that is near your other resources and that supports Cloud EKM. To create a key ring, see Create a key ring.
  • In the external key management partner system, grant the Google Cloud service account access to use your external keys. Treat the service account as an email address. EKM partners might use different terminology than that used in this document.
  • To create EKM over VPC keys, you need to create an EKM connection.

Required roles

To get the permissions that you need to create keys, ask your administrator to grant you the Cloud KMS Admin (roles/cloudkms.admin) IAM role on the project or a parent resource. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to create keys. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create keys:

  • cloudkms.cryptoKeys.create
  • cloudkms.cryptoKeys.get
  • cloudkms.cryptoKeys.list
  • cloudkms.cryptoKeyVersions.create
  • cloudkms.cryptoKeyVersions.get
  • cloudkms.cryptoKeyVersions.list
  • cloudkms.keyRings.get
  • cloudkms.keyRings.list
  • cloudkms.locations.get
  • cloudkms.locations.list
  • resourcemanager.projects.get
  • To retrieve a public key: cloudkms.cryptoKeyVersions.viewPublicKey

You might also be able to get these permissions with custom roles or other predefined roles.

Create a coordinated external key

Console

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

    Go to Key Management

  2. Click the name of the key ring for which you will create a key.

  3. Click Create key.

  4. For Key name, enter a name for your key.

  5. For Protection level, select External.

  6. For External key manager (EKM) connection type, select via VPC.

  7. For EKM via VPC connection, select a connection.

    If you do not have the EkmConnection.list permission, you must manually enter the connection resource name.

  8. Click Continue.

  9. In the Key material section, you should see a message about new key material being requested by Cloud KMS and generated in your EKM. If you see the Key path field, the EKM via VPC connection that you selected isn't configured for coordinated external keys.

  10. Configure the rest of the key settings as needed, and then click Create.

Cloud EKM sends a request to your EKM to create a new key. The key shows as Pending generation until the key path is returned by your EKM and the Cloud EKM key is available.

gcloud

To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.

gcloud kms keys create KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --purpose PURPOSE \
    --default-algorithm ALGORITHM \
    --protection-level "external-vpc" \
    --crypto-key-backend VPC_CONNECTION_RESOURCE_ID

Replace the following:

  • 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.
  • PURPOSE: the purpose of the key.
  • ALGORITHM: the algorithm to use for the key, for example google-symmetric-encryption. For a list of supported algorithms, see Algorithms.
  • VPC_CONNECTION_RESOURCE_ID: the resource ID of the EKM connection.

For information on all flags and possible values, run the command with the --help flag.

What's next