Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

Google Cloud External Key Manager Resources

Managing Google EKM Cryptospaces

search

Please Note:

Managing Google EKM Cryptospaces

GCP also allows users to use EKM in the Google Cloud Key Management Service (KMS) for the creation and management of external keys through VPC connections that support Cloud KMS EKM management mode. Using the Cloud KMS EKM management mode in the VPC connection to the EKM, you create and manage your external keys from the Google Cloud KMS. The key material of these keys are generated from the EKM (CipherTrust Manager). These external keys that are created and managed using this type of VPC connection are also referred to as coordinated keys.

In support of the VPC connection type of Cloud KMS EKM management mode, CCKM provides cryptospaces. A cryptospace is a logical workspace only available in CCKM in which a group of keys resides. It is within a CCKM cryptospace that coordinated keys are created, rotated, and destroyed through a VPC connection. The EKM cryptospace keys (also referred to as endpoints) can only be managed through the Google Cloud KMS (and not through CipherTrust Manager or CCKM).

As part of creating a cryptospace in CCKM, grant your Cloud KMS service account access to your cryptospace and the keys to be created in it. In addition, set up a Key Access Justifications (KAJ) policy to define which access justifications should be allowed or denied. Keys created in a given cryptospace inherit the cryptospace’s default KAJ policy. For more information about the required parameters, see Create an EKM Cryptospace.

This page provides the prerequisites to allow a connection between CipherTrust Manager and Google Cloud External Key Manager Service. It also provides the steps to create a cryptospace in CCKM and then update it as required after it is created. After an EKM cryptospace is created, you can:

To view cryptospace endpoints, refer to Managing Google EKM cryptospace endpoints.

!!! note
    This document assumes that you are familiar with Google Cloud EKM and Cloud EKM keys to protect your data.

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.

  • For the 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.

  • Refer to Create an EKM connection via VPC for information on how to create an EKM connection via VPC from the Google console. Note there are prerequisite steps for creating an EKM connection via VPC that are provided within this Google documentation, including preparing a VPC network, creating a Service Directory service endpoint, and authorizing Cloud EKM to access your VPC. Be sure to perform all required prerequisite steps. Also included in the prerequisite steps is high-level information about how to set up your EKM.

  • Refer to Create an external key for information on how to create Cloud EKM keys on an existing key ring in Cloud KMS. Refer to Create a coordinated external key to create the coordinated external keys.

CipherTrust Manager Prerequisites

  • The CipherTrust Manager must have an IP address that is accessible from Google KMS. This is done by setting up a VPC. See VPC networks for more information.

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

    EKM UDE uses the same TLS certificate the CCKM web interface uses. If the TLS certificate for the CCKM web interface is updated, a restart of the CCKM service is required for the CCKM for UDE to use the updated certificate.

  • A Google Cloud project using Cloud KMS must be added to the CCKM before creating a cryptospace.

  • 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 cryptospace

