Please Note:

Google Cloud EKM APIs

Google Cloud External Key Manager (EKM) is a cloud native service that provides access to an external key encryption key (KEK) for use as a wrapping key in Google Cloud Platform (GCP) Projects. CCKM integration with Google Cloud EKM enables you to:

Manage endpoints for KEKs for keys added to the key ring through GCP EKM
Configure and manage policy sets

The AES256 wrap/unwrap KEK allows users, developers, and organizations to maintain separation between encrypted data at rest and encryption keys.

The benefits of using CCKM Google Cloud EKM Endpoints include:

Secure generation, storage and protection of your KEK.
Privately maintained key provenance, managed access control, and centralized key management.
Full life cycle management of your encryption key.
Visibility for compliance.

GCP allows users to use Cloud External Key Management (EKM) in the Google Cloud Key Management Service (KMS) for Google Projects. CCKM protects your data in the GCP while your encryption keys are stored in CipherTrust Manager outside of GCP. Users create a Key Encryption Key (KEK) in CCKM, create a Cloud EKM key in Google Cloud, using the KEK's URI to identify the externally-managed key in Google Cloud KMS, and use the keys to protect data in a Customer-Managed Encryption Key (CMEK) integration service, to encrypt data using a symmetric key, or to sign with an asymmetric key. In this scenario, Google Cloud KMS does not store the external key material.

The following diagram shows how the Cloud KMS and CCKM fit into the key management model, using BigQuery and Compute Engine as example services.

Note

If you are deploying a new CipherTrust Manager instance exclusively or primarily to use the Google Cloud EKM service, we recommend deploying the instance geographically close to one of the Google Cloud KMS regions where you intend to set up the Google Cloud KMS Key Ring.

We have tested the following Google Customer-Managed Encryption Key (CMEK) integration services for Google Cloud EKM:

BigQuery
Compute Engine

All other Google CMEK integration services for Google Cloud EKM are not validated by Thales, but are expected to work and are supported. Consult Google EKM documentation for the full list of Google CMEK services for EKM. Only CMEK services integrated with Google Cloud 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.

The connection between Google Cloud and CCKM can take place over the internet, or mediated through a Google Cloud Virtual Private Cloud (VPC) network.

Ubiquitous Data Encryption

CCKM provides another integration with EKM, called Google Cloud External Key Manager Ubiquitous Data Encryption (EKM UDE). While standard EKM protects data in use for CMEK services in Google Cloud, EKM UDE protects data as it moves between two environments, called workloads, mediated by Google Cloud KMS. The two workloads can be two Google Cloud Confidential VMs, two non-confidential environments (on-premises or cloud), or one Confidential VM and one non-confidential environment.

CCKM provides options in the EKM UI menus to manage endpoints, configure and manage policy sets, and configure confidential computing requirements for access to KEKs.

The UDE version of EKM provides additional security, access control and auditability guarantees, namely:

the end-to-end encryption of Data Encryption Keys (DEKs) between workloads and the external key manager
the leveraging of Confidential VMs to provide strong guarantees of the runtime privacy of customer data (data-in-use security)
the use of independently-verifiable attestations of the runtime environment, allowing the EKM to strongly differentiate between protected and unprotected environments

An example architecture is shown below, showing a potential interaction between CCKM, Google Cloud Storage, and a Confidential VM. For any type of workload, CCKM holds the KEK needed to wrap and unwrap DEKs. Communications between CCKM and a Confidential VM require an Attestation of Confidentiality sequence for an additional guarantee that only the intended workload can access the KEK.

These CipherTrust Cloud Key Manager keys can be used in four main use cases within GCP:

A DEK is generated within a GCP confidential VM, then is wrapped by the CCKM KEK. The KEK is configured such that unwrapping of the wrapped key is only possible by an attested, verified confidential VM. You can place additional restrictions on instance ID, project ID, and zones, which limit KEK use to specific confidential VMs.
A DEK is generated on-premise, in a regular (non-confidential computing) environment, then is wrapped by the CCKM KEK. The data is uploaded to Google Cloud Storage (GCS) and the KEK is configured such that unwrapping of the wrapped key (and hence the protected data) is only possible by an attested, verified confidential VM. You can place additional restrictions on instance ID, project ID, and zones, which limit KEK use to specific confidential VMs.
A DEK is generated within a GCP confidential VM, then is wrapped by the CCKM KEK. The KEK is configured such that wrapping of the wrapped key is only possible in an attested, verified confidential VM, but that unwrapping is possible in a regular (non-confidential computing) environment. You can place additional restrictions on instance ID, project ID, and zones, which limit KEK use to specific confidential VMs.
A DEK is generated on-premise in a regular environment, then is wrapped by CipherTrust-managed KEK. The data is moved to another regular environment (on cloud or on-premise). The KEK is configured such that unwrapping of the wrapped data is possible in a second regular environment.

These four cases, respectively, give the following guarantees:

In case 1, the guarantee that the protected DEK/data is only accessible by a confidential VM.
In case 2, the guarantee that data encrypted on-premise and migrated to the cloud will only be accessible by a confidential VM.
In case 3, the guarantee that data retrieved from the cloud and decrypted, was originated in a confidential VM.
In case 4, the guarantee is that the data is only decryptable when the KEK is accessible.

Google Cloud EKM API Endpoints on CipherTrust Manager

CCKM provides APIs for users in the CCKM Admins Group to create and manage endpoints.

There are also APIs for Google tools to exercise cryptographic operations such as wrapping and unwrapping with the endpoints, and to establish a secure EKM UDE session between EKM UDE endpoints and Confidential VMs. Details about those operations are provided for information only and without sample curl commands, as properly configured Google tooling can construct these calls without user intervention.

Create an EKM or EKM UDE Endpoint

Use POST for /v1/cckm/ekm/endpoints to create a new EKM or EKM UDE endpoint.

Specify the following required details:

Unique name for the endpoint.
Base hostname for the Key URI
Policy attributes in rego or basic format, including allowed service accounts.

You can create a new KEK or specify an existing KEK for wrapping and unwrapping operations. Existing KEK is applicable for migrating EKM integration from another CM deployment.

The syntax varies based on whether EKM policy is specified in basic or rego format.

Syntax with policy in basic format

curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints' -H 'Authorization: Bearer AUTHTOKEN -H 'Content-Type: application/json' --data-binary $'{\n  "name": "<endpoint_name>",\n  "keyURIHostname": "<ciphertrust_fqdn>",\n  "meta": {\n    "<key>": "<value>" \n}, \n "cvm_required_for_decrypt": <boolean>\n "cvm_required_for_encrypt": <boolean>\n "endpoint_type": "<endpoint_type>",\n  "key_type": "<key-type>",\n  "algorithm": "<algorithm-type>",\n "existing_key_id": "<existing_key_id>",\n "<algorithm-type>",\n  "raw_policy_enabled": false,\n  "policy":  {\n "basic": {\n "clients": [<allowed-service-accounts>], \n  "attestation_instance_names": [<allowed-instance-names>],\n "attestation_project_ids": [<allowed-project-ids>],\n "attestation_zones": [<allowed-zones>],\n "justification_reason": [<allowed-key-access justification-reasons>],\n "justification_required": boolean \n}'}' --compressed

Syntax with policy in rego format

curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints' -H 'Authorization: Bearer AUTHTOKEN -H 'Content-Type: application/json' --data-binary $'{\n  "name": "<endpoint_name>",\n  "keyURIHostname": "<ciphertrust_fqdn>",\n  "meta": {\n    "<key>": "<value>" \n}, \n "cvm_required_for_decrypt": <boolean>\n "cvm_required_for_encrypt": <boolean>\n  "endpoint_type": "<endpoint-type>",\n  "key_type": "<key-type>",\n  "algorithm": "<algorithm-type>",\n  "existing_key_id": "<existing_key_id>",\n  "raw_policy_enabled": true,\n  "policy": {\n    "rego": <rego-policy-string> \n  }\n}' --compressed

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token
name	string	Unique name for EKM or EKM UDE Endpoint.
keyURIHostname	string	Base url hostname for KeyURI. If you changed the web interface port within CipherTrust Manager from the default port of 443 to another port, ensure to add that same port number when configuring url hostname for KeyURI by specifying the new port number along with the url hostname. For example, example.com:8443. For more information changing the web interface port, refer to Support for Changing the Default Port of Web Interface Setting.
meta	JSON	Optional. Additional information associated with this endpoint.
cvm_required_for_decrypt	boolean	Is a confidential VM (and valid attestation) required for decryption. Default is false. Applicable for UDE Endpoint only.
cvm_required_for_encrypt	boolean	Is a confidential VM (and valid attestation) required for encryption. Default is false. Applicable for UDE Endpoint only.
endpoint_type	string	EKM Endpoint type. Can be either "ekm" or "ekm-ude". Default is ekm.
key_type	string	EKM Key type. For existing keys, this must match the supplied key. Options are either symmetric or asymmetric. Default is symmetric.
algorithm	string	EKM Key Algorithm. For existing keys, this must match the supplied key. Default is AES256. Supported values are AES256, 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
existing_key_id	string	Identifier to be used to find the latest version of an existing CipherTrust Manager key. This identifier can be the ID of any version or the name of a CipherTrust Manager key. This key is either a symmetric or an asymmetric key type. The symmetric key must have Encrypt, Decrypt, Wrap, and Unwrap usage masks while the asymmetric key must have sign and verify usage masks. In addition, this key must not be exportable or deletable. An EKM endpoint will be created using the latest version of this key. If the identifier is not supplied, a new CipherTrust Manager key will be created. This identifier is applicable to migrating an EKM endpoint from one CipherTrust Manager deployment to another. When creating a new EKM endpoint using an existing CipherTrust Manager key in the new deployment, CCKM uses this identifier to associate all of the existing versions of a CipherTrust Manager key to the new endpoint.
raw_policy_enabled	boolean	Flag to denote if the sent policy is in raw format. Default is false. EKM Policy in basic format is required if raw_policy_enabled=false.
policy	JSON	EKM Policy Attributes

Policy Parameters

Policy Parameter	Type	Description
rego	string	EKM Policy in rego format. Required field if raw_policy_enabled=true.
basic	JSON	EKM Policy in basic format. Required field if raw_policy_enabled=false.

Basic Format Policy Parameters

Basic Format Policy Parameter	Type	Description
clients	array	Allowed Service Accounts. Required.
attestation_instance_names	array	Allowed Instance Names. Applicable for UDE Endpoint only.
attestation_project_ids	array	Allowed Project IDs. Applicable for UDE Endpoint only.
attestation_zones	array	Allowed zones. Applicable for UDE Endpoint only.
justification_reason	array	Justification reason can't be empty when justification_required is set to true. Allowed Key Access justification reasons. Options: • 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 • CUSTOMER_AUTHORIZED_WORKFLOW_SERVICING
justification_required	boolean	Flag to denote if key access justification should be enforced. Default is false.

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJlZDg5ZTFhNy1kOGUwLTRhMzAtOGQ3NC03YzBjZDA3ZjliODAiLCJzdWIiOiJsb2NhbHxhYzM2NGNkMi0xNGRkLTRiZWMtOGYzYy0yZDQzYWMwOGQzZTQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiN2Y4Y2E2MDktZTlkYy00ZTMwLThhNWMtNGJmYjQxZDM3MjMwIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjdkOTYzNzgxLTYwOTItNGQ5MS05YWNlLTg4Y2E2Mjk0YzRkYSIsImlhdCI6MTYzODQ5Mzg4MSwiZXhwIjoxNjM4NDk0MTgxfQ.vVJeW-faq9zInW81LyDB3Ffl29qiH6MiGlaLdVQMUzA' -H 'Content-Type: application/json' --data-binary $'{\n  "name": "ekmendpoint_1",\n  "keyURIHostname": "ekm.thales.com",\n  "meta": {\n    "color": "blue",\n    "size": "big"\n  },\n  "cvm_required_for_encrypt": true,\n  "cvm_required_for_decrypt": true,\n  "endpoint_type": "ekm-ude",\n  "key_type": "symmetric",\n  "algorithm": "AES256",\n  "raw_policy_enabled": true,\n  "policy": {\n    "rego": "package example\\r\\n\\r\\ndefault allow = false\\r\\n\\r\\nallowedClient {\\r\\n    input.client = {\\"abc@google.com\\"}[_]\\r\\n}\\r\\n\\r\\nallowedJustification {\\r\\n    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\\",\\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\\"}[_]\\r\\n}\\r\\n\\r\\ndefault allowAttestation = false\\r\\n\\r\\nallowAttestation {\\r\\n\\tinput.attestationRequired = false\\r\\n}\\r\\n\\r\\nallowAttestation {\\r\\n    input.attestationZones = {\\"us-east1a\\"}[_]\\r\\n    input.attestationProjectIDs = {\\"project1\\"}[_]\\r\\n    input.instanceNames = {\\"instance1\\"}[_]\\r\\n}\\r\\n\\r\\nallow {\\r\\n    allowedClient\\r\\n    allowedJustification\\r\\n    allowAttestation\\r\\n}"\n  }\n}' --compressed

