This page shows you how to set up Cloud External Key Manager (Cloud EKM) to connect toyour external key management (EKM) provider over aVirtual Private Cloud (VPC) network.

You can use external keys over VPC in Cloud KMS locations thatsupport EKM via VPC. For more information, see theCloud KMS Locationspage.

Terminology

• EKM connection

  The Cloud KMS resource used to configure a connection to yourexternal key manager. In the Google Cloud console, this is referred to as anEKM via VPC connection.

• VPC project

  The project that holds the VPC resource that is used to connectto your external key manager.

• Key projects

  The projects that hold EKM connection resources and Cloud EKM keys inCloud KMS. A key project can be the same as a VPCproject, but it is not required.

• Crypto space

  A container for your resources within your external key management partner. Your crypto spaceis identified by a unique crypto space path. The format of the crypto spacepath varies by external key management partner—for example,v0/cryptospaces/YOUR_UNIQUE_PATH.

Before you begin

After you complete the steps below, you can begin using Cloud EKMkeys 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. Verify that billing is enabled for your Google Cloud project.

You can learn more aboutCloud 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 thefollowing example, replacePROJECT_NUMBER with yourGoogle Cloud project'sproject number. Thisinformation is also visible each time you use the Google Cloud console to createa Cloud EKM key.

   service-PROJECT_NUMBER@gcp-sa-ekms.iam.gserviceaccount.com

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 thefollowing command:

gcloud components update

Prepare a VPC network

There are two options when setting up a VPC network:

• Auto mode network
• Custom mode network

By default, new projects contain an auto mode network that ispre-populated with firewall rules.If the VPC network will not be used for production purposes, thedefault auto mode network is the quickest way to get started.

If your external key manager is running on-premises and you will connect to it viahybrid connectivity, you should use a custom modenetwork because it provides control over the subnet IP address ranges.

Follow these steps for setting up your VPC:

1. Enable Private Google Access

   The external key manager must verify the OIDC token contained in eachrequest. To verify the token, it needs to retrieve the OAuth2 public keyfrom thewww.googleapis.com domain name. If the external key manager runsin Google Cloud and does not have access via the internet (e.g. a VM withoutan external IP or blocked by a firewall), follow the instructions forconfiguring private Google access.

2. Firewall configuration for IP range35.199.192.0/19

   Requests from Cloud EKM will come from this range. Create bothingress and egress allowfirewall rules for TCP forthe port on which the external key manager is listening.

Set up hybrid connectivity

If the external key manager is running on-premise, use ahybrid connectivity solutionto connect the VPC with your on-premise network. Once you haveset up connectivity, follow these additional steps:

1. Enable Private Google Access

   The external key manager must verify the OIDC token contained in each request. To verify the token, it needsto retrieve the OAuth2 public key from thewww.googleapis.com domain name. If theexternal key manager runs on-premise and does not have access via the internet, followthe instructions forconfiguring private Google access for on-premises hosts.

2. Firewall configuration for IP range35.199.192.0/19

   Requests from Cloud EKM will come from this range. Configure youron-premise network firewall or similar equipment to permit TCP traffic onthe port on which the external key manager is listening.

3. Ensure that your VPC has a return route to IP range35.199.192.0/19

   Your on-premises network must have a route for the35.199.192.0/19destination. For information about how to meet this requirement, seereturn route strategies for on-premise targets.

Return route strategies for on-premise targets

• For Cloud VPN tunnels that use static routing, manually create a route inyour on-premises network whose destination is35.199.192.0/19 and whosenext hop is the Cloud VPN tunnel. For Cloud VPN tunnelsthat use policy-based routing,configure the Cloud VPN's localtraffic selector and the on-premises VPN gateway'sremote traffic selector to include35.199.192.0/19.

• For Cloud VPN tunnels that use dynamic routing or forCloud Interconnect,configure custom advertisement mode for35.199.192.0/19 on the BGP session of the Cloud Router that managesthe tunnel or VLAN attachment.

Set up your external key manager

Follow the instructions from your EKM provider to set up your EKM.

Set up your crypto space

If you use Cloud EKM as part of a partner-managed EKM arrangement,these steps have been completed for you as part of your partner's provisioningprocess.

If your EKM provider is compatible with EKM key management from Cloud KMS, the following setupand configuration steps need to be made in your EKM:

• Create a crypto space for your Cloud KMS-managed resources in yourEKM.

• Grant your Cloud KMS service account access to your crypto spaceand the keys created in it.

• Set up Key Access Justifications policy to define which access justificationsshould be allowed or denied.

The exact process for each of these steps depends on your EKM. For moreinformation, see your EKM provider's documentation.

Create a Service Directory service endpoint

Create and configure a Service Directory service endpointin your VPC project that points to the private IP address andport of your your external key manager. If you are using a load balancer infront of multiple EKM replicas, use the load balancer's IP address and port.Ensure thenetwork field of your Service Directory service endpoint ispopulated.