To create a Google EKM cryptospace in the CCKM GUI and to make it available to Google Cloud EKM.

  1. 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 cryptospaces, 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.

    1. On Google Cloud, create a new project or choose an existing one.

    2. Copy the project ID.

    3. In CipherTrust Manager, open the Cloud Key Manager application.

    4. Navigate to KMS Containers > Google and open the Projects tab.

    5. Click Add Existing Project. The Add Existing Google Project screen displays.

    6. Under Select Method, select Manually Enter Project ID. This option allows you manually enter a project ID to connect to a project without credentials. This option is only applicable to creating and managing Key Encryption Keys (KEKs) for EKM usage.

      The Select From List option allows you to select an existing project from a list of connections stored in CipherTrust Connection Manager. This option is applicable to creating and managing Google Cloud keys.

    7. In Project ID, paste in the project ID.

    8. (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.

    9. Click Add Project.

  2. Login as a user in the 'CCKM Admins' group to create the cryptospace in the CCKM GUI.

    Note

    You can also create the cryptospace with the REST API or CLI to to associate meta information with the endpoint. Use the /v1/cckm/ekm/cryptospaces endpoint in the REST API, or ksctl cckm ekm cryptospaces create --ekm-cryptospace-create-jsonfile <meta_information_filename> in the CLI.

  3. Navigate to Cloud Key Manager > Services > Google Cloud EKM.

  4. Select the CryptoSpace(s) tab.

  5. Select Create CryptoSpace. The Create CryptoSpace screen displays.

  6. Under General Info, select/enter the following details:

    1. Specify a unique Name for the cryptospace.

    2. Specify a Hostname. This is the base url hostname for Ciphertrust Manager.

    3. In the Project ID drop-down list, select the GCP project to be associated with this cryptospace in CCKM.

    4. In the Location drop-down list, select the desired location of the cryptospace.

    5. (Optional) Enter a Description for the cryptospace.

    6. Click Next.

  7. Under CryptoSpace Type:

    1. Select either EKM CryptoSpace or Ubiquitous Data Encryption CryptoSpace from the available cryptospace types. The Ubiquitous Data Encryption CryptoSpace type allows you to create an EKM cryptospace that supports UDE. The default is EKM CryptoSpace. For Ubiquitous Data Encryption CryptoSpace, the default for requirement for Confidential VMs is Not Required. If selecting Ubiquitous Data Encryption CryptoSpace, select the requirement for Confidential VMs to originate wrap or unwrap requests under Require Confidential VMs. You can select Not Required, required For Wrap and Unwrap, required For Wrap only, or required For Unwrap only.

    2. Click Next.

  8. Under Service Accounts:

    1. In Service Account name, add the service account that is to be granted access to this cryptospace. Google service accounts are identified by an email in the form service-account-name@project-id.iam.gserviceaccount.com.

    2. Click Add Service Account. The account is added to the Service Accounts section. Expand the caret icon to view the permissions assigned to this service account. By default, all the checkboxes for the available permissions for the service account are selected. At least one permission must be selected for the given service account. You can add multiple service accounts.

    3. Deselect any permission(s) you wish to not use for the service account.

    4. Click Next.

  9. Under CryptoSpace Policy:

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

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

    3. Specify policies for UDE Attestation, if you previously selected the cryptospace type of UDE cryptospace. The values for Zones, Project IDs and Instance Names constrain which workloads can use the EKM UDE cryptospace endpoint, and are enforced whenever a Confidential VM originates a request.

    4. Click Next.

  10. Review your settings and click Create CryptoSpace. To modify any of the sections (General Info, CryptoSpace Type, Service Accounts, or CryptoSpace Policy), click Edit for the given section.

    The EKM cryptospace is created.

After the EKM cryptospace is created, create an EKM connection via VPC from the Google console. As part of this step, select Cloud KMS as the EKM management mode and provide the cryptospace URL in the Crypto Space path. To obtain the cryptospace URL from CCKM, copy the path within the Path column of the Cryptospace(s) tab in the Google Cloud External Key Manager page. Note that there are prerequisite steps provided within this Google documentation including preparing a VPC network, creating a Service Directory service endpoint, and authorizing Cloud EKM to access your VPC.

After you have created an EKM connection via VPC, proceed to creating an external key from the Google console. As part of creating an external key, select External under Protection Level and via VPC under External key manager (EKM) connection type. Select the EKM via VCP connection that you created from the drop-down list. Once the key is created, it displays on the Key ring details page within the Google console. It also then displays within Cryptospace Endpoint(s) tab in the Google Cloud External Key Manager page of CCKM. Thereafter, you can begin using these Cloud EKM keys to protect your data.

Refreshing EKM cryptospaces

To refresh all EKM cryptospaces:

  1. Open the Cloud Key Manager application.

  2. In the left pane, click Services > Google Cloud EKM. The Google Cloud External Key Manager page displays.

  3. Click the CryptoSpace(s) tab. The list of cryptospace added to CCKM is displayed.

  4. Click Refresh.

The refreshed cryptospaces are listed on the CryptoSpace(s) page.

Viewing EKM cryptospaces

The CryptoSpace(s) tab shows the list of existing cryptospaces within CCKM. Search for cryptospace by Name or Project.

To view the list of Google cryptospace endpoints available on CCKM:

  1. Open the Cloud Key Manager application.

  2. In the left pane, click Services > Google Cloud EKM. The Google Cloud External Key Manager page displays.

  3. Click the CryptoSpace(s) tab. The list of cryptospaces added to CCKM is displayed. The tab displays the following details:

    FieldDescription
    NameName of the cryptospace.
    BlockIndicates whether the cryptospace is blocked or unblocked.
    CryptoSpace TypeCryptospace type. There are two types of cryptospaces. One for EKM endpoints (ekm) and another for EKM UDE endpoints (ekm-ude).
    Require Confidential VMsIndicates whether a wrap or unwrap request is required to originate from a confidential VM.
    HostnameThe base url hostname for Ciphertrust Manager.
    ProjectName of the project.
    PathExternal-KMS-defined resource identifier for the cryptospace.
    EndpointsNumber of endpoints within the cryptospace.
    LocationLocation of the cryptospace.
    Creation DateTime when the cryptospace was created.

To view the custom columns, click the Customize View (Custom View) icon, select the desired option, and click OK to display the column. To view the Cryptospace details page, click on the name of the cryptospace under the Name column. To view cryptospace endpoints, refer to Managing Google EKM cryptospace endpoints.

Changing the base hostname

You can patch the /v1/cckm/ekm/cryptospaces/{id}REST API endpoint, as described in the API Guide, or use ksctl cckm ekm cryptospaces update --id <cryptospace-id> --ekm-cryptospace-hostname <new-base-url-hostname> in the CLI.

In the GUI:

  1. Login to the CipherTrust Manager products page as a user in the 'CCKM Admins' group.

  2. Navigate to Cloud Key Manager>Services>Google Cloud EKM>CryptoSpace(s) tab.

  3. Find the cryptospace in the list, and click the ellipsis icon(...) at the far right for options.

  4. Click View/Edit.

  5. In the General Info section, enter a new Hostname and click Update.

Block or unblock a cryptospace

Blocking and unblocking a cryptospace is a way to temporarily suspend and restore access to the cryptospace and its keys. You can block the /v1/cckm/ekm/cryptospaces/{id}/blockREST API endpoint or unblock the /v1/cckm/ekm/cryptospaces/{id}/unblockREST API endpoint, as described in the API Guide. In the CLI, you can use ksctl cckm ekm cryptospaces block --id <cryptospace-id> to block a cryptospace and ksctl cckm ekm cryptospaces unblock --id <cryptospace-id> to unblock a cryptospace.

In the GUI:

  1. Login to the CipherTrust Manager products page as a user in the 'CCKM Admins' group.

  2. Navigate to Cloud Key Manager>Services>Google Cloud EKM>CryptoSpace(s) tab.

  3. Find the cryptospace in the list, and click the ellipsis icon(...) at the far right for options.

  4. Click Block or Unblock, depending on whether the cryptospace is currently in a blocked or unblocked state.

  5. You are asked to confirm the action. Click Block or Unblock again.

    The status in the Blocked column updates on the table.

Delete a cryptospace

You can delete the /v1/cckm/ekm/cryptospaces/{id}/REST API endpoint, as described in the API Guide. In the CLI, you can use ksctl cckm ekm cryptospaces delete --id <cryptospace-id>. This permanently deletes the cryptospace.

Caution

Once the cryptospace has been deleted, it cannot be restored.

In the GUI:

  1. Login to the CipherTrust Manager products page as a user in the 'CCKM Admins' group.

  2. Navigate to Cloud Key Manager>Services>Google Cloud EKM>CryptoSpace(s) tab.

  3. Find the cryptospace in the list, and click the ellipsis icon(...) at the far right for options.

  4. Click Delete.

    A confirmation window appears, as this operation is irreversible.

  5. Enable the I wish to delete this cryptospace checkbox and click Delete.

Update a Confidential VM requirement

You can patch the /v1/cckm/ekm/cryptospaces/{id}REST API endpoint, as described in the API Guide, or use ksctl cckm ekm cryptospaces update --id <cryptospace-id> --cvm-required-for-encrypt=true in the CLI.

In the GUI:

  1. Login to the CipherTrust Manager products page as a user in the 'CCKM Admins' group.

  2. Navigate to Cloud Key Manager>Services>Google Cloud EKM>CryptoSpace(s) tab.

  3. Find the cryptospace in the list, and click the ellipsis icon(...) at the far right for options.

  4. Click View/Edit.

  5. Under CryptoSpace Type, select/enter the following details:

    1. From the available cryptospace types, select Ubiquitous Data Encryption CryptoSpace.

    This option allows you to create an EKM cryptospace that supports UDE.

    1. Under Require Confidential VMs, 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.

    2. Click Update.

Update a service account

In the GUI:

  1. Login to the CipherTrust Manager products page as a user in the 'CCKM Admins' group.

  2. Navigate to Cloud Key Manager>Services>Google Cloud EKM>CryptoSpace(s) tab.

  3. Find the cryptospace in the list, and click the ellipsis icon(...) at the far right for options.

  4. Click View/Edit.

  5. Under Service Accounts, select/enter the following details:

    1. In Service Account name, add the service account that is to be granted access to this cryptoSpace. Google service accounts are identified by an email in the form service-account-name@project-id.iam.gserviceaccount.com.

    2. Click Add Service Account.

      The account is added to the Service Accounts section. Expand the caret icon to view the assigned permissions. By default, all the checkboxes for the available permissions for the service account are selected. At least one permission must be selected for the given service account.

  6. Deselect any permission(s) you wish to not use for the service account.

  7. Click Update.

Update a cryptospace policy

A cryptospace endpoint inherits its policy from the cryptospace in which it resides. Changing Cryptospace policy affects all the endpoints that reside in this cryptospace.

In the GUI:

  1. Login to the CipherTrust Manager products page as a user in the 'CCKM Admins' group.

  2. Navigate to Cloud Key Manager>Services>Google Cloud EKM>CryptoSpace(s) tab.

  3. Find the cryptospace in the list, and click the ellipsis icon(...) at the far right for options.

  4. Click View/Edit

    The policy options are visible in the CryptoSpace Policy section. The Basic View is selected by default.

  5. Skip to step 6 for editing in Raw View. In Basic View, you can edit the following policies:

    • Clients allowed to use the cryptospace, specified as a list separated by commas. Google service accounts are in the format of an email address, <service-account-name>@<project-id>.iam.gserviceaccount.com.

    • Whether Key Access Justifications are required or not.

    • If Key Access Justifications are required, which justification reasons are accepted.

    • EKM UDE endpoints have additional fields for Zones, Project IDs, and Instance Names. These settings constrain which workloads can use the EKM UDE Endpoint, and are enforced whenever a Confidential VM originates a request.

  6. In Raw View, you can edit the following parameters:

    • package controls the rego policy package name

    • default allow is a mandatory line to declare whether the rego policy is enforced. Setting this to false enables the policy and setting it to true disables the policy.

    • input.clients controls which clients are allowed to access the endpoint. This should match the clients on Google Cloud Service Accounts that are allowed to perform wrap or unwrap operations.

    • default allowedJustification controls whether Key Access Justifications are required or not.

    • input.justificationReason controls what justification reason needs to be provided for Google Cloud EKM to initiate a wrap or unwrap operation. You can remove this line, or comment it out with # at the start of the line if you do not require the feature.

    • EKM UDE endpoints have additional lines to set Zones, Project IDs, and Instance Names, which are input.attestationZones, input.attestationProjectIDs, and input.instanceNames respectively. These settings constrain which workloads can use the EKM UDE Endpoint, and are enforced whenever a Confidential VM originates a request.

  7. Click Update.

Key Access Justifications

Justification reasons are used by the Key Access Justifications feature in Google Cloud. This feature is optional for EKM and EKM UDE. When justification reasons are set, they need to be provided for Google Cloud EKM to initiate a wrap or unwrap operation.

The supported justification reasons are:

  • REASON_UNSPECIFIED

  • CUSTOMER_INITIATED_SUPPORT

  • GOOGLE_INITIATED_SERVICE

  • THIRD_PARTY_DATA_REQUEST

  • GOOGLE_INITIATED_REVIEW

  • CUSTOMER_INITIATED_ACCESS

  • GOOGLE_INITIATED_SYSTEM_OPERATION

  • REASON_NOT_EXPECTED

  • MODIFIED_CUSTOMER_INITIATED_ACCESS

  • GOOGLE_RESPONSE_TO_PRODUCTION_ALERT

  • MODIFIED_GOOGLE_INITIATED_SYSTEM_OPERATION

  • CUSTOMER_AUTHORIZED_WORKFLOW_SERVICING

Note

These justification reasons appear with spaces instead of underscores and with lowercase letters in the CipherTrust Manager GUI Basic View. For example, GOOGLE_INITIATED_REVIEW appears as Google Initiated Review in the Basic View.

In OPA format, this is expressed as:

package example
default allow = false
allow {
# Uncomment and add specific clients in below line to allow wrap/unwrap from Google services
# input.clients == {"abc@yahoo.com", "abc@google.com", "abc@msn.com"}[_]
input.justificationReason == {"REASON_UNSPECIFIED","CUSTOMER_INITIATED_SUPPORT","GOOGLE_INITIATED_SERVICE","THIRD_PARTY_DATA_REQUEST",
"GOOGLE_INITIATED_REVIEW","CUSTOMER_INITIATED_ACCESS","GOOGLE_INITIATED_SYSTEM_OPERATION","REASON_NOT_EXPECTED",
"MODIFIED_CUSTOMER_INITIATED_ACCESS"}[_]
}

On this page