Managing Google EKM Endpoints
Google Cloud External Key Manager (EKM) Service can access CipherTrust Cloud Key Manager (CCKM) after you meet some prerequisites.
Once this access is established, users in the 'CCKM Admins' group and 'Key Users' group can create and manage an endpoint in CCKM for Google Cloud EKM service to access a Key Encryption Key (KEK) using CCKM's GUI, CLI and REST API.
You can create a regular EKM Endpoint or an External Key Manager Ubiquitous Data Encryption (EKM UDE) Endpoint. The architecture and use cases for the two endpoint types are described on the Google Cloud External Key Manager Resources page.
After you have created an endpoint, you can:
Enable or disable the wrapping and unwrapping operation. This allows you to avoid deleting the endpoint, and temporarily suspend Google Cloud EKM's ability to use the KEK.
View activity for a wrap or unwrap endpoint. Google Cloud Key Management Service (KMS) consumes these endpoints.
Prerequisites
To allow a connection between CipherTrust Manager and Google Cloud External Key Manager Service, some network and security configuration must be in place in both entities.
Google Cloud Platform Prerequisites
A Google Cloud project using Cloud KMS must exist for the CCKM EKM integration's use. You can create a new project or choose an existing project in your Google Cloud account. You need to provide either a project ID or the private key file associated with the service account to add a Google project to CipherTrust Manager. The project ID is the simplest path to add the Google Cloud project just for EKM usage. The private key file is required if you want add a Google Cloud connection to CipherTrust Manager.
If you are using confidential computing environments for EKM UDE, an additional Google Cloud project needs to be associated with the confidential computing environments. A Google service account with the Identity and Access Management (IAM) permission
compute.instances.getShieldedInstanceIdentity
must have access to the project. This permission is required to carry out full verification of attestation evidence.If you wish to require Key Access Justifications (KAJ) you need to configure KAJ on Google Cloud.
CipherTrust Manager Prerequisites
The CipherTrust Manager must have a public IP address with the 443 HTTPS port open. See Planning Network Configuration for details.
The CipherTrust Manager must be reachable through a Fully Qualified Domain Name (FQDN).
The web interface must have a TLS certificate signed by an external Certificate Authority (CA) trusted by Google Cloud Platform. Google Cloud trusts certificates issued by well-known public CAs such as Verisign. Alternatively, you can create a certificate chain with Google's Certificate Authority Service and upload the chain to CipherTrust Manager.
For correct operation of UDE in a cluster of CipherTrust Manager nodes, all of the nodes must be configured with the same TLS certificate. This requirement is a consequence of termination of TLS sessions for UDE occurring at the individual CipherTrust Manager nodes rather than at the cluster load balancer.
A Google Cloud project using Cloud KMS must be added to the CipherTrust Cloud Key Manager before creating an endpoint.
For EKM UDE endpoints using confidential computing environments, the Google Cloud project associated with the confidential computing environments must be added to CCKM through connection manager for CCKM to completely verify attestation evidence.
Prepare an EKM endpoint
Below, we provide steps to create a Google endpoint in the CCKM GUI and to make the endpoint available to Google Cloud EKM.
Add the Google Cloud project using Google Cloud KMS to CCKM.
This action consumes one CCKM license cloud unit.
Note
These steps demonstrate the simplest configuration to add a Google project ID to CCKM just for EKM endpoints, without using an active connection to Google Cloud. If you want to monitor and manage a Google Cloud account connection and associated resources on CipherTrust Manager, you can also add a Google Cloud connection using connection manager, and then use the connection to retrieve project IDs.
On Google Cloud, create a new project or choose an existing one.
Copy the project ID.
In CipherTrust Manager, open the Cloud Key Manager application.
Navigate to KMS Containers > Google and open the Projects tab.
Click Add Existing Project
In the popup window, under Select Method, switch to Manually Enter Project ID.
In Project ID, paste in the project ID.
(Optional) Use the Enable success audit events toggle to enable or disable audit recording of successful operations within the given Google cloud project. This toggle is set to enable, by default.
Click Add Project.
Login as a user in the 'CCKM Admins' group to create the endpoint in the CCKM GUI.
Note
You can also create the endpoint with the REST API or CLI to to associate meta information with the endpoint. Use the
/v1/cckm/ekm/endpoints
endpoint in the REST API, orksctl cckm ekm endpoints create --ekm-endpoint-create-jsonfile <meta_information_filename>
in the CLI.Navigate to Cloud Key Manager > Services > Google Cloud EKM Endpoints.
Click Create Endpoint
Provide a Name and a Key URI Hostname for your endpoint. For the Key URI Hostname, enter the the FQDN of the CipherTrust Manager instance.
Note
The Key URI Hostname will be used to construct the URL Google will use to send requests to CipherTrust Manager and for JWT validations. The web interface of the CipherTrust Manager must have a valid TLS certificate signed by a trusted CA.
If the SSL termination takes place at the CipherTrust Manager, the Key URI Hostname must match the FQDN of the CipherTrust Manager. If the SSL termination takes place at the load balancer in front of the CipherTrust Manager, the Key URI Hostname must match the FQDN of the public-facing load balancer. Wildcard certificates are supported.
Select EKM endpoint as the Endpoint type.
Note
Ubiquitous Data Encryption endpoint steps are described below.
Select either Symmetric or Asymmetric for Key Type of the KEK. If selecting Symmetric, click Next thereafter. If selecting Asymmetric, select key algorithm from the Key Algorithm drop down and click Next.
Endpoints with symmetric keys can be used for wrapping and unwrapping operations, whereas endpoints with asymmetric keys can be used for signing and fetching the public key.
Symmetric key type is always an AES-256 symmetric key. Symmetric keys for EKM endpoints must have the Encrypt, Decrypt, Wrap, and Unwrap usage masks. In addition, this key type must not be exportable or deletable.
Asymmetric key type has several RSA and EC algorithm options. Asymmetric keys for EKM endpoints must have the Sign and Verify usage masks. In addition, this key type must not be exportable or deletable. The available key algorithms for asymmetric keys are:
RSA_SIGN_PSS_2048_SHA256
RSA_SIGN_PSS_3072_SHA256
RSA_SIGN_PSS_4096_SHA256
RSA_SIGN_PSS_4096_SHA512
RSA_SIGN_PKCS1_2048_SHA256
RSA_SIGN_PKCS1_3072_SHA256
RSA_SIGN_PKCS1_4096_SHA256
RSA_SIGN_PKCS1_4096_SHA512
EC_SIGN_P256_SHA256
EC_SIGN_P384_SHA384
Choose to either create a new key or copy an existing key.
If creating a new key, select Create New Key, enter the name of the key, and click Next. If copying an existing key, select Copy Existing Key, select a key from the Key drop down, and click Next.
Caution
Although it is possible to copy a key that is associated with an existing EKM or EKM UDE endpoint, we recommend that you do not do this.
Note
The Copy Existing Key option is applicable to the migration of an EKM endpoint from one CipherTrust Manager deployment to another. When creating a new EKM endpoint in the new deployment using this option, CCKM uses the key name you select from the Key drop down and associates all of the existing versions of a CipherTrust Manager key to the new endpoint.
Edit the Endpoint Policy.
Provide the list of Google service accounts which are granted access to the endpoints in the Clients field, separating the clients with commas. Google service accounts are in the format of an email address,
<service-account-name>@<project-id>.iam.gserviceaccount.com
.Edit the Key Access Justification settings. You can disable the requirement for Key Access Justifications, or specify which justification reasons are needed for the EKM endpoint to initiate a wrap or unwrap request.
Click Next.
Note
You can edit these endpoint policies later, if desired.
Review your settings and click Add Endpoint.
The EKM endpoint is created.
Caution
Do not edit the KEK through the general CipherTrust Manager key management functions. Do not modify the KEK through the Keys menu in the GUI, ksctl keys commands in the CLI, or the
/v1/vault/keys2
endpoint in the REST API. This can result in the KEK becoming unavailable to the Google Cloud EKM service unexpectedly.Enable Key Access Justifications in your Google Account, if you require this feature, and you have not already enabled this feature.
Proceed to establish a connection between Google Cloud and the endpoint.
Prepare an EKM UDE endpoint
Add the Google Cloud project using Google Cloud KMS to CCKM.
This action consumes one CCKM license cloud unit.
Note
These steps demonstrate the simplest configuration to add a Google project ID to CCKM just for EKM endpoints, without using an active connection to Google Cloud. If you want to monitor and manage a Google Cloud account connection and associated resources on CipherTrust Manager, you can also add a Google Cloud connection using connection manager, and then use the connection to retrieve project IDs.
On Google Cloud, create a new project or choose an existing one.
Copy the project ID.
In CipherTrust Manager, open the Cloud Key Manager application.
Navigate to KMS Containers > Google and open the Projects tab.
Click Add Existing Project
In the popup window, under Select Method, switch to Manually Enter Project ID.
In Project ID, paste in the project ID.
(Optional) Use the Enable success audit events toggle to enable or disable audit recording of successful operations within the given Google cloud project. This toggle is set to enable, by default.
Click Add Project.
Login as a user in the 'CCKM Admins' group to create the endpoint in the CCKM GUI.
Note
You can also create the endpoint with the REST API or CLI to to associate meta information with the endpoint. Use the
/v1/cckm/ekm/endpoints
endpoint in the REST API, orksctl cckm ekm endpoints create --ekm-endpoint-create-jsonfile <meta_information_filename>
in the CLI.Navigate to Cloud Key Manager > Services > Google Cloud EKM Endpoints.
Click Create Endpoint
Provide a Name and a Key URI Hostname for your endpoint. For the Key URI Hostname, enter the the FQDN of the CipherTrust Manager instance.
Note
The Key URI Hostname will be used to construct the URL Google will use to send requests to CipherTrust Manager and for JWT validations. The web interface of the CipherTrust Manager must have a valid TLS certificate signed by a trusted CA.
If the SSL termination takes place at the CipherTrust Manager, the Key URI Hostname must match the FQDN of the CipherTrust Manager. If the SSL termination takes place at the load balancer in front of the CipherTrust Manager, the Key URI Hostname must match the FQDN of the public-facing load balancer. Wildcard certificates are supported.
Select Ubiquitous Data Encryption Endpoint as the Endpoint type. Click Next.
Select the requirement for Confidential VMs to originate wrap or unwrap requests. You can select Not Required, required For Wrap and Unwrap, required For Wrap only, or required For Unwrap only.
Choose to either create a new key or copy an existing key.
If creating a new key, select Create New Key, enter the name of the key, and click Next. If copying an existing key, select Copy Existing Key, select a key from the Key drop down, and click Next.
Caution
Although it is possible to copy a key that is associated with an existing EKM or EKM UDE endpoint, we recommend that you do not do this.
Note
The Copy Existing Key option is applicable to the migration of an EKM endpoint from one CipherTrust Manager deployment to another. When creating a new EKM endpoint in the new deployment using this option, CCKM uses the key name you select from the Key drop down and associates all of the existing versions of a CipherTrust Manager key to the new endpoint.
The supported key type is AES-256. Valid keys must have the Encrypt, Decrypt, Wrap, and Unwrap usage masks and cannot be exportable or deletable.
Specify the endpoint policy.
Provide the list of Google service accounts which are granted access to the endpoints in the Clients field, separating the clients with commas. Google service accounts are in the format of an email address,
<service-account-name>@<project-id>.iam.gserviceaccount.com
.Edit the Key Access Justification settings. You can disable the requirement for Key Access Justifications, or specify which justification reasons are needed for the EKM endpoint to initiate a wrap or unwrap request. Click Next.
Note
You can edit these endpoint policies later, if desired.
Specify policies for UDE Attestation. The values for Zones, Project IDs and Instance Names constrain which workloads can use the EKM UDE Endpoint, and are enforced whenever a Confidential VM originates a request.
Click Next.
Review your settings and click Add Endpoint. Click Close to close.
A unique URI is created, associated with the KEK that acts as the Google EKM UDE endpoint key. The hostname is applied to the URI, to create a path that Google Cloud can access.
Caution
Do not edit the KEK through the general CipherTrust Manager key management functions. Do not modify the KEK through the Keys menu in the GUI, ksctl keys commands in the CLI, or the
/v1/vault/keys2
endpoint in the REST API. This can result in the KEK becoming unavailable to the Google Cloud EKM service unexpectedly.If you intend to use one or more confidential computing environments, you must add an additional Google Cloud project associated with the confidential computing VMs. Add a Google Cloud connection on CipherTrust Manager through Connection Manager. You need to provide the private key file associated with the service account.
Note
For this case, the Google Cloud project needs to be associated with a Google service account with the Identity and Access Management (IAM) permission
compute.instances.getShieldedInstanceIdentity
. This ensures CCKM can fully verify attestation evidence.Enable Key Access Justifications in your Google Account, if you require this feature, and you have not already.
Proceed to establish a connection between Google Cloud and the endpoint.
Establish a Connection Between Google Cloud and the Endpoint
Google Cloud configuration to connect to the endpoint depends on whether the connection is over the internet or Google Cloud VPC.
If you want to set up EKM communication over the internet, follow Using Cloud EKM via the Internet Google documentation to create the necessary Google Cloud EKM key. You need the following values related to CipherTrust Manager:
The full Key URI, including hostname, of the EKM endpoint.
The geographical region where the CipherTrust Manager instance is deployed. In Google Cloud, choose a location for the Key Ring that is as close as possible to reduce network latencies.
If you want to set up EKM communication over VPC, follow Using Cloud EKM with VPC Google documentation to create the necessary Google Cloud entities and connections. On Google Cloud, you need to:
prepare a VPC network.
create a Service Directory service endpoint using the private IP address of CipherTrust Manager and port 443.
authorize CloudEKM to access the VPC.
create a connection using Location, Service Directory, EKM Hostname (CipherTrust Manager hostname), and CipherTrust Manager web certificate. This connection is created in your key project using KMS infrastructure.
create a Cloud EKM key using the EKM or EKM UDE endpoint Key URI path.
Do the following to obtain CipherTrust Manager-related values needed by Google Cloud:
Note the fully qualified domain name of the CipherTrust Manager. This value and the port number
443
are needed to create the Service Directory service endpoint.Download the web interface certificate.
ksctl interfaces certificate get --name web --icertfile <desired-filename>.pem
On the web console, this certificate is available at Admin Settings > Interfaces.
Convert the downloaded certificate to DER format. This is needed to create the EKM connection on Google Cloud.
openssl x509 -outform der -in <filename>.pem -out <filename>.der
Make a note of where the CipherTrust Manager is geographically deployed. In Google Cloud, choose a location for the EKM connection that is as close as possible to reduce network latencies.
Copy the Key URI path of the EKM or EKM UDE endpoint. When you create the corresponding Cloud EKM key, provide the Key path in the format
api/v1/cckm/ekm/endpoints/<endpoint_id>
. Do not include the CipherTrust Manager hostname in the path.
Once a connection is established, consult documentation for your desired Google CMEK service integrated with Cloud EKM to grant permissions for the CMEK service to use the KEK in Cloud KMS. Consult this documentation as well for particular encryption and decryption scenarios for the CMEK service.
For example:
Protecting Compute Engine resources with Cloud KMS keys
Note
Only CMEK services integrated with EKM are supported with CCKM EKM endpoints. These are "Hold Your Own Key" (HYOK) integrations, where you manage and control the base KEK inside of CCKM. Google Cloud has additional CMEK services that do not follow the HYOK model and do not integrate with EKM. Consult Google Cloud EKM documentation for a list of supported CMEK services.
For using the EKM UDE functionality either on premise or in a confidential VM, consult the Google Cloud Platform open source repository for the Split Trust Encryption Tool.
Rotate the Key Encryption Key
For EKM UDE endpoints, and EKM endpoints using symmetric key type, you can create a new version of the KEK which will be applied to future wrap operations. This can be done even if the endpoint is disabled. Rotating the KEK regularly is a security best practice.
Note
There is no extra configuration required on Google Cloud. The next time Google Cloud tries a wrap operation with the KEK, the new key material is automatically used to wrap.
You can also post to the /v1/cckm/ekm/endpoints/{id}/rotate
REST API endpoint, as described in the API Guide, or use ksctl cckm ekm endpoints rotate --id <endpoint_id>
in the CLI.
In the GUI:
Login to the CipherTrust Manager products page as a user in the 'CCKM Admins' group.
Navigate to Cloud Key Manager>Services>Google Cloud EKM.
Find the endpoint in the list, and click the ellipsis icon (...) at the far right for options.
Select Rotate.
Change the base hostname
You can also patch the /v1/cckm/ekm/endpoints/{id}
REST API endpoint, as described in the API Guide, or use ksctl cckm ekm endpoints update --id <endpoint-id> --hostName <new-base-url-hostname>
in the CLI.
In the GUI:
Login to the CipherTrust Manager products page as a user in the 'CCKM Admins' group.
Navigate to Cloud Key Manager>Services>Google Cloud EKM
Find the endpoint in the list, and click the ellipsis icon (...) at the far right for options.
Click View/Edit.
In the General Info section, enter a new Key URI hostname and click Update.
Enable or Disable Key Wrapping
You can post to the /v1/cckm/ekm/endpoints/{id}/enable
and /v1/cckm/ekm/endpoints/{id}/disable
REST API endpoints, as described in the API Guide. In the CLI, you can use ksctl cckm ekm endpoints enable --id <endpoint-id>
and ksctl cckm ekm endpoints disable --id <endpoint-id>
.
This is a way to temporarily remove and restore client access to an endpoint without permanently deleting the endpoint and its KEK.
In the GUI:
Login to the CipherTrust Manager products page as a user in the 'CCKM Admins' group.
Navigate to Cloud Key Manager>Services>Google Cloud EKM
Find the endpoint in the list, and click the ellipsis icon(...) at the far right for options.
Click Enable or Disable.
Delete the Endpoint
You can delete the /v1/cckm/ekm/endpoints/{id}/
REST API endpoint, as described in the API Guide. In the CLI, you can use ksctl cckm ekm endpoints delete --id <endpoint-id>
. This permanently deletes the KEK.
Caution
Once the endpoint has been deleted, the key cannot be restored.
In the GUI:
Login to the CipherTrust Manager products page as a user in the 'CCKM Admins' group.
Navigate to Cloud Key Manager>Services>Google Cloud EKM
Find the endpoint in the list, and click the ellipsis icon(...) at the far right for options.
Click Delete.
A confirmation window appears, as this operation is irreversible.
Enable the I wish to delete this endpoint checkbox and click Delete.
View Activity for a Wrap or Unwrap Endpoint
Google Cloud KMS calls EKM endpoints to perform a wrap or unwrap operation on a base64 blob, and therefore protect some data on behalf of a CMEK service integrated with Cloud EKM such as BigQuery or Compute Engine. EKM UDE endpoints are called from workloads via Google-provided integration tools.
Standard EKM wrapping functionality is performed with /v1/cckm/ekm/endpoints/{id}:wrap
and /v1/cckm/ekm/endpoints/{id}:unwrap
REST API endpoints, as described in the REST API endpoint. Google provided tools can find and make calls to wrap and unwrap endpoints without user intervention, if Google Cloud KMS has correctly configured the Cloud EKM key, and the CMEK service is correctly configured to access the key on Google Cloud KMS. This configuration happens as part of preparing a new endpoint.
EKM UDE endpoints also allow for confidential wrapping and unwrapping, which requires the use of a secure session and a policy enforcement check with an authorized confidential VM, through /v1/cckm/ekm/endpoints/{id}:confidentialwrap
and /v1/cckm/ekm/endpoints/{id}:confidentialunwrap
.
Requests to these endpoints generate a record under Records> Server Records in the GUI, and the /v1/audit/records
endpoint in the API. These records can be helpful to monitor EKM activity or troubleshoot EKM problems.
View Attestation Activity for an EKM UDE Endpoint
In EKMS, using an EKM UDE endpoint for wrap or unwrap operations requires a three-step process:
The establishment of a secure TLS 1.3 session between the Google-provided integration component and CipherTrust Manager.
The optional provision of attestation information/proofs over this secure session, allowing CCKM to assess the data-in-use protection capabilities of the requester.
Note
During this process, CCKM attempts to fetch a public key. This operation requires a Google service account with the IAM permission
compute.instances.getShieldedInstanceIdentity
registered with CCKM as a connection. If the public key cannot be fetched, an error is logged,unable to check validity of instance key...
. Wrap and unwrap operations are allowed to proceed.The submission and handling of (confidential) wrap and unwrap requests, over this secure session.
The TLS sessions which are established have a session lifetime of 600 seconds, allowing multiple confidential wrap/unwrap requests to be handled by any given session. Thus, any confidential wrap or unwrap request can be associated with a secure channel and any secure channel can be associated with a set of attestation proofs (or none in the case of an on premise, non-confidential environment).
All relevant details are captured in Records> Server Records in the GUI, and the /v1/audit/records
endpoint in the API, allowing cross-referencing of confidential wrap/unwrap requests with sessions with attestations.
Note
The EKM UDE API contains a set of ‘Session’ endpoints, namely: session/begin session; session/handshake; session/negotiate attestation; session/finalize and session/end session.
These endpoints allow the establishment of a secure TLS 1.3 session between the Google-provided integration component and CipherTrust Manager. Further details on these endpoints is beyond the scope of this document.