Authorize Cloud EKM to access your VPC

For each key project, you must authorize Cloud EKM to access yourVPC on that project's behalf, even if the key project and theVPC project are the same. By authorizing access, keys in your key project canuse the VPC in your VPC project.

1. Ensure a Cloud EKM service account exists for the project.

   gcloud CLI

   gcloud beta services identity create \  --service=cloudkms.googleapis.com \  --project=KEY_PROJECT_ID

2. Grant theservicedirectory.viewer andservicedirectory.pscAuthorizedService in yourVPC project toservice-KEY_PROJECT_NUMBER@gcp-sa-ekms.iam.gserviceaccount.comFor help with getting your project ID and number, seeCreating and managing projects.

   gcloud CLI

   gcloud projects add-iam-policy-bindingVPC_PROJECT_ID \  --member=serviceAccount:service-KEY_PROJECT_NUMBER@gcp-sa-ekms.iam.gserviceaccount.com \  --role=roles/servicedirectory.viewergcloud projects add-iam-policy-bindingVPC_PROJECT_ID \  --member=serviceAccount:service-KEY_PROJECT_NUMBER@gcp-sa-ekms.iam.gserviceaccount.com \  --role=roles/servicedirectory.pscAuthorizedService

Create an EKM connection

To connect your external key manager to Cloud EKM, create anEKM connection in yourkey project.

gcloud beta kms ekm-connections createEKM_CONNECTION \    --locationLOCATION \    --service-directory-serviceSERVICE_DIRECTORY_SERVICE \    --hostnameHOSTNAME \    --server-certificates-filesSERVER_CERTIFICATE_FILES \    --key-management-mode manual

gcloud beta kms ekm-connections createEKM_CONNECTION \    --locationLOCATION \    --service-directory-serviceSERVICE_DIRECTORY_SERVICE \    --hostnameHOSTNAME \    --server-certificates-filesSERVER_CERTIFICATE_FILES \    --key-management-mode cloud-kms \    --crypto-space-pathCRYPTO_SPACE_PATH

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ekmConnections" \    --request "POST" \    --header "authorization: BearerTOKEN" \    --header "content-type: application/json" \    --header "x-goog-user-project:PROJECT_ID" \    --data '{      "name": "EKM_CONNECTION",      "serviceResolvers": [        {          "serviceDirectoryService": "SERVICE_DIRECTORY_SERVICE",          "hostname": "HOSTNAME",          "serverCertificates": [            {SERVER_CERTIFICATES            }          ]        }      ]      "keyManagementMode": "CLOUD_KMS",      "cryptoSpacePath": "CRYPTO_SPACE_PATH"    }'

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ekmConnections" \    --request "POST" \    --header "authorization: BearerTOKEN" \    --header "content-type: application/json" \    --header "x-goog-user-project:PROJECT_ID" \    --data '{      "name": "EKM_CONNECTION",      "serviceResolvers": [        {          "serviceDirectoryService": "SERVICE_DIRECTORY_SERVICE",          "hostname": "HOSTNAME",          "serverCertificates": [            {SERVER_CERTIFICATES            }          ]        }      ]    }'

Certificate status

Once you've uploaded a certificate for your EKM connection, you can check theoverall certificate status of the EKM connection as well as the status of eachcertificate from theKMS infrastructure page.

EKM connections have an overall status in theCertificate status column ofeach connection. If an EKM connection has a status other thanActive, werecommend updating the certificate(s) on your EKM connection.

Both EKM connections and individual certificates can have the following status:

• Active: The certificate is valid and is not nearing its expiration date.
• Expiring within 30 days: The certificate is valid, but has an expirationdate in the next 30 days.
• Expired: The certificate is expired and is no longer valid. We recommendupdating any expired certificates.
• Not valid yet: The certificate is not active. This can happen if thecertificate's start date is in the future.

If your certificate is no longer valid, update your EKM connection in theGoogle Cloud console.

Set an EKM connection as default

You can set an EKM connection as the default connection for a given projectand location. When a default EKM connection is set for a project and location,new Cloud EKM by VPC keys created in key rings in that locationuse the indicated EKM connection unless another EKM connection is selected.

To set an EKM connection as the default for its project and location, completethe following steps:

gcloud kms ekm-config update  --location=LOCATION  --default-ekm-connection=projects/PROJECT_ID/locations/LOCATION/ekmConnections/DEFAULT_EKM_CONNECTION

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ekmConfig" \    --request "PATCH" \    --header "authorization: BearerTOKEN" \    --header "content-type: application/json" \    --data '{"defaultEkmConnection": "projects/PROJECT_ID/locations/LOCATION/ekmConnections/DEFAULT_EKM_CONNECTION"}'

If another EKM connection had been set as the default for this location, theselected EKM connection replaces it as the default. Only one EKM connection canbe default for a given project and location.

What's next

• Create an external key.