Example Response

{
    "application/json": {
    "id": "04f63144-940c-4c4f-8426-1917b54e0c33",
    "uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
    "account": "kylo:kylo:admin:accounts:kylo",
    "application": "ncryptify:gemalto:admin:apps:kylo",
    "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
    "createdAt": "2021-02-10T00:19:40.321138Z",
    "name": "ekmendpoint_1",
    "updatedAt": "2021-02-10T00:20:25.036189Z",
    "keyURIHostname": "ciphertrust.mycompany.com",
    "keyURI": "https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
    "kekName": "ekmendpoint_1",
    "kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
    "meta": {
        "size": "big",
        "color": "blue"
    },
    "enabled": true,
    "kekVersion": "0",
    "cvm_required_for_encrypt": true,
    "cvm_required_for_decrypt": true,
    "endpoint_type": "ekm-ude",
    "key_type": "symmetric",
    "algorithm": "AES256",
    "raw_policy_enabled": false,
    "policy": {
        "basic": {},
        "rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n    input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n    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\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n    input.attestationZones = {\"us-east1a\"}[_]\r\n    input.attestationProjectIDs = {\"project1\"}[_]\r\n    input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n    allowedClient\r\n    allowedJustification\r\n    allowAttestation\r\n}"
        }
    }
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

List EKM or EKM UDE Endpoints

Use GET for /v1/cckm/ekm/endpoints to return a list of EKM Endpoints.

Syntax

curl -k 'https://<ciphertrust_fqdn>/api/v1/cckm/ekm/endpoints?<query_parameters>' -H 'AUTHTOKEN' --compressed

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Request Query Parameters

Parameter	Type	Description
id	string	Filter the result based on EKM Endpoint ID.
name	string	Filter the result based on EKM Endpoint name.
key_type	string	Filter the results based on EKM key type.
endpoint_type	string	Filter the results based on EKM endpoint type, ekm or ekm-ude.
algorithm	string	Filter the results based on EKM endpoint algorithm.
cryptospace_id	string	Filters the results based on cryptospace id.
cryptospace_name	string	Filter the results based on cryptospace name.
gcp_relative_resource_name	string	Filters the results based on the relative resource name of the GCP Cloud KMS Key.
relative_resource_name_without_version	string	Filters the results based on the relative resource name (without version) of the GCP Cloud KMS Key.
gcp_key_ring_name	string	Filter the results based on the GCP Cloud KMS Key ring name corresponding to an EKM endpoint.
gcp_key_name	string	Filter the results based on the GCP Cloud KMS Key name corresponding to an EKM endpoint.
gcp_project_id	string	Filter the results by Google project id.
state	string	Filter the results by state of the EKM key. Supported values are ACTIVE, DESTROYED, and empty (for both ACTIVE and DESTROYED).
skip	integer	The index of the first resource to return. Equivalent to 'offset' in SQL.
limit	integer	The max number of resources to return. Equivalent to 'limit' in SQL.

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints?skip=0&limit=10' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiYjQ5NDY5ZjgtMDJhNi00ZTgxLTliMDEtNGU1MTk2MjA0NzIwIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijc2ZTc1N2JiLWJiYTgtNDJiNy04OTI1LWMwYWFmZTQ0NzNiMSIsImlhdCI6MTYyNjExODk4OCwiZXhwIjoxNjI2MTE5Mjg4fQ.gwvR6t2-E5DFLatL6CdGdJnphDlkHp1Rog9xUlz_DWs' --compressed

Example Response

{
    "application/json": {
    "skip": "0,",
    "limit": "10,",
    "total": "2,",
    "resources": [
        {
            "id": "a1d22b5c-1734-40b8-8437-6a01987edef0",
            "uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
            "account": "kylo:kylo:admin:accounts:kylo",
            "application": "ncryptify:gemalto:admin:apps:kylo",
            "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
            "createdAt": "2021-02-10T00:19:40.321138Z",
            "name": "ekmendpoint_1",
            "updatedAt": "2021-02-10T00:20:25.036189Z",
            "keyURIHostname": "ekm.thales.com",
            "keyURI": "https://ekm.thales.com/api/v1/cckm/ekm/endpoints/a1d22b5c-1734-40b8-8437-6a01987edef0",
            "key_path": "api/v1/cckm/ekm/endpoints/a1d22b5c-1734-40b8-8437-6a01987edef0",
            "kekName": "ekmendpoint_1",
            "kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
            "meta": {
                "size": "big",
                "color": "blue"
            },
            "enabled": true,
            "kekVersion": "0",
            "cvm_required_for_encrypt": false,
            "cvm_required_for_decrypt": false,
            "endpoint_type": "ekm-ude",
            "key_type": "symmetric",
            "algorithm": "AES256",
            "cryptospace_id": "76e5b274-5cb8-4aa5-9645-164f375bbb35",
            "raw_policy_enabled": false,
            "policy": {
                "basic": {
                    "clients": [
                        "abc@google.com"
                    ],
                    "justification_required": true,
                    "justification_reason": [
                        "REASON_UNSPECIFIED",
                        "CUSTOMER_INITIATED_SUPPORT"
                    ],
                    "attestation_zones": [
                        "zone1",
                        "zone2"
                    ],
                    "attestation_project_ids": [
                        "project1",
                        "project2"
                    ],
                    "attestation_instance_names": [
                        "instance1",
                        "instance2"
                    ]
                },
                "rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n    input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n    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\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\",\"MODIFIED_GOOGLE_INITIATED_SYSTEM_OPERATION\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n    input.attestationZones = {\"us-east1a\"}[_]\r\n    input.attestationProjectIDs = {\"project1\"}[_]\r\n    input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n    allowedClient\r\n    allowedJustification\r\n    allowAttestation\r\n}"
            },
            "state": "ACTIVE"
        },
        {
            "account": "kylo:kylo:admin:accounts:kylo",
            "algorithm": "AES256",
            "application": "ncryptify:gemalto:admin:apps:kylo",
            "createdAt": "2022-11-23T01:47:40.727232Z",
            "cryptospace_id": "a5d55e6f-6145-40ca-86e3-d9b2ec77503f",
            "cryptospace_name": "cryptospace-1",
            "cvm_required_for_decrypt": false,
            "cvm_required_for_encrypt": false,
            "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
            "enabled": true,
            "endpoint_type": "ekm",
            "gcp_key_name": "key-test-1",
            "gcp_key_ring_name": "my-keyring",
            "id": "72ad421d-3cb0-4d2a-b8ba-3ae0c53f4de0",
            "kekID": "47425e5655c1449f8fce099e437ddf729e98fab6857d40038995101bd1934f96",
            "kekName": "ks-47425e5655c1449f8fce099e437ddf729e98fab6857d40038995101bd1934f96",
            "kekVersion": "0",
            "key_path": "api/v1/cckm/ekm/endpoints/72ad421d-3cb0-4d2a-b8ba-3ae0c53f4de0",
            "key_type": "symmetric",
            "keyURI": "https://ekm.thales.com/api/v1/cckm/ekm/endpoints/72ad421d-3cb0-4d2a-b8ba-3ae0c53f4de0",
            "keyURIHostname": "ekm.thales.com",
            "meta": null,
            "name": "cryptospace-1/my-proj/us-central1/my-keyring/key-test-1/0",
            "policy": {
                "basic": {
                    "clients": [
                        "richard-roe@google.com",
                        "john-doe@thales-test-proj.iam.gserviceaccount.com"
                    ],
                    "justification_reason": [
                        "CUSTOMER_INITIATED_SUPPORT"
                    ],
                    "justification_required": true
                },
                "rego": "\npackage example\ndefault allow = false\n\ndefault allowedClient = false\nallowedClient {\n\t\tinput.clients = {\"richard-roe@google.com\",\"john-doe@thales-test-proj.iam.gserviceaccount.com\",\"starjammers-ekm@gemalto-kyloeng.iam.gserviceaccount.com\"}[_]\n}\n\ndefault allowedJustification = false\nallowedJustification  {\n\t\tinput.justificationReason  = {\"CUSTOMER_INITIATED_SUPPORT\"}[_]\n}\n\nallow {\n    allowedClient\n    allowedJustification\n}\n"
            },
            "raw_policy_enabled": false,
            "relative_resource_name_without_version": "projects/my-proj/locations/us-central1/keyRings/my-keyring/cryptoKeys/key-test-1",
            "gcp_relative_resource_name": "projects/my-proj/locations/us-central1/keyRings/my-keyring/cryptoKeys/key-test-1/cryptoKeyVersions/0",
            "updatedAt": "2022-11-23T01:47:40.727232Z",
            "uri": "kylo:kylo:cckm:ekm-e2e-key:cryptospace-1-my-proj-us-central1-my-keyring-key-test-1-0",
            "gcp_project_id": "my-proj",
            "state": "DESTROYED"
        }
    ]
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Viewing Details for an EKM or EKM UDE Endpoint

Use GET for /v1/cckm/ekm/endpoints/{id} to return the details of the given EKM endpoint.

Syntax

curl -k 'https://<ciphertrust_hostname>/api/v1/cckm/ekm/endpoints/<ekm_endpoint_id>' -H 'AUTHTOKEN' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM Endpoint

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiYjQ5NDY5ZjgtMDJhNi00ZTgxLTliMDEtNGU1MTk2MjA0NzIwIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijc2ZTc1N2JiLWJiYTgtNDJiNy04OTI1LWMwYWFmZTQ0NzNiMSIsImlhdCI6MTYyNjExODk4OCwiZXhwIjoxNjI2MTE5Mjg4fQ.gwvR6t2-E5DFLatL6CdGdJnphDlkHp1Rog9xUlz_DWs' --compressed

Example Response

{
    "application/json": {
    "id": "a15d481e-9d30-4891-a55b-311a7f9d93c1",
    "uri": "kylo:kylo:cckm:ekm-e2e-key:ekmendpoint-1",
    "account": "kylo:kylo:admin:accounts:kylo",
    "application": "ncryptify:gemalto:admin:apps:kylo",
    "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
    "createdAt": "2021-11-17T22:48:10.81538Z",
    "name": "ekmendpoint_1",
    "updatedAt": "2021-11-17T22:48:10.81538Z",
    "keyURIHostname": "ekm.thales.com",
    "keyURI": "https://ekm.thales.com/api/v1/cckm/ekm/endpoints/a15d481e-9d30-4891-a55b-311a7f9d93c1",
    "kekName": "ks-4b9e5fe0d7934bf7a115db711a88b7073a933af817d04651a0323af811bcf95f",
    "kekID": "4b9e5fe0d7934bf7a115db711a88b7073a933af817d04651a0323af811bcf95f",
    "meta": {
        "size": "big",
        "color": "blue"
    },
    "enabled": true,
    "kekVersion": "0",
    "cvm_required_for_encrypt": true,
    "cvm_required_for_decrypt": true,
    "endpoint_type": "ekm-ude",
    "key_type": "symmetric",
    "raw_policy_enabled": true,
    "policy": {
        "basic": {},
        "rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n    input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n    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\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n    input.attestationZones = {\"us-east1a\"}[_]\r\n    input.attestationProjectIDs = {\"project1\"}[_]\r\n    input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n    allowedClient\r\n    allowedJustification\r\n    allowAttestation\r\n}"
        },
    "algorithm": "AES256"
    }
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Update An EKM or EKM UDE Endpoint

Use PATCH with /v1/cckm/ekm/endpoints/{id} to update the endpoint's base hostname, meta data, confidential VM requirements for operations, policy format, or policies. If you are changing policies, the syntax varies depending on whether the policy is provided in basic or rego format

Syntax with policy in basic format

curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>' -X PATCH -H 'Authorization: AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n  "keyURIHostname": "<new_URL"\n, "meta": {<key>:<value>}\n "cvm_required_for_encrypt": <boolean>,\n  "cvm_required_for_decrypt": <boolean>,\n  "raw_policy_enabled":false,\n "policy":  {\n "basic": {\n "clients": [<allowed-service-accounts>], \n  "attestation_instance_names": [<allowed-instance-names>],\n "attestation_project_ids": [<allowed-project-ids>],\n "attestation_zones": [<allowed-zones>],\n "justification_reason": [<allowed-key-access justification-reasons>],\n "justification_required": boolean \n}'}' --compressed

Syntax with policy in rego format

curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>' -X PATCH -H 'Authorization: AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n  "keyURIHostname": "<new_URL"\n, "meta": {<key>:<value>}\n "cvm_required_for_encrypt": <boolean>,\n  "cvm_required_for_decrypt": <boolean>,\n  "raw_policy_enabled": true,\n  "policy": {\n    "rego": <rego-policy-string> \n  }\n}'}' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM or EKM UDE Endpoint

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token
keyURIHostname	string	Base url hostname for KeyURI.
meta	JSON	Optional. Additional information associated with this endpoint.
cvm_required_for_encrypt	boolean	Is a confidential VM (and valid attestation) required for encryption. Default is false. Applicable for UDE Endpoint only.
cvm_required_for_decrypt	boolean	Is a confidential VM (and valid attestation) required for decryption. Default is false. Applicable for UDE Endpoint only.
raw_policy_enabled	boolean	Flag to denote if the sent policy is in raw format. Default is false.
policy	JSON	EKM Policy Attributes

Policy Parameters

Policy Parameter	Type	Description
rego	string	EKM Policy in rego format.
basic	JSON	EKM Policy in basic format.

Basic Format Policy Parameters

Basic Format Policy Parameter	Type	Description
clients	array	Allowed Service Accounts. Required.
attestation_instance_names	array	Allowed Instance Names. Applicable for UDE Endpoint only.
attestation_project_ids	array	Allowed Project IDs. Applicable for UDE Endpoint only.
attestation_zones	array	Allowed zones. Applicable for UDE Endpoint only.
justification_reason	array	Justification reason can't be empty when justification_required is set to true. Allowed Key Access justification reasons. Options: • 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 • CUSTOMER_AUTHORIZED_WORKFLOW_SERVICING
justification_required	boolean	Flag to denote if key access justification should be enforced. Default is false.

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test' -X PATCH -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhMWU0ODRhMi05MGQxLTQ3MmItYjk1ZC05MTJlOGRkMjQ3NGEiLCJzdWIiOiJsb2NhbHwyZGE3ZWI4Ny1iZGU0LTQ3ZDgtYmVlNC1mMDJiMzk0ODIxZWIiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiYTNiNmRjNWMtY2Y4YS00ZTVkLWEwYWUtN2UxZjQ0NjczNTI1Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6ImI4MWUxNzg5LWMwMTItNDFmZC1hZjJlLTJmNGQyM2ZlN2Q2MCIsImlhdCI6MTYzODU0NDAwMCwiZXhwIjoxNjM4NTQ0MzAwfQ.HOGqk0pOUDyJsVahADs5vJKuZanZW1dnfNC9G_-HmFs' -H 'Content-Type: application/json' --data-binary $'{\n  "keyURIHostname": "ciphertrust.newcompany.com",\n  "cvm_required_for_encrypt": false,\n  "cvm_required_for_decrypt": false,\n  "raw_policy_enabled": false,\n  "policy": {\n    "basic": {\n      "clients": [\n        "abc@google.com"\n      ],\n      "justification_required": true,\n      "justification_reason": [\n        "REASON_UNSPECIFIED",\n        "CUSTOMER_INITIATED_SUPPORT"\n      ],\n      "attestation_zones": [\n        "zone1",\n        "zone2"\n      ],\n      "attestation_project_ids": [\n        "project1",\n        "project2"\n      ],\n      "attestation_instance_names": [\n        "instance1",\n        "instance2"\n      ]\n    }\n  }\n}' --compressed

Example Response

{
    "application/json": {
        "id": "04f63144-940c-4c4f-8426-1917b54e0c33",
        "uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
        "account": "kylo:kylo:admin:accounts:kylo",
        "application": "ncryptify:gemalto:admin:apps:kylo",
        "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
        "createdAt": "2021-02-10T00:19:40.321138Z",
        "name": "ekmendpoint_1",
        "updatedAt": "2021-02-10T00:20:25.036189Z",
        "keyURIHostname": "ciphertrust.newcompany.com",
        "keyURI": "https://ciphertrust.newcompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "kekName": "ekmendpoint_1",
        "kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "meta": {
            "size": "big",
            "color": "yellow"
        },
        "enabled": true,
        "kekVersion": "0"
        "cvm_required_for_encrypt": false,
        "cvm_required_for_decrypt": false,
        "endpoint_type": "ekm",
        "key_type": "symmetric",
        "algorithm": "AES256",
        "raw_policy_enabled": false,
        "policy": {
            "basic": {
                "clients": [
                    "abc@google.com"
                ],
                "justification_required": true,
                "justification_reason": [
                    "REASON_UNSPECIFIED",
                    "CUSTOMER_INITIATED_SUPPORT"
                ],
                "attestation_zones": [
                    "zone1",
                    "zone2"
                ],
                "attestation_project_ids": [
                    "project1",
                    "project2"
                ],
                "attestation_instance_names": [
                    "instance1",
                    "instance2"
                ]
            },
            "rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n    input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n    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\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n    input.attestationZones = {\"us-east1a\"}[_]\r\n    input.attestationProjectIDs = {\"project1\"}[_]\r\n    input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n    allowedClient\r\n    allowedJustification\r\n    allowAttestation\r\n}"
        }
    }
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Delete An EKM or EKM UDE Endpoint

To permanantly delete an EKM or EKM UDE Endpoint, and therefore the Key Encryption Key (KEK) associated with it, send a DELETE request to /v1/cckm/ekm/endpoints/{id}

Syntax

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/<ekm_endpoint_id>' -X DELETE -H 'AUTHTOKEN' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM or EKM UDE Endpoint

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test' -X DELETE -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA5MjViMzktYzQ0OS00YWYzLWI0Y2UtOTJlYzkxODc1YTk2Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjhjYzAyNzhjLTIxODItNGRkZC1iNGZmLTYwYWMyNTgzYjVmZiIsImlhdCI6MTYyNjEyNDAzMiwiZXhwIjoxNjI2MTI0MzMyfQ.mPf1683qErNbtipKLPUKKShdmLwtx0XRD5rj2ft6UMI' --compressed

Example Response

{
    "status": 204
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

List EKM or EKM UDE Policies

Use GET with /v1/cckm/ekm/endpoints/{id}/policies to list the active policies for an endpoint. The policy language and model are derived from the Open Policy Agent (OPA) policy engine.

Syntax

curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>/policies' -H 'AUTHTOKEN' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM or EKM UDE Endpoint

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test/policies' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA5MjViMzktYzQ0OS00YWYzLWI0Y2UtOTJlYzkxODc1YTk2Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjIwNmVlMWVjLTY2MjMtNGZhNC05MjJiLWYwZGI3ZWFlMDRiOCIsImlhdCI6MTYyNjEyNTU1MywiZXhwIjoxNjI2MTI1ODUzfQ.bTQwMEQ3ivt20QluBKeA-KJBlEQ-n67kATeLMQbHlTs' --compressed

Example Response

{
    "text/plain": "package example default allow = false allowedClient {\n    input.client = {\"abc@google.com\"}[_]\n} allowedJustification {\n  input.justificationReason == {\"REASON_UNSPECIFIED\",\"CUSTOMER_INITIATED_SUPPORT\",\"GOOGLE_INITIATED_SERVICE\",\"THIRD_PARTY_DATA_REQUEST\",\n  \"GOOGLE_INITIATED_REVIEW\",\"CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_INITIATED_SYSTEM_OPERATION\",\"REASON_NOT_EXPECTED\",\n  \"MODIFIED_CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\n} default allowAttestation = false allowAttestation {\n\tinput.attestationRequired = false\n} allowAttestation {\n    input.attestationZones = {\"us-east1a\"}[_]\n    input.attestationProjectIDs = {\"project1\"}[_]\n    input.instanceNames = {\"instance1\"}[_]\n} allow {\n    allowedClient\n    allowedJustification\n    allowAttestation\n}\n"
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Update EKM or EKM UDE Policies

Use PATCH with /v1/cckm/ekm/endpoints/{id}/policies to edit the active policies for an endpoint. The policy language and model are derived from the Open Policy Agent (OPA) policy engine. You can also edit policies with the endpoint to update the endpoint generally. ).

Syntax

curl -k 'https://<ciphertrust_fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>/policies' -X PATCH -H 'AUTHTOKEN' -H 'Content-Type: text/plain' --data-binary '{ "clients" : <allowed_clients>", "justificationReason" : "<allowed_justification_reasons>", "attestationZones":<allowed-attestation-zones>, "attestationProjectIDs":<allowed-project-ids>, "instanceNames":<allowed-instance-names> }' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM or EKM UDE Endpoint

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token
clients	string	Clients permitted to access the endpoint.
justificationReason	string	Justification reasons required in the request to wrap or unwrap with the endpoint.
attestationZones	string	Set param with Zones that should be allowed during UDE Attestation. Applicable only for UDE Endpoints.
attestationProjectIDs	string	Set param with Project IDs that should be allowed during UDE Attestation. Applicable only for UDE Endpoints.
instanceNames	string	Set param with Instance Names that should be allowed during UDE Attestation. Applicable only for UDE Endpoints.

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test/policies' -X PATCH -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA1NzZkODgtMjFhNy00ZmY4LThmZWYtN2IyY2JlZWRkYjE4Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijg0M2I0Njc0LWJlZWQtNDFjNS04YjgxLWUyNzBhYzI1ZTU3ZiIsImlhdCI6MTYyNjE4MTEwNywiZXhwIjoxNjI2MTgxNDA3fQ.3nG8PoPEWOagovTpM8LVk90BxU-jgiVqaqMo0d1OcXA' -H 'Content-Type: text/plain' --data-binary '{ "clients" : "abc@yahoo.com", "justificationReason" : "REASON_UNSPECIFIED" }' --compressed

Example Response

{
    "text/plain": "package example default allow = false allow {\n  input.clients == {\"abc@yahoo.com\", \"abc@google.com\", \"abc@msn.com\"}[_]\n  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\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\n}\n"
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Rotate An EKM or EKM UDE Endpoint

Use POST with /v1/cckm/ekm/endpoints/{id}/rotate to add a new key version with new key material to the endpoint's KEK. The Key URI remains the same.

Syntax

curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>/rotate' -X POST -H 'AUTHTOKEN' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM or EKM UDE Endpoint

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test/rotate' -X POST -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA1NzZkODgtMjFhNy00ZmY4LThmZWYtN2IyY2JlZWRkYjE4Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijg0M2I0Njc0LWJlZWQtNDFjNS04YjgxLWUyNzBhYzI1ZTU3ZiIsImlhdCI6MTYyNjE4MTEwNywiZXhwIjoxNjI2MTgxNDA3fQ.3nG8PoPEWOagovTpM8LVk90BxU-jgiVqaqMo0d1OcXA' --compressed

Example Response

{
    "application/json": {
        "id": "04f63144-940c-4c4f-8426-1917b54e0c33",
        "uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
        "account": "kylo:kylo:admin:accounts:kylo",
        "application": "ncryptify:gemalto:admin:apps:kylo",
        "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
        "createdAt": "2021-02-10T00:19:40.321138Z",
        "name": "ekmendpoint_1",
        "updatedAt": "2021-02-10T00:20:25.036189Z",
        "keyURIHostname": "ciphertrust.mycompany.com",
        "keyURI": "https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "kekName": "ekmendpoint_1",
        "kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "meta": {
            "size": "big",
            "color": "blue"
        },
        "enabled": true,
        "kekVersion": "1"
        "cvm_required_for_encrypt": false,
        "cvm_required_for_decrypt": false,
        "endpoint_type": "ekm",
        "key_type": "symmetric",
        "algorithm": "AES256",
        "raw_policy_enabled": false,
        "policy": {
            "basic": {
                "clients": [
                    "abc@google.com"
                ],
                "justification_required": true,
                "justification_reason": [
                    "REASON_UNSPECIFIED",
                    "CUSTOMER_INITIATED_SUPPORT"
                ],
                "attestation_zones": [
                    "zone1",
                    "zone2"
                ],
                "attestation_project_ids": [
                    "project1",
                    "project2"
                ],
                "attestation_instance_names": [
                    "instance1",
                    "instance2"
                ]
            },
            "rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n    input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n    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\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n    input.attestationZones = {\"us-east1a\"}[_]\r\n    input.attestationProjectIDs = {\"project1\"}[_]\r\n    input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n    allowedClient\r\n    allowedJustification\r\n    allowAttestation\r\n}"
        }
    }
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Enable an EKM or EKM UDE Endpoint

Use POST with /v1/cckm/ekm/endpoints/{id}/enable to allow wrap or unwrap operation using the EKM or EKM UDE endpoint.

Syntax

curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>/enable' -X POST -H 'AUTHTOKEN' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM or EKM UDE Endpoint

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test/enable' -X POST -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA1NzZkODgtMjFhNy00ZmY4LThmZWYtN2IyY2JlZWRkYjE4Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijg0M2I0Njc0LWJlZWQtNDFjNS04YjgxLWUyNzBhYzI1ZTU3ZiIsImlhdCI6MTYyNjE4MTEwNywiZXhwIjoxNjI2MTgxNDA3fQ.3nG8PoPEWOagovTpM8LVk90BxU-jgiVqaqMo0d1OcXA' --compressed

Example Response

{
    "application/json": {
        "id": "04f63144-940c-4c4f-8426-1917b54e0c33",
        "uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
        "account": "kylo:kylo:admin:accounts:kylo",
        "application": "ncryptify:gemalto:admin:apps:kylo",
        "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
        "createdAt": "2021-02-10T00:19:40.321138Z",
        "name": "ekmendpoint_1",
        "updatedAt": "2021-02-10T00:20:25.036189Z",
        "keyURIHostname": "ciphertrust.mycompany.com",
        "keyURI": "https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "kekName": "ekmendpoint_1",
        "kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "meta": {
            "size": "big",
            "color": "blue"
        },
        "enabled": true,
        "kekVersion": "1"
        "cvm_required_for_encrypt": false,
        "cvm_required_for_decrypt": false,
        "endpoint_type": "ekm",
        "key_type": "symmetric",
        "algorithm": "AES256",
        "raw_policy_enabled": false,
        "policy": {
            "basic": {
                "clients": [
                    "abc@google.com"
                ],
                "justification_required": true,
                "justification_reason": [
                    "REASON_UNSPECIFIED",
                    "CUSTOMER_INITIATED_SUPPORT"
                ],
                "attestation_zones": [
                    "zone1",
                    "zone2"
                ],
                "attestation_project_ids": [
                    "project1",
                    "project2"
                ],
                "attestation_instance_names": [
                    "instance1",
                    "instance2"
                ]
            },
            "rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n    input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n    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\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n    input.attestationZones = {\"us-east1a\"}[_]\r\n    input.attestationProjectIDs = {\"project1\"}[_]\r\n    input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n    allowedClient\r\n    allowedJustification\r\n    allowAttestation\r\n}"
        }
    }
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Disable an EKM or EKM UDE Endpoint

Use POST with /v1/cckm/ekm/endpoints/{id}/disable to disallow wrap or unwrap operation using the EKM or EKM UDE endpoint. This is a way to temporarily suspend client operations with an endpoint without deleting it and its associated KEK.

Syntax

curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>/disable' -X POST -H 'AUTHTOKEN' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM or EKM UDE Endpoint

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test/disable' -X POST -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA1NzZkODgtMjFhNy00ZmY4LThmZWYtN2IyY2JlZWRkYjE4Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijg0M2I0Njc0LWJlZWQtNDFjNS04YjgxLWUyNzBhYzI1ZTU3ZiIsImlhdCI6MTYyNjE4MTEwNywiZXhwIjoxNjI2MTgxNDA3fQ.3nG8PoPEWOagovTpM8LVk90BxU-jgiVqaqMo0d1OcXA' --compressed

Example Response

{
    "application/json": {
        "id": "04f63144-940c-4c4f-8426-1917b54e0c33",
        "uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
        "account": "kylo:kylo:admin:accounts:kylo",
        "application": "ncryptify:gemalto:admin:apps:kylo",
        "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
        "createdAt": "2021-02-10T00:19:40.321138Z",
        "name": "ekmendpoint_1",
        "updatedAt": "2021-02-10T00:20:25.036189Z",
        "keyURIHostname": "ciphertrust.mycompany.com",
        "keyURI": "https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "kekName": "ekmendpoint_1",
        "kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "meta": {
            "size": "big",
            "color": "blue"
        },
        "enabled": true,
        "kekVersion": "1"
        "cvm_required_for_encrypt": false,
        "cvm_required_for_decrypt": false,
        "endpoint_type": "ekm",
        "key_type": "symmetric",
        "algorithm": "AES256",
        "raw_policy_enabled": false,
        "policy": {
            "basic": {
                "clients": [
                    "abc@google.com"
                ],
                "justification_required": true,
                "justification_reason": [
                    "REASON_UNSPECIFIED",
                    "CUSTOMER_INITIATED_SUPPORT"
                ],
                "attestation_zones": [
                    "zone1",
                    "zone2"
                ],
                "attestation_project_ids": [
                    "project1",
                    "project2"
                ],
                "attestation_instance_names": [
                    "instance1",
                    "instance2"
                ]
            },
            "rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n    input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n    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\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n    input.attestationZones = {\"us-east1a\"}[_]\r\n    input.attestationProjectIDs = {\"project1\"}[_]\r\n    input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n    allowedClient\r\n    allowedJustification\r\n    allowAttestation\r\n}"
        }
    }
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Get Information about EKM Software

Use GET for /.well-known/external-key-manager/info to obtain information about the EKM software as well as to test the connectivity to the EKM. This operation is available for testing purposes only.

The request contains a JWT asserting that the getInfo operation is done by a legitimate User.

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization token

Example Response

{
    "application/json": {
        "ekm_software_id" :
            'CipherTrust Manager k170v 1.0.0'
    }
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

EKM UDE Session

The EKM API contains a set of Session endpoints for an EKM UDE Session, which allow the establishment of a secure TLS 1.3 session between the Google-provided integration component and CipherTrust Manager, with Google acting as client and CipherTrust Manager acting as server.

Note

As this sequence is a TLS exchange most appropriate for TLS clients, we do not provide curl example requests and responses.

The sequence for the session endpoints is: session/begin session; session/handshake; session/negotiate attestation; session/finalize and session/end session.

Begin an EKM UDE Session

Use POST with /v1/cckm/ekm/session/beginsession to initiate an encapsulated TLS (1.3) session. A server session is created in CipherTrust Manager and the encapsulated first TLS message is handled from the client. A unique session ID is created and returned - this accompanies all further uses of this session.

Request Parameters

Parameter	Type	Description
tlsRecords	string	Serialized message to begin a TLS handshake.

Response Elements

Element	Type	Description
sessionContext	string	Information associated with the session including session ID.
tlsRecords	string	Serialized response.

Complete the EKM UDE Session Handshake

Use POST with /v1/cckm/ekm/session/handshake to complete the encapsulated TLS handshake. All subsequent messages using the established session are encrypted.

Request Parameters

Parameter	Type	Description
tlsRecords	string	Result from `/v1/cckm/ekm/session/beginsession`
sessionContext	string	Result from `/v1/cckm/ekm/session/beginsession`

Response Elements

Empty JSON object.

Negotiate Attestation for an EKM UDE Session

Use POST with /v1/cckm/ekm/session/negotiateattestation to perform EKM UDE attestation negotiation. The client presents the set of attestation options it is willing or capable of providing (NONE, TPM, TCG_LOG) and the server determines acceptability. The server responds with the subset of attestation options which must be provided for this session, or an error if no acceptable combination is possible.

Request Parameters

Parameter	Type	Description
sessionContext	string	Result from `/v1/cckm/ekm/session/beginsession`
offeredEvidenceTypeRecords	string	Set of attestation options the client can provide.

Response Elements

Element	Type	Description
requiredEvidenceTypeRecords	string	Set of attestation options the server requires.

Finalize an EKM UDE Session

Use POST with /v1/cckm/ekm/session/finalize to finalize an EKM UDE session. Attestation evidence (if any) is presented for this session. This is evaluated and also compared with the attestation(s) required in /negotiateattestation. If acceptable, the session is associated with the attributes conveyed by these attestations.

Request Parameters

Parameter	Type	Description
sessionContext	string	Information associated with the session including session ID.
attestationEvidenceRecords	string	Attestion evidence if present.

Response Elements

Empty JSON object.

End an EKM UDE Session

Use POST with /v1/cckm/ekm/session/endsession to destroy an EKM UDE session.

Request Parameters

Parameter	Type	Description
sessionContext	string	Information associated with the session including session ID.

Response Elements

Empty JSON object.

Perform a Confidential Wrap with an EKM UDE endpoint

Use POST with /v1/cckm/ekm/endpoints/{id}:confidentialwrap to perform a confidential wrap. A confidential wrap is an EKM wrap requiring the use of a secure EKM UDE session and involving a policy enforcement check against the requirements for the endpoint (i.e. the level of attestation required).

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM UDE Endpoint

Request Parameters

Parameter	Type	Description
sessionContext	string	Session context identifier.
tlsRecords	string	TLS records, base64 encoded.

Example Response

{
"status": 204
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Perform a Confidential Unwrap with an EKM UDE Endpoint

Use POST with /v1/cckm/ekm/endpoints/{id}:confidentialunwrap to perform a confidential wrap. A confidential wrap is an EKM unwrap requiring the use of a secure session and involving a policy enforcement check against the requirements for the endpoint (i.e. the level of attestation required).

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM UDE Endpoint

Request Parameters

Parameter	Type	Description
sessionContext	string	Session context identifier.
tlsRecords	string	TLS records, base64 encoded.

Example Response

{
"status": 204
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Perform an Asymmetric Signature Verification Operation

Use POST with /v1/cckm/ekm/endpoints/{id}:asymmetricVerify to perform an asymmetric signature verification. This operation is available for testing purposes only.

The request contains:

A JWT asserting that asymmetricsign operation is done by a legitimate User.
The base64 signature that needs to be verified.
Additional Context containing Key Access Justification details.

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM Endpoint

Request Parameters

Parameter	Type	Description
data	string	Required. The signed data to be verified (base64 encoded). Must be no larger than 64KiB.
key_path	string	Required. A unique, External-KMS-defined resource identifier for the key.
signature	string	Required. The data signature (base64 encoded).
key_uri_prefix	string	Optional data that, if specified, defines the full key URI.
additionalContext	JSON	More context provided during Verify operation. Required if Key Access Justification is enabled for GCP project. See Verify additionalContext Parameters for allowed values.

Verify additionalContext parameters

Parameter	Type	Description
accessReasonContext	JSON	Optional. Request that has an empty AccessReasonContext is a valid request.
reason	string	Key Access Justification reason. Required if Key Access Justification is enabled for GCP project.
fullResourceName	string	The full resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See For a Cloud KMS CryptoKey resource, this includes the Cloud KMS Location associated with the resource.
isKeyHealthCheck	boolean	Optional. Whether the request is a key health check that contains a canonical plaintext or its encryption instead of customer data.
relativeResourceName	string	Optional. The relative resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See This is a substring of the RequestContext's full_resource_name.

Example Response

{
    "application/json": {
        "status": true
    }
}

Perform an Asymmetric Sign Operation

Use POST with /v1/cckm/ekm/endpoints/{id}:asymmetricSign to perform an asymmetric sign. The request contains:

A JWT asserting that asymmetricsign operation is done by a legitimate User.
The base64 signature that needs to be signed.
Additional Context containing Key Access Justification details.

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM Endpoint

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization token
data	string	Required. The data to be signed (base64 encoded). Must be no larger than 64KiB.
key_path	string	Required. A unique, External-KMS-defined resource identifier for the key.
key_uri_prefix	string	Optional data that, if specified, defines the full key URI.
additionalContext	JSON	More context provided during Sign operation. Required if Key Access Justification is enabled for GCP project. See Sign additionalContext Parameters for allowed values.

Sign additionalContext parameters

Parameter	Type	Description
accessReasonContext	JSON	Optional. Request that has an empty AccessReasonContext is a valid request.
reason	string	Key Access Justification reason. Required if Key Access Justification is enabled for GCP project.
fullResourceName	string	The full resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See For a Cloud KMS CryptoKey resource, this includes the Cloud KMS Location associated with the resource.
isKeyHealthCheck	boolean	Optional. Whether the request is a key health check that contains a canonical plaintext or its encryption instead of customer data.
relativeResourceName	string	Optional. The relative resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See This is a substring of the RequestContext's full_resource_name.

Example Response

{
    "application/json": {
        "signature": "ZXlKM2NtRndjR1ZrWDJKc2IySWlPaUpCZW5Cc1RIQXlPRTh2WkdWd1QzZE1ZVk5zY1hwS1pWWlFTR3R4YVcxMlJXYzVTWFFyY0ZOTlMzWjROaUlzSW10bGExOXBaQ0k2SWpNNVkyWmhaR1EyTnpWa05EUmhPV1k0T0Raa09XSTBNalV3TjJSaU1UUXlZekZrWmpjeU5tTmhPR0ZrTkRGaVltSXhPRGs0T1RJek1UY3pNMlZsTmpnaWZRPT0="
    }
}

Get the Public Key from an EKM endpoint

Use POST with /v1/cckm/ekm/endpoints/{id}:getPublicKey to retrieve the public key and its algorithm from the Google Cloud EKM endpoint.

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM Endpoint

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization token
key_path	string	Required. A unique, External-KMS-defined resource identifier for the key.
key_uri_prefix	string	Optional data that, if specified, defines the full key URI.
additionalContext	JSON	More context provided during GetPublicKey operation. Required if Key Access Justification is enabled for GCP project. See GetPublicKey additionalContext Parameters for allowed values.

GetPublicKey additionalContext parameters

Parameter	Type	Description
accessReasonContext	JSON	Optional. Request that has an empty AccessReasonContext is a valid request.
reason	string	Key Access Justification reason. Required if Key Access Justification is enabled for GCP project.
fullResourceName	string	The full resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See For a Cloud KMS CryptoKey resource, this includes the Cloud KMS Location associated with the resource.
isKeyHealthCheck	boolean	Optional. Whether the request is a key health check that contains a canonical plaintext or its encryption instead of customer data.
relativeResourceName	string	Optional. The relative resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See This is a substring of the RequestContext's full_resource_name.

Example Response

{
    "pem": "-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy/fapXb3aFvU8DljEi0t EYsi34aEKPStH9G2GbG2/yirRpjkgET9LlggFxXqLsVtOMRYL68L5Lx5KH1GOXaI H4nuHuMsOeXL/pzjqw6DwLIFmPxO8WIOY7/zNJt5pIXRLtbI08+7dujQM/CP7s6b G6+CG6kUpYhroapqlSvwBalcVh7Ne574r38VCG0ISPdgkDzHX5gizRu0qQLWI6yw Yfon5CZE3k1lz9MvfLIujbcPTH8ss/05ujOCZl8rkt+dq6pH5QOufF9vDSAhQlbf qdkf3UQlFX34IgPCU12xo0lDYamofZLkcEL/0EWUfBVtlLfADT4h4iFJweppQe9y CQIDAQAB -----END PUBLIC KEY-----",
    "key_algorithm": "RSA_SIGN_PSS_2048_SHA256"
}

Wrap with an EKM or EKM UDE Endpoint

Use POST with /v1/cckm/ekm/endpoints/{id}:wrap to perform a wrap operation with the EKM or EKM UDE endpoint, used only for health check. Google Cloud KMS can find and make calls to this endpoint 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.

Specify the following details:

A JWT asserting that unwrap operation is done by legitimate User.
The base64 blob that needs to be wrapped.
Additional Context containing Key Access Justification details.

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM or EKM UDE Endpoint

Request Parameters

Parameter	Type	Description
GOOGLE_TOKEN	string	Authorization Token
plaintext	string	Required. The data to be wrapped (base64 encoded). Must be no larger than 64KiB.
additionalAuthenticatedData	string	Optional data that, if specified, must also be provided during unwrap. The AAD must be no larger than 64KiB.
additionalContext	JSON	More context provided during Wrap operation. Required if Key Access Justification is enabled for GCP project. See Wrap additionalContext Parameters for allowed values.

Wrap additionalContext parameters

Parameter	Type	Description
accessReasonContext	JSON	Optional. Request that has an empty AccessReasonContext is a valid request.
reason	string	Key Access Justification reason. Required if Key Access Justification is enabled for GCP project.
fullResourceName	string	The full resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See For a Cloud KMS CryptoKey resource, this includes the Cloud KMS Location associated with the resource.
isKeyHealthCheck	boolean	Optional. Whether the request is a key health check that contains a canonical plaintext or its encryption instead of customer data.
relativeResourceName	string	Optional. The relative resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See This is a substring of the RequestContext's full_resource_name.

Example Response

{
    "application/json": {
        "wrappedBlob": "ZXlKM2NtRndjR1ZrWDJKc2IySWlPaUpCZW5Cc1RIQXlPRTh2WkdWd1QzZE1ZVk5zY1hwS1pWWlFTR3R4YVcxMlJXYzVTWFFyY0ZOTlMzWjROaUlzSW10bGExOXBaQ0k2SWpNNVkyWmhaR1EyTnpWa05EUmhPV1k0T0Raa09XSTBNalV3TjJSaU1UUXlZekZrWmpjeU5tTmhPR0ZrTkRGaVltSXhPRGs0T1RJek1UY3pNMlZsTmpnaWZRPT0="
    }
}

Unwrap with an EKM or EKM UDE Endpoint

Use POST with /v1/cckm/ekm/endpoints/{id}:unwrap to perform an unwrap operation with the EKM or EKM UDE endpoint, used only for health checks. Google Cloud KMS can find and make calls to this endpoint without user intervention, if Google Cloud KMS has correctly configured the Cloud EKM or EKM UDE key, and the CMEK service is correctly configured to access the key on Google Cloud KMS.

Specify the following details:

A JWT asserting that unwrap operation is done by legitimate User.
The base64 blob that needs to be wrapped.
Additional Context containing Key Access Justification details.

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM or EKM UDE Endpoint

Request Parameters

Parameter	Type	Description
GOOGLE_TOKEN	string	Authorization Token
additionalAuthenticatedData	string	Must match the data originally supplied in the wrap request.
additionalContext	JSON	More context provided during the unwrap operation. Required if Key Access Justification is enabled for GCP project. See Unwrap additionalContext Parameters for allowed values.
wrappedBlob	string	Required. The wrapped data to be unwrapped, originally returned in the wrap request.

Unwrap additionalContext Parameters

Parameter	Type	Description
accessReasonContext	JSON	Optional. Request that has an empty AccessReasonContext is a valid request.
reason	string	Key Access Justification reason. Required if Key Access Justification is enabled for GCP project.
fullResourceName	string	Optional. The full resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See For a Cloud KMS CryptoKey resource, this includes the Cloud KMS Location associated with the resource.
isKeyHealthCheck	boolean	Optional. Whether the request is a key health check that contains a canonical plaintext or its encryption instead of customer data.
relativeResourceName	string	Optional. The relative resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See This is a substring of the RequestContext's full_resource_name.

Example Response

{
    "application/json": {
        "plaintext": "dG9tbXk="
    }
}

Google Cloud EKM Cryptospace APIs

Caution

This feature is a technical preview for evaluation in non-production environments. A technical preview introduces new, limited functionality for customer feedback as we work on the feature. Details and functionality are subject to change. This includes API endpoints, UI elements, and CLI commands. We cannot guarantee that data created as part of a technical preview will be retained after the feature is finalized.

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 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, you define a default Key Access Justification (KAJ) policy to apply to it in addition to other required parameters. Keys created in a given cryptospace inherit the cryptospace’s default policy. For more information about the required parameters, see Create an EKM Cryptospace.

Note

In release 2.11.0, only CCKM EKM cryptospace APIs are available in the technical preview for evaluation in non-production environments. The CCKM UI does not include the EKM cryptospace feature.

To employ an EKM through VPC connections using Cloud KMS EKM management mode for external keys, perform the following general steps:

Add the GCP project to be associated with a cryptospace in CCKM.
Create a cryptospace in CCKM (specifying a default policy for it). Note the cryptospace URL.
Create an EKM through VPC connection on the Google console. Select Cloud KMS as the EKM management mode and provide the cryptospace URL.
From the Google console, select the VPC connection you created in Step 2 to create, rotate, and destroy your EKM keys.

For more information about a VPC connection of type Cloud KMS EKM management mode for EKMs as well as the prerequisite steps to use this feature in Google, refer to Google documentation.

Create an EKM Cryptospace

Use POST for /v1/cckm/ekm/cryptospaces to create a new EKM cryptospace.

Note

This API is idempotent. It gives the same results no matter how many times it is called.

Specify the following required details for the cryptospace:

Cryptospace name
Hostname
Cryptospace type
GCP Project ID
Indicate whether the policy is in a raw format
Indicate whether cryptospace is blocked
Policy attributes in rego or basic format including the allowed service accounts
Attestation parameter for encrypt (applicable only if type is ekm-ude)
Attestation parameter for decrypt (applicable only if type is ekm-ude)
List of service accounts and permissions for these service accounts
Location of the cryptospace

The syntax varies based on whether EKM policy is specified in basic or rego format

Syntax with policy in basic format

curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/cryptospaces' -H 'Authorization: Bearer AUTHTOKEN -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary $'{\n  "name": "<cryptospace_name>",\n  "hostname": "<ciphertrust_fqdn>",\n  "type": "<cryptospace_type>",\n  "project_id": "<project_id>",\n  "meta": {\n    "<key>": "<value>",\n    "<key>": "<value>"\n  },\n  "blocked": false,\n  "raw_policy_enabled": false,\n  "policy": {\n    "basic": {\n      "justification_required": true,\n      "clients": [\n  [<allowed-service-accounts>],\n      "justification_reason": [<allowed-key-access justification-reasons>]\n    }\n  },\n  "location": "<cryptospace_location>",\n  "description": "<cryptospace_description>",\n  "permissions": [\n    {\n      "service_account": "<allowed_service_account>",\n      "permissions": ["<list_allowed_permissions>"]\n    },\n    {\n      "service_account": "<allowed_service_account>",\n      "permissions": [\n        "<list_allowed_permissions>"]\n    }\n  ]\n}' --compressed

Syntax with policy in rego format

curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/cryptospaces' -H 'Authorization: Bearer AUTHTOKEN -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary $'{\n    "name": "<cryptospace_name>",\n    "hostname": "https://<ciphertrust-fqdn>",\n    "type": "<cryptospace_type>",\n    "location": "<cryptospace_location>",\n    "project_id": "<project_id>",\n    "meta": {\n        "<key>": "<value>",\n        "<key>": "<value>"\n    },\n    "blocked": false,\n    "raw_policy_enabled": true,\n    "policy": {\n        "rego":  <rego-policy-string>"]\n        }\n    ]\n}' --compressed

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token
name	string	Name of a cryptospace. The name must be unique in a domain.
hostname	string	Base url hostname for Ciphertrust Manager. You can change the default port of 443 for the CipherTrust Manager web interface. One would have to ensure to change it BEFORE configuring the given cloud service on CCKM. However, in the case of Google Cryptospace, Google only accepts and sends requests on the default port of 443. If you wish to use a different port for the web interface other than the default, add a network component, such as a load balancer or a firewall, in front of CipherTrust Manager. Then configure port mapping on this component by mapping port 443 to the non-default port on the CipherTrust Manager you plan to use. For more information, refer to Support for Changing the Default Port of Web Interface Setting.
type	string	There are two types of cryptospaces. One for EKM endpoints (ekm) and another for EKM UDE endpoints (ekm-ude). The default is ekm.
project_id	string	The project ID of the Google Cloud project to be associated with the given cryptospace.
meta	object	Additional information associated with the given cryptospace.
blocked	boolean	This field indicates whether the cryptospace is blocked. The default is false.
raw_policy_enabled	boolean	Flag to denote whether the sent policy is in raw format. The default is false. Cryptospace Policy in a basic format is required if raw_policy_enabled=false.
policy	object	Cryptospace Key Access Justification (KAJ) Policy attributes. Endpoints in a cryptospace are to inherit the cryptospace's policy. EKM endpoint in a cryptospace can have its own policy as well.
location	string	Location of a cryptospace.
description	string	Description of a cryptospace.
permissions	object	List of service accounts and permissions. Service account used to call EKM cryptospace APIs. Service account is a string. List of permissions assigned to a service account. This list is an array. Options: • CREATE_KEY • DESTROY_KEY • WRAP • UNWRAP • GET_PUBLIC_KEY • ASYMMETRIC_SIGN • GET_INFO

Policy Parameters

Policy Parameter	Type	Description
rego	string	EKM Policy in rego format. Required field if raw_policy_enabled=true.
basic	JSON	EKM Policy in basic format. Required field if raw_policy_enabled=false.

Basic Format Policy Parameters

Basic Format Policy Parameter	Type	Description
clients	array	Allowed Service Accounts. Required.
attestation_instance_names	array	Allowed Instance Names. Applicable for UDE Endpoint only.
attestation_project_ids	array	Allowed Project IDs. Applicable for UDE Endpoint only.
attestation_zones	array	Allowed zones. Applicable for UDE Endpoint only.

|justification_reason|array|Justification reason cannot be empty when justification_required is set to true. Allowed Key Access justification reasons. Options:
• 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
• CUSTOMER_AUTHORIZED_WORKFLOW_SERVICING| |justification_required|boolean|Flag to denote if key access justification should be enforced. The default is false.|

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/cryptospaces' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiIxZTgwZjk3Yi1iN2JhLTQ1NTgtYTIzMC1hMmQ2ZWY0MGRhYTEiLCJzdWIiOiJsb2NhbHwyNGVhNzlmYy00YzAxLTRmODctYTIyYy02OGUzZjJhZmE4ZmMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfdHlwZSI6InVucmVnaXN0ZXJlZCIsImRvbWFpbl9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImdyb3VwcyI6WyJhZG1pbiJdLCJzaWQiOiIwYjRjZTQzNS0yNTlkLTQxZWUtYTc4ZC01ODNmZGJkYjUzNTIiLCJ6b25lX2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIn0sImp3dGlkIjoiNzhlMWU1NjYtM2FjNC00YzFjLTkyZWQtYjNkZDliYjcxMDkzIiwiaWF0IjoxNjc0NTA5MTA0LCJleHAiOjE2NzQ1MDk0MDR9.pzBBG4QTHNxZ762AfJLsl54Zrt4jMMEGhUI7dAk6GWs' -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary $'{\n  "name": "cryptospace_1",\n  "hostname": "ciphertrust.mycompany.com",\n  "type": "ekm",\n  "project_id": "thales-test-proj",\n  "meta": {\n    "color": "blue",\n    "size": "big"\n  },\n  "blocked": false,\n  "raw_policy_enabled": false,\n  "policy": {\n    "basic": {\n      "justification_required": true,\n      "clients": [\n        "richard-roe@google.com",\n        "john-doe@thales-test-proj.iam.gserviceaccount.com"\n      ],\n      "justification_reason": [\n        "CUSTOMER_INITIATED_SUPPORT"\n      ]\n    }\n  },\n  "location": "us-east1",\n  "description": "cryptospace for testing control plane",\n  "permissions": [\n    {\n      "service_account": "test-ekm@testgcp-prj.iam.gserviceaccount.com",\n      "permissions": [\n        "CREATE_KEY",\n        "DESTROY_KEY",\n        "WRAP",\n        "UNWRAP",\n        "GET_PUBLIC_KEY",\n        "ASYMMETRIC_SIGN",\n        "GET_INFO"\n      ]\n    },\n    {\n      "service_account": "test2-ekm@testgcp-prj.iam.gserviceaccount.com",\n      "permissions": [\n        "WRAP",\n        "UNWRAP"\n      ]\n    }\n  ]\n}' --compressed

Example Response

{
"application/json": {
    "id": "e94093c5-f9a0-4bd6-84ea-c44ff8cb1c88",
    "uri": "kylo:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963:cckm:ekm-cryptospace:e94093c5-f9a0-4bd6-84ea-c44ff8cb1c88",
    "account": "kylo:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963:admin:accounts:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963",
    "createdAt": "2022-09-26T05:52:31.721974Z",
    "updatedAt": "2022-09-26T05:52:31.721974Z",
    "type": "ekm",
    "project_id": "thales-test-proj",
    "meta": {
        "color": "red",
        "size": "xsmall"
    },
    "blocked": false,
    "raw_policy_enabled": false,
    "policy": {
        "basic": {
            "justification_required": true,
            "clients": [
                "richard-roe@google.com",
                "john-doe@thales-test-proj.iam.gserviceaccount.com"
            ],
            "justification_reason": [
                "CUSTOMER_INITIATED_SUPPORT"
            ]
        },
        "rego": "\npackage example\ndefault allow = false\n\ndefault allowedClient = false\nallowedClient {\n\t\tinput.clients = {\"richard-roe@google.com\",\"john-doe@thales-test-proj.iam.gserviceaccount.com\"}[_]\n}\n\ndefault allowedJustification = false\nallowedJustification  {\n\t\tinput.justificationReason  = {\"CUSTOMER_INITIATED_SUPPORT\"}[_]\n}\n\nallow {\n    allowedClient\n    allowedJustification\n}\n"
    },
    "hostname": "ciphertrust.mycompany.com",
    "name": "cryptospace_1",
    "location": "us-east1",
    "description": "cryptospace for testing control plane",
    "cryptospace_path": "api/v1/cckm/ekm/cryptospaces/f84149ea-d8b3-465a-907d-f2724c635798",
    "permissions": [
        {
            "service_account": "test-ekm@testgcp-prj.iam.gserviceaccount.com",
            "permissions": [
                "CREATE_KEY",
                "DESTROY_KEY",
                "WRAP",
                "UNWRAP",
                "GET_PUBLIC_KEY",
                "ASYMMETRIC_SIGN",
                "GET_INFO"
            ]
        },
        {
            "service_account": "test2-ekm@testgcp-prj.iam.gserviceaccount.com",
            "permissions": [
                "WRAP",
                "UNWRAP"
            ]
        }
    ]
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

List EKM Cryptospaces

Use GET for /v1/cckm/ekm/cryptospaces to return a list of EKM cryptospaces. You can filter the results based on query parameters.

Syntax

curl -k 'https://<ciphertrust_fqdn>/api/v1/cckm/ekm/cryptospaces' -H 'Authorization: Bearer 'AUTHTOKEN' -H 'accept: application/json' --compressed

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Request Query Parameters

Parameter	Type	Description
id	string	Filter the results based on the EKM cryptospace ID.
name	string	Filter the results based on the EKM cryptospace name.
project_id	string	Filter the results based on the Google project ID.
type	string	Filter the results based on the EKM cryptospace type.
location	string	Filter the results based on the Google location.
skip	integer	The index of the first resource to return. Equivalent to 'offset' in SQL.
limit	integer	The max number of resources to return. Equivalent to 'limit' in SQL.

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/cryptospaces' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1NmE5OGU5Ny1mZTA1LTRjMTUtOWM5YS04ZmU5ZjM4YWM2NGIiLCJzdWIiOiJsb2NhbHw4ZGE4NDFmZC0yOTA2LTQ5MWMtODAxMC02YjAwMDgzM2IwYWQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfdHlwZSI6InVucmVnaXN0ZXJlZCIsImRvbWFpbl9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImdyb3VwcyI6WyJhZG1pbiJdLCJzaWQiOiI0ZDUxMjFkNS03ZmM2LTRkNDAtYmMyZS04ZGY3MzNiZjBmNzciLCJ6b25lX2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIn0sImp3dGlkIjoiOThiYWE1YWEtNTI1Ni00ZGQwLWI0YjQtOWU2MGZjNWIzNzBjIiwiaWF0IjoxNjc0MjU3Njk4LCJleHAiOjE2NzQyNTc5OTh9.pdNn2PDSnrT2k-KMPCl_IoZ4WtXtoLFaI7oUYlFly3Y' -H 'accept: application/json' --compressed

Example Response

{
"application/json": {
    "skip": 0,
    "limit": 10,
    "total": 3,
    "resources": [
        {
            "id": "e94093c5-f9a0-4bd6-84ea-c44ff8cb1c88",
            "uri": "kylo:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963:cckm:ekm-cryptospace:e94093c5-f9a0-4bd6-84ea-c44ff8cb1c88",
            "account": "kylo:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963:admin:accounts:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963",
            "createdAt": "2022-09-26T05:52:31.721974Z",
            "updatedAt": "2022-09-26T05:52:31.721974Z",
            "type": "ekm",
            "project_id": "thales-test-proj",
            "meta": {
                "size": "xsmall",
                "color": "red"
            },
            "blocked": false,
            "raw_policy_enabled": false,
            "policy": {
                "basic": {
                    "justification_required": true,
                    "clients": [
                        "richard-roe@google.com",
                        "john-doe@thales-test-proj.iam.gserviceaccount.com"
                    ],
                    "justification_reason": [
                        "CUSTOMER_INITIATED_SUPPORT"
                    ]
                },
                "rego": "\npackage example\ndefault allow = false\n\ndefault allowedClient = false\nallowedClient {\n\t\tinput.clients = {\"richard-roe@google.com\",\"john-doe@thales-test-proj.iam.gserviceaccount.com\"}[_]\n}\n\ndefault allowedJustification = false\nallowedJustification  {\n\t\tinput.justificationReason  = {\"CUSTOMER_INITIATED_SUPPORT\"}[_]\n}\n\nallow {\n    allowedClient\n    allowedJustification\n}\n"
            },
            "hostname": "ciphertrust.mycompany.com",
            "name": "cryptospace_1",
            "permissions": [
                {
                    "service_account": "test-ekm@testgcp-prj.iam.gserviceaccount.com",
                    "permissions": [
                        "CREATE_KEY",
                        "DESTROY_KEY",
                        "WRAP",
                        "UNWRAP",
                        "GET_PUBLIC_KEY",
                        "ASYMMETRIC_SIGN",
                        "GET_INFO"
                    ]
                },
                {
                    "service_account": "test2-ekm@testgcp-prj.iam.gserviceaccount.com",
                    "permissions": [
                        "WRAP",
                        "UNWRAP"
                    ]
                }
            ]
        },
        {
            "id": "7d8249ca-4dbf-48d7-b14d-bc6535249dcd",
            "uri": "kylo:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963:cckm:ekm-cryptospace:7d8249ca-4dbf-48d7-b14d-bc6535249dcd",
            "account": "kylo:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963:admin:accounts:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963",
            "createdAt": "2022-09-26T05:38:12.870872Z",
            "updatedAt": "2022-09-26T05:38:12.870872Z",
            "type": "ekm-ude",
            "project_id": "thales-test-proj",
            "meta": {
                "size": "large",
                "color": "red"
            },
            "blocked": true,
            "raw_policy_enabled": false,
            "policy": {
                "basic": {
                    "justification_required": true,
                    "clients": [
                        "richard-roe@google.com",
                        "john-doe@thales-test-proj.iam.gserviceaccount.com"
                    ],
                    "justification_reason": [
                        "CUSTOMER_INITIATED_SUPPORT"
                    ]
                },
                "rego": "\npackage example\ndefault allow = false\n\ndefault allowedClient = false\nallowedClient {\n\t\tinput.clients = {\"richard-roe@google.com\",\"john-doe@thales-test-proj.iam.gserviceaccount.com\"}[_]\n}\n\ndefault allowedJustification = false\nallowedJustification  {\n\t\tinput.justificationReason  = {\"CUSTOMER_INITIATED_SUPPORT\"}[_]\n}\n\ndefault allowAttestation = true\n\nallow {\n    allowedClient\n    allowedJustification\n    allowAttestation\n}\n"
            },
            "hostname": "ciphertrust.mycompany.com",
            "cvm_required_for_encrypt": true,
            "cvm_required_for_decrypt": false,
            "name": "cryptospace_2"
        },
        {
            "id": "d47cd045-616a-4b13-88c4-03cfa8817318",
            "uri": "kylo:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963:cckm:ekm-cryptospace:d47cd045-616a-4b13-88c4-03cfa8817318",
            "account": "kylo:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963:admin:accounts:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963",
            "createdAt": "2022-09-26T05:34:52.14094Z",
            "updatedAt": "2022-09-26T05:34:52.14094Z",
            "type": "ekm",
            "project_id": "thales-test-proj",
            "meta": {
                "size": "xsmall",
                "color": "red"
            },
            "blocked": false,
            "raw_policy_enabled": false,
            "policy": {
                "basic": {
                    "justification_required": true,
                    "clients": [
                        "richard-roe@google.com",
                        "john-doe@thales-test-proj.iam.gserviceaccount.com"
                    ],
                    "justification_reason": [
                        "CUSTOMER_INITIATED_SUPPORT"
                    ]
                },
                "rego": "\npackage example\ndefault allow = false\n\ndefault allowedClient = false\nallowedClient {\n\t\tinput.clients = {\"richard-roe@google.com\",\"john-doe@thales-test-proj.iam.gserviceaccount.com\"}[_]\n}\n\ndefault allowedJustification = false\nallowedJustification  {\n\t\tinput.justificationReason  = {\"CUSTOMER_INITIATED_SUPPORT\"}[_]\n}\n\nallow {\n    allowedClient\n    allowedJustification\n}\n"
            },
            "hostname": "ciphertrust.mycompany.com",
            "name": "cryptospace_3"
        }
    ]
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

View Details of an EKM Cryptospace

Use GET for /v1/cckm/ekm/cryptospaces/{id} to return the details of a given EKM cryptospace.

Syntax

curl -k 'https://<ciphertrust_fqdn>/api/v1/cckm/ekm/cryptospaces/<cryptospace_id>' -H 'Authorization: Bearer 'AUTHTOKEN' -H 'accept: application/json' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM cryptospace.

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/cryptospaces/170f6286-5da4-49b8-81f4-754ab6acf425' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI3ZTJhODM0OC1hYTkxLTQ4OTYtYjliZC00MzgwMmQ5NjU5ZmYiLCJzdWIiOiJsb2NhbHxhYzcwYjE1MS1mZmI1LTQzMTQtYjAyNS1jNjM0MTgzZmRkZjUiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfdHlwZSI6InVucmVnaXN0ZXJlZCIsImRvbWFpbl9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImdyb3VwcyI6WyJhZG1pbiJdLCJzaWQiOiJkNmQwOTUyOC02YzQ5LTQzOWItYWU0NC03M2VkMDRmNzI4ZTkiLCJ6b25lX2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIn0sImp3dGlkIjoiZDU5NDcwNmMtOTFmYS00ODg2LWI0MjYtMGMzMjYxMWFkZmQ4IiwiaWF0IjoxNjc0NjE2NzY0LCJleHAiOjE2NzQ2MTcwNjR9.3_pdScGhYotHFgqyGTafd7gn1mEWP4UiCfvrZii3IY4' -H 'accept: application/json' --compressed

Example Response

{
"application/json": {
    "id": "e94093c5-f9a0-4bd6-84ea-c44ff8cb1c88",
    "uri": "kylo:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963:cckm:ekm-cryptospace:e94093c5-f9a0-4bd6-84ea-c44ff8cb1c88",
    "account": "kylo:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963:admin:accounts:kylo-36db9ba8-816a-41ba-a6f0-1fc2bea70963",
    "createdAt": "2022-09-26T05:52:31.721974Z",
    "updatedAt": "2022-09-26T05:52:31.721974Z",
    "type": "ekm",
    "project_id": "thales-test-proj",
    "meta": {
        "size": "xsmall",
        "color": "red"
    },
    "blocked": false,
    "raw_policy_enabled": false,
    "policy": {
        "basic": {
            "justification_required": true,
            "clients": [
                "richard-roe@google.com",
                "john-doe@thales-test-proj.iam.gserviceaccount.com"
            ],
            "justification_reason": [
                "CUSTOMER_INITIATED_SUPPORT"
            ]
        },
        "rego": "\npackage example\ndefault allow = false\n\ndefault allowedClient = false\nallowedClient {\n\t\tinput.clients = {\"richard-roe@google.com\",\"john-doe@thales-test-proj.iam.gserviceaccount.com\"}[_]\n}\n\ndefault allowedJustification = false\nallowedJustification  {\n\t\tinput.justificationReason  = {\"CUSTOMER_INITIATED_SUPPORT\"}[_]\n}\n\nallow {\n    allowedClient\n    allowedJustification\n}\n"
    },
    "hostname": "ciphertrust.mycompany.com",
    "name": "cryptospace_1",
    "cryptospace_path": "api/v1/cckm/ekm/cryptospaces/f84149ea-d8b3-465a-907d-f2724c635798"
    }
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Update an EKM Cryptospace

Use PATCH with /v1/cckm/ekm/cryptospaces/{id} to update an EKM cryptospace. If you are changing policies, the syntax varies depending on whether the policy is provided in the basic or rego format.

Syntax

curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/cryptospaces/<cryptospace_id>' -X PATCH -H 'Authorization: Bearer 'AUTHTOKEN' -H 'accept: application/json' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of the EKM cryptospace.

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token
Hostname	string	Base url hostname for Ciphertrust Manager.
meta	JSON	Optional. Additional information associated with this endpoint.
cvm_required_for_encrypt	boolean	Is a confidential VM (and valid attestation) required for encryption. Applicable for UDE Endpoint only.
cvm_required_for_decrypt	boolean	Is a confidential VM (and valid attestation) required for decryption. Applicable for UDE Endpoint only.
raw_policy_enabled	boolean	Flag to denote if the sent policy is in raw format.
policy	object	Cryptospace Key Access Justification (KAJ) Policy attributes. Endpoints in a cryptospace are to inherit the cryptospace's policy. EKM endpoint in a cryptospace can have its own policy as well.
description	string	Description of a cryptospace.
permissions	object	List of service accounts and permissions. Service account used to call EKM cryptospace APIs. Service account is a string. List of permissions assigned to service account. This list is an array. Options: • CREATE_KEY • DESTROY_KEY • WRAP • UNWRAP • GET_PUBLIC_KEY • ASYMMETRIC_SIGN • GET_INFO

Policy Parameters

Policy Parameter	Type	Description
rego	string	EKM Policy in rego format.
basic	JSON	EKM Policy in basic format.

Basic Format Policy Parameters

Basic Format Policy Parameter	Type	Description
clients	array	Allowed Service Accounts. Required.
attestation_instance_names	array	Allowed Instance Names. Applicable for UDE Endpoint only.
attestation_project_ids	array	Allowed Project IDs. Applicable for UDE Endpoint only.
attestation_zones	array	Allowed zones. Applicable for UDE Endpoint only.
justification_reason	array	Justification reason can't be empty when justification_required is set to true. Allowed Key Access justification reasons. Options: • 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 • CUSTOMER_AUTHORIZED_WORKFLOW_SERVICING
justification_required	boolean	Flag to denote if key access justification should be enforced. Default is false.

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/cryptospaces/170f6286-5da4-49b8-81f4-754ab6acf425' -X PATCH -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI3ZTJhODM0OC1hYTkxLTQ4OTYtYjliZC00MzgwMmQ5NjU5ZmYiLCJzdWIiOiJsb2NhbHxhYzcwYjE1MS1mZmI1LTQzMTQtYjAyNS1jNjM0MTgzZmRkZjUiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfdHlwZSI6InVucmVnaXN0ZXJlZCIsImRvbWFpbl9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImdyb3VwcyI6WyJhZG1pbiJdLCJzaWQiOiIzZDYxYmU5MC0wODU3LTQ4OGYtODkzZi01ZTBmNTQ1NDM3YTgiLCJ6b25lX2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIn0sImp3dGlkIjoiOGQ4YjgzNTQtZjZiMi00OWM3LTk2ZjUtMjM3NjY3ZmJiMGE2IiwiaWF0IjoxNjc0NTc4ODkzLCJleHAiOjE2NzQ1NzkxOTN9.-WTscyjSYiDteph8IkGvK7fk477OUvy6yukV50NqBd8' -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary $'{\n  "hostname": "ciphertrust.mycompany.com",\n  "cvm_required_for_encrypt": false,\n  "cvm_required_for_decrypt": false,\n  "raw_policy_enabled": false,\n  "policy": {\n    "basic": {\n      "clients": [\n        "john-doe@google.com"\n      ]\n    }\n  },\n  "description": "Updated description of cryptospace",\n  "permissions": [\n    {\n      "service_account": "test-ekm@testgcp-prj.iam.gserviceaccount.com",\n      "permissions": [\n        "CREATE_KEY",\n        "DESTROY_KEY",\n        "WRAP",\n        "UNWRAP",\n        "GET_PUBLIC_KEY",\n        "ASYMMETRIC_SIGN",\n        "GET_INFO"\n      ]\n    },\n    {\n      "service_account": "test2-ekm@testgcp-prj.iam.gserviceaccount.com",\n      "permissions": [\n        "WRAP",\n        "UNWRAP"\n      ]\n    }\n  ]\n}' --compressed

Example Response

{
"application/json": {
"id": "170f6286-5da4-49b8-81f4-754ab6acf425",
"uri": "kylo:kylo:cckm:ekm-cryptospace:170f6286-5da4-49b8-81f4-754ab6acf425",
"account": "kylo:kylo:admin:accounts:kylo",
"createdAt": "2023-01-24T16:06:55.435608Z",
"updatedAt": "2023-01-24T16:48:24.64958Z",
"type": "ekm",
"project_id": "thales-test-proj",
"meta": {
    "size": "big",
    "color": "blue"
},
"blocked": false,
"raw_policy_enabled": false,
"policy": {
    "basic": {
        "justification_required": false,
        "clients": [
            "john-doe@google.com"
        ]
    },
    "rego": "\npackage example\ndefault allow = false\n\ndefault allowedClient = false\nallowedClient {\n\t\tinput.clients = {\"john-doe@google.com\"}[_]\n}\n\ndefault allowedJustification = true\n\nallow {\n    allowedClient\n    allowedJustification\n}\n"
},
"hostname": "ciphertrust.mycompany.com",
"permissions": [
    {
        "service_account": "test-ekm@testgcp-prj.iam.gserviceaccount.com",
        "permissions": [
            "CREATE_KEY",
            "DESTROY_KEY",
            "WRAP",
            "UNWRAP",
            "GET_PUBLIC_KEY",
            "ASYMMETRIC_SIGN",
            "GET_INFO"
        ]
    },
    {
        "service_account": "test2-ekm@testgcp-prj.iam.gserviceaccount.com",
        "permissions": [
            "WRAP",
            "UNWRAP"
        ]
    }
],
"name": "cryptospace_1",
"location": "us-east1",
"description": "Updated description of cryptospace",
"cryptospace_path": "api/v1/cckm/ekm/cryptospaces/170f6286-5da4-49b8-81f4-754ab6acf425"

}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Delete an EKM Cryptospace

To permanently delete a given EKM cryptospace, send a DELETE request to /v1/cckm/ekm/cryptospaces/{id}.

Syntax

curl -k '<ciphertrust-fqdn>/api/v1/cckm/ekm/cryptospaces/<cryptospace_id>' -X DELETE -H 'Authorization: Bearer 'AUTHTOKEN' -H 'accept: application/json' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of a cryptospace.

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/cryptospaces/f79b0a66-a683-44a6-9406-fb6c4c052ae8' -X DELETE -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI3ZTJhODM0OC1hYTkxLTQ4OTYtYjliZC00MzgwMmQ5NjU5ZmYiLCJzdWIiOiJsb2NhbHxhYzcwYjE1MS1mZmI1LTQzMTQtYjAyNS1jNjM0MTgzZmRkZjUiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfdHlwZSI6InVucmVnaXN0ZXJlZCIsImRvbWFpbl9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImdyb3VwcyI6WyJhZG1pbiJdLCJzaWQiOiIzYjQ4NmNlNi0zZTM3LTQ1ZmYtODgxYi00NTRmYTkxOTA0OGUiLCJ6b25lX2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIn0sImp3dGlkIjoiZTA5ODFmYWYtZDIxMS00NGQyLWFlZjAtODcxNjBkY2MzOTI0IiwiaWF0IjoxNjc0NjIzMTkyLCJleHAiOjE2NzQ2MjM0OTJ9.10XgrjivnD45M6yr_ZudyAQsgMBMmpRf_4kfHsVi-iE' -H 'accept: application/json' --compressed

Example Response

{
    "status": 204
}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Block an EKM Cryptospace

To block access to the APIs used to wrap, unwrap, asymmetric sign, create a key, and destroy a key within a given cryptospace, use POST for /v1/cckm/ekm/cryptospaces/{id}/block.

Syntax

curl -k '<ciphertrust-fqdn>/api/v1/cckm/ekm/cryptospaces/<cryptospace_id>/block' -X POST -H 'Authorization: Bearer 'AUTHTOKEN' -H 'accept: application/json' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of a cryptospace.

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/cryptospaces/f79b0a66-a683-44a6-9406-fb6c4c052ae8/block' -X POST -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiIxZTgwZjk3Yi1iN2JhLTQ1NTgtYTIzMC1hMmQ2ZWY0MGRhYTEiLCJzdWIiOiJsb2NhbHwyNGVhNzlmYy00YzAxLTRmODctYTIyYy02OGUzZjJhZmE4ZmMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfdHlwZSI6InVucmVnaXN0ZXJlZCIsImRvbWFpbl9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImdyb3VwcyI6WyJhZG1pbiJdLCJzaWQiOiJjYmM0NjY5OS0yOTUzLTRjNzEtOTY5Zi1iZWY0OTQ1YzNjYjAiLCJ6b25lX2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIn0sImp3dGlkIjoiNjk1NzE5MjYtNGE3My00MTMyLWEwMWUtNTE4YWI0OWNkNGUzIiwiaWF0IjoxNjc0NTI5Njk0LCJleHAiOjE2NzQ1Mjk5OTR9.LASn8HnESZnoDrH3YMjRE1-oH1hhyC8REmFQRrKIpNY' -H 'accept: application/json' --compressed

Example Response

{
"application/json": {
"id": "f79b0a66-a683-44a6-9406-fb6c4c052ae8",
"uri": "kylo:kylo:cckm:ekm-cryptospace:f79b0a66-a683-44a6-9406-fb6c4c052ae8",
"account": "kylo:kylo:admin:accounts:kylo",
"createdAt": "2023-01-24T22:59:52.709886Z",
"updatedAt": "2023-01-25T05:24:06.330512Z",
"type": "ekm",
"project_id": "thales-test-proj",
"meta": {
    "size": "big",
    "color": "blue"
},
"blocked": true,
"raw_policy_enabled": true,
"policy": {
    "basic": {}
},
"hostname": "ciphertrust.mycompany.com",
"permissions": [
    {
        "permissions": [
            "CREATE_KEY",
            "DESTROY_KEY",
            "WRAP",
            "UNWRAP",
            "GET_PUBLIC_KEY",
            "ASYMMETRIC_SIGN",
            "GET_INFO"
        ],
        "service_account": "starjammers-ekm@gemalto-kyloeng.iam.gserviceaccount.com"
    }
],
"name": "cryptospace_with_raw_policy",
"location": "us-west1",
"description": "",
"cryptospace_path": "api/v1/cckm/ekm/cryptospaces/f79b0a66-a683-44a6-9406-fb6c4c052ae8"

}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Unblock an EKM Cryptospace

To unblock access to APIs used to wrap, unwrap, asymmetric sign, create a key, and destroy a key within a given cryptospace, use POST for /v1/cckm/ekm/cryptospaces/{id}/unblock.

Syntax

curl -k '<ciphertrust-fqdn>/api/v1/cckm/ekm/cryptospaces/<cryptospace_id>/block' -X POST -H 'Authorization: Bearer 'AUTHTOKEN' -H 'accept: application/json' --compressed

Path Parameters

Parameter	Type	Description
id	string	ID of a cryptospace.

Request Parameters

Parameter	Type	Description
AUTHTOKEN	string	Authorization Token

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/cryptospaces/f79b0a66-a683-44a6-9406-fb6c4c052ae8/unblock' -X POST -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiIxZTgwZjk3Yi1iN2JhLTQ1NTgtYTIzMC1hMmQ2ZWY0MGRhYTEiLCJzdWIiOiJsb2NhbHwyNGVhNzlmYy00YzAxLTRmODctYTIyYy02OGUzZjJhZmE4ZmMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfdHlwZSI6InVucmVnaXN0ZXJlZCIsImRvbWFpbl9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImdyb3VwcyI6WyJhZG1pbiJdLCJzaWQiOiJjYmM0NjY5OS0yOTUzLTRjNzEtOTY5Zi1iZWY0OTQ1YzNjYjAiLCJ6b25lX2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIn0sImp3dGlkIjoiYmM2N2EzOTMtYzU2Mi00NTU1LWEwN2YtMzRmOWQzYmRjNTlmIiwiaWF0IjoxNjc0NTMxMTYzLCJleHAiOjE2NzQ1MzE0NjN9.i5cvk9dIOIZsK-f1gwxqeS-6es5RKoeBDosCZBH26I8' -H 'accept: application/json' --compressed

Example Response

{
"application/json": {
"id": "f79b0a66-a683-44a6-9406-fb6c4c052ae8",
"uri": "kylo:kylo:cckm:ekm-cryptospace:f79b0a66-a683-44a6-9406-fb6c4c052ae8",
"account": "kylo:kylo:admin:accounts:kylo",
"createdAt": "2023-01-24T22:59:52.709886Z",
"updatedAt": "2023-01-25T05:25:44.297994Z",
"type": "ekm",
"project_id": "thales-test-proj",
"meta": {
    "size": "big",
    "color": "blue"
},
"blocked": false,
"raw_policy_enabled": true,
"policy": {
    "basic": {}
},
"hostname": "ciphertrust.mycompany.com",
"permissions": [
    {
        "permissions": [
            "CREATE_KEY",
            "DESTROY_KEY",
            "WRAP",
            "UNWRAP",
            "GET_PUBLIC_KEY",
            "ASYMMETRIC_SIGN",
            "GET_INFO"
        ],
        "service_account": "starjammers-ekm@gemalto-kyloeng.iam.gserviceaccount.com"
    }
],
"name": "cryptospace_with_raw_policy",
"location": "us-west1",
"description": "",
"cryptospace_path": "api/v1/cckm/ekm/cryptospaces/f79b0a66-a683-44a6-9406-fb6c4c052ae8"

}

Response Codes

Response Code	Description
2xx	Success
4xx	Client errors
5xx	Server errors

Refer to HTTP status codes for details.

Suggest A Change

Google Cloud EKM APIs

Ubiquitous Data Encryption

Related Pages

Google Cloud EKM API Endpoints on CipherTrust Manager

Create an EKM or EKM UDE Endpoint

Syntax with policy in basic format

Syntax with policy in rego format

Request Parameters

Policy Parameters

Basic Format Policy Parameters

Example Request

Example Response

Response Codes

List EKM or EKM UDE Endpoints

Syntax

Request Parameters

Request Query Parameters

Example Request

Example Response

Response Codes

Viewing Details for an EKM or EKM UDE Endpoint

Syntax

Path Parameters

Request Parameters

Example Request

Example Response

Response Codes

Update An EKM or EKM UDE Endpoint

Syntax with policy in basic format

Syntax with policy in rego format

Path Parameters

Request Parameters

Policy Parameters

Basic Format Policy Parameters

Example Request

Example Response

Response Codes

Delete An EKM or EKM UDE Endpoint

Syntax

Path Parameters

Request Parameters

Example Request

Example Response

Response Codes

List EKM or EKM UDE Policies

Syntax

Path Parameters

Request Parameters

Example Request

Example Response

Response Codes

Update EKM or EKM UDE Policies

Syntax

Path Parameters

Request Parameters

Example Request

Example Response

Response Codes

Rotate An EKM or EKM UDE Endpoint

Syntax

Path Parameters

Request Parameters

Example Request

Example Response

Response Codes

Enable an EKM or EKM UDE Endpoint

Syntax

Path Parameters

Request Parameters

Example Request

Example Response

Response Codes

Disable an EKM or EKM UDE Endpoint

Syntax

Path Parameters

Request Parameters

Example Request

Example Response

Response Codes