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
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.
Note
CCKM doesn't support Google BYOK for Google Trusted Partner Clouds (TPC).
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.
Related Pages
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 (optional) | JSON | Additional information associated with this endpoint. |
| cvm_required_for_decrypt (optional) | boolean | Is a confidential VM (and valid attestation) required for decryption. Default is false. Applicable for UDE Endpoint only. |
| cvm_required_for_encrypt (optional) | boolean | Is a confidential VM (and valid attestation) required for encryption. Default is false. Applicable for UDE Endpoint only. |
| endpoint_type (optional) | string | EKM Endpoint type. Can be either "ekm" or "ekm-ude". Default is ekm. |
| key_type (optional) | string | EKM Key type. For existing keys, this must match the supplied key. Options are either symmetric or asymmetric. Default is symmetric. |
| algorithm (optional) | 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 (optional) | 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 (optional) | 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 | Filter the results based on the relative resource name (without version) of the GCP Cloud KMS Key. |
| unique_rrn_without_version | boolean | Filter the endpoints with unique values for relative resource name (by creation time) would be returned. |
| 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). |
| 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/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",
<!--- #if platform -->
"cryptospace_id": "76e5b274-5cb8-4aa5-9645-164f375bbb35",
<!--- #endif -->
"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\",\"CUSTOMER_AUTHORIZED_WORKFLOW_SERVICING\"}[_]\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",
"location": "us-central1"
},
{
"account": "kylo:kylo:admin:accounts:kylo",
"algorithm": "AES256",
"application": "ncryptify:gemalto:admin:apps:kylo",
"createdAt": "2022-11-23T01:47:40.727232Z",
<!--- #if platform -->
"cryptospace_id": "a5d55e6f-6145-40ca-86e3-d9b2ec77503f",
"cryptospace_name": "cryptospace-1",
<!--- #endif -->
"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,
<!--- #if platform -->
"name": "cryptospace-1/my-proj/us-central1/my-keyring/key-test-1/0",
<!--- #endif -->
"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",
"location": "us-central1"
}
]
}
}
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 (optional) | string | Base url hostname for KeyURI. |
| meta (optional) | JSON | Additional information associated with this endpoint. |
| cvm_required_for_encrypt (optional) | boolean | Is a confidential VM (and valid attestation) required for encryption. Default is false. Applicable for UDE Endpoint only. |
| cvm_required_for_decrypt (optional) | boolean | Is a confidential VM (and valid attestation) required for decryption. Default is false. Applicable for UDE Endpoint only. |
| raw_policy_enabled (optional) | boolean | Flag to denote if the sent policy is in raw format. Default is false. |
| policy (optional) | 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": false,
"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.
Destroy an EKM Cryptospace Endpoint
Use post /v1/cckm/ekm/endpoints/{id}/destroy to destroy an EKM cryptospace endpoint key. A label "reason": "local_destroyed" will be added to the key.
Syntax
curl -k '<IP>/api/v1/cckm/ekm/endpoints/{id}/destroy' -X POST -H 'Authorization: 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://127.0.0.1/api/v1/cckm/ekm/endpoints/121e23/destroy' -X POST -H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzQwNWViYi00NmIwLTQ4NTYtYTA1ZS0wYWY4YTA5NThlMWIiLCJzdWIiOiJsb2NhbHw2ODVmN2I4Ni0xNGJhLTQyMmMtYjhhNy1lNmM0ZmIzM2FjNTgiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfaWQiOiI4MzdjODQwZC03NWRkLTRiNGYtYTMxOC03OWNiMTZjYTI0OGQiLCJjbGllbnRfbmFtZSI6ImFwaS1wbGF5Z3JvdW5kIiwiY2xpZW50X3R5cGUiOiJwdWJsaWMiLCJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODM3Yzg0MGQtNzVkZC00YjRmLWEzMTgtNzljYjE2Y2EyNDhkIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6ImEzNTM2MzUyLTY1OWMtNGE1Zi05MjczLWZjZmVlYTQwYWM5NiIsImlhdCI6MTcyMjk2MTY0MSwiZXhwIjoxNzIyOTYxOTQxfQ.kgwyr8SV8QGk8sUJtGgmWrd-0JnPfGBu05-9afy7D3x7MgLAoseFbxEP7LOxMFdrdvUR3BVWqYZ3AUVKzjXeYA' -H 'accept: application/json' --compressed
Example Response
{
"application/json": {
"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"
},
"label": {
"reason": "local_destroyed"
},
"enabled": false,
"state": "DESTROYED",
"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\",\"MODIFIED_GOOGLE_INITIATED_SYSTEM_OPERATION\",\"CUSTOMER_AUTHORIZED_WORKFLOW_SERVICING\"}[_]\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 |
| 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 |
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 |
| 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 |
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 |
| 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 |
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 |
| 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 |
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 |
| 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 |
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
CCKM doesn't support Google BYOK for Google Trusted Partner Clouds (TPC).
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 (optional) | string | Description of a cryptospace. |
| permissions (optional) | 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 List of issuers associated with the service account, (for TPC enabled only). |
| tpc_enabled (optional) | boolean | This field indicates whether the cryptospace is TPC Enabled. The Default is false. When tpc_enabled is true, make sure that justification_required is false. |
Note
If you are setting the value of raw_policy_enabled as true, it is up to you to validate this policy.
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.
When tpc_enabled is true, make sure that justification_required 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, permissions, and issuers (for TPC enabled only). 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 List of issuers associated with the service account, (for TPC enabled only). |
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.
Google Cloud EKM Issuer APIs
CCKM provides APIs to the users to manage the EKM Issuers.
Create an EKM Issuer
Use the post /v1/cckm/ekm/issuers API to create a valid issuer for EKM Cryptospace. When creating the issuer, you must specify a unique name along with one of the following combinations.
issuer and jwks_uri.
openid_config_url: This will be used to auto-fetch the issuer and jwks_uri.
Syntax
curl -k '<IP>/api/v1/cckm/ekm/issuers' -X POST -H 'Authorization: Bearer AUTHTOKEN' --compressed
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| name | string | Name of the issuer. It should be unique. |
| issuer (optional) | string | URL for the issuer. |
| jwks_uri (optional) | string | URI of JWKS, for example, https://abc.auth0.com/.well-known/jwks.json. |
| openid_config_url (optional) | string | OpendID configuration URL for the issuer. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/ekm/issuers' -X POST -H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkYjQ3MmEzMS1hZGZlLTQ5OTktYjdmYS02NWNmYzAwYWNkYWEiLCJzdWIiOiJsb2NhbHw1OWZiZDEyZC0wOTZhLTRmZDItODMwYi0yNGYyYjA2M2U5OWIiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfaWQiOiI4MzdjODQwZC03NWRkLTRiNGYtYTMxOC03OWNiMTZjYTI0OGQiLCJjbGllbnRfbmFtZSI6ImFwaS1wbGF5Z3JvdW5kIiwiY2xpZW50X3R5cGUiOiJwdWJsaWMiLCJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODM3Yzg0MGQtNzVkZC00YjRmLWEzMTgtNzljYjE2Y2EyNDhkIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijc2ZWY1MDhhLWM2ODQtNDc5NS1iMmQ4LWRjM2U2YzRlYWM3OCIsImlhdCI6MTcyMDAxMDY3NywiZXhwIjoxNzIwMDEwOTc3fQ.V2E5cRoiksqSMLEuPX4ZesH4kfRHP40_bTX4fHkVBmmEj4GZWPJhPLq2LJEWnPQFh24PaD8lkA4plWAO_3Y3TA' -H 'accept: application/json' --compressed
Example Response
{
"id": "9a82d3cc-c79f-478f-b6f6-c3b480c0b400",
"uri": "kylo:kylo:cckm:abcd",
"account": "kylo:kylo:admin:accounts:kylo",
"createdAt": "2022-09-22T21:22:03.959447Z",
"updatedAt": "2022-09-22T21:24:35.503393Z",
"name": "issuerOne",
"openid_config_url": "https://www.example.com/openid-configuration",
"issuer": "https://issuer.com",
"jwks_uri": "https://www.example.com/jwks.json"
}
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
View EKM Issuers
Use the get /v1/cckm/ekm/issuers API to view the list of the EKM issuers. The results can be filtered using the query parameters.
Syntax
curl -k '<IP>/api/v1/cckm/ekm/issuers?skip=0&limit=10&sort=updatedAt' -H 'Authorization: Bearer AUTHTOKEN' --compressed
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| ID | string | ID of the EKM Issuer on the CipherTrust Manager. |
| name | string | Name of the EKM Issuer. |
| issuer | string | URL for the issuer. |
| skip | integer | Number of records to skip. For example, if "skip":5 is specified, the first five records will not be displayed in the output. |
| limit | integer | Numbers of records to display. For example, if "limit":10 is specified, then the next 10 records (after skipping the number of records specified in the skip parameter) will be displayed in the output. |
| sort | string | Comma-delimited list of properties to sort the results. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/ekm/issuers?skip=0&limit=10&sort=updatedAt' -H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkYjQ3MmEzMS1hZGZlLTQ5OTktYjdmYS02NWNmYzAwYWNkYWEiLCJzdWIiOiJsb2NhbHw1OWZiZDEyZC0wOTZhLTRmZDItODMwYi0yNGYyYjA2M2U5OWIiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfaWQiOiI4MzdjODQwZC03NWRkLTRiNGYtYTMxOC03OWNiMTZjYTI0OGQiLCJjbGllbnRfbmFtZSI6ImFwaS1wbGF5Z3JvdW5kIiwiY2xpZW50X3R5cGUiOiJwdWJsaWMiLCJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODM3Yzg0MGQtNzVkZC00YjRmLWEzMTgtNzljYjE2Y2EyNDhkIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjEwOTUwZmY0LTIzMWEtNGI0Yy05ZTY2LTQ4YzRlN2U1Y2NmYyIsImlhdCI6MTcyMDAzOTc4NSwiZXhwIjoxNzIwMDQwMDg1fQ.ri6Zq9KeGw_xUNv46kf4Hq23c666IzID5HPtWP76Ei0k7T0sbJOrHnqU0oRxJTo6bb0ICA1ol9VCeqtLsCcqQA' -H 'accept: application/json' --compressed
Example Response
{
"skip": 0,
"limit": 10,
"total": 1,
"resources": [
{
"id": "9a82d3cc-c79f-478f-b6f6-c3b480c0b400",
"uri": "kylo:kylo:cckm:issuerOne",
"account": "kylo:kylo:admin:accounts:kylo",
"createdAt": "2022-09-22T21:22:03.959447Z",
"updatedAt": "2022-09-22T21:22:03.959447Z",
"name": "issuerOne",
"openid_config_url": "https://www.example.com/openid-configuration",
"issuer": "https://issuer.com",
"jwks_uri": "https://www.example.com/jwks.json"
}
]
}
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 Issuer
Use the get /v1/cckm/ekm/issuers/{id} API to view the details of an EKM issuer with the given id.
Syntax
curl -k '<IP>/api/v1/cckm/ekm/issuers/{id}' -H 'Authorization: Bearer AUTHTOKEN' --compressed
Here, {id} represents the ID of the EKM Issuer on the CipherTrust Manager.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/ekm/issuers/adg3' -H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkYjQ3MmEzMS1hZGZlLTQ5OTktYjdmYS02NWNmYzAwYWNkYWEiLCJzdWIiOiJsb2NhbHw1OWZiZDEyZC0wOTZhLTRmZDItODMwYi0yNGYyYjA2M2U5OWIiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfaWQiOiI4MzdjODQwZC03NWRkLTRiNGYtYTMxOC03OWNiMTZjYTI0OGQiLCJjbGllbnRfbmFtZSI6ImFwaS1wbGF5Z3JvdW5kIiwiY2xpZW50X3R5cGUiOiJwdWJsaWMiLCJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODM3Yzg0MGQtNzVkZC00YjRmLWEzMTgtNzljYjE2Y2EyNDhkIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6ImM0OWMwN2UwLWZkY2YtNGRjZC05OWQ5LTgzMWVjMTI4ODAwZSIsImlhdCI6MTcyMDA0MDg3NiwiZXhwIjoxNzIwMDQxMTc2fQ.chrzR1CaaXQHS1uxvmwbD0rlfVX21uWZvidm4alcQpiwKzRHUhHFF0SnN0bnSlHd58vKCWwhpDbznmuhivoj5g' -H 'accept: application/json' --compressed
Example Response
{
"id": "9a82d3cc-c79f-478f-b6f6-c3b480c0b400",
"uri": "kylo:kylo:cckm:abcd",
"account": "kylo:kylo:admin:accounts:kylo",
"createdAt": "2022-09-22T21:22:03.959447Z",
"updatedAt": "2022-09-22T21:24:35.503393Z",
"name": "issuerOne",
"openid_config_url": "https://www.example.com/openid-configuration",
"issuer": "https://issuer.com",
"jwks_uri": "https://www.example.com/jwks.json"
}
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Update an EKM Issuer
Use the patch /v1/cckm/ekm/issuers/{id} API to update an EKM issuer for the given id.
Syntax
curl -k '<IP>/api/v1/cckm/ekm/issuers/{id}' -X PATCH -H 'Authorization: Bearer AUTHTOKEN' --compressed
Here, {id} represents the ID of the EKM Issuer on the CipherTrust Manager.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| name (optional) | string | Unique name for the issuer. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/ekm/issuers/234Kl' -X PATCH -H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiIxNTIzYmRlMy1iYzE4LTQ3YzMtODk0Yi00ZjM2M2ViMmE1ZGIiLCJzdWIiOiJsb2NhbHxmZmRlZDcxOS1jODcxLTQyMmItOTE5Ni0zNzcyNjIyZDM5Y2EiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfaWQiOiI4MzdjODQwZC03NWRkLTRiNGYtYTMxOC03OWNiMTZjYTI0OGQiLCJjbGllbnRfbmFtZSI6ImFwaS1wbGF5Z3JvdW5kIiwiY2xpZW50X3R5cGUiOiJwdWJsaWMiLCJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODM3Yzg0MGQtNzVkZC00YjRmLWEzMTgtNzljYjE2Y2EyNDhkIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjI1YThiOTc5LWM5ZWEtNDI5MS04YTFhLTRmNWU2ZjljOTMyYiIsImlhdCI6MTcyMDA3MjIxNiwiZXhwIjoxNzIwMDcyNTE2fQ.pVEzHcs6KgpFwee1iEOzw2DopBZmY736zXu27CU7Hmt7FaUT8Dvdth66TBMzGaQwreXnMU8toh3F0-Om47-bSQ' -H 'accept: application/json' --compressed
Example Response
{
"id": "9a82d3cc-c79f-478f-b6f6-c3b480c0b400",
"uri": "kylo:kylo:cckm:abcd",
"account": "kylo:kylo:admin:accounts:kylo",
"createdAt": "2022-09-22T21:22:03.959447Z",
"updatedAt": "2022-09-22T21:24:35.503393Z",
"name": "issuerTwo",
"openid_config_url": "https://www.example.com/openid-configuration",
"issuer": "https://issuer.com",
"jwks_uri": "https://www.example.com/jwks.json"
}
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Delete an EKM Issuer
Use the delete /v1/cckm/ekm/issuers/{id} API to delete an EKM issuer from the CCKM.
Syntax
curl -k '<IP>/api/v1/cckm/ekm/issuers/{id}' -X DELETE -H 'Authorization: Bearer AUTHTOKEN' --compressed
Here, {id} represents the ID of the EKM Issuer on the CipherTrust Manager.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/ekm/issuers/234Kl' -X DELETE -H 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiIxNTIzYmRlMy1iYzE4LTQ3YzMtODk0Yi00ZjM2M2ViMmE1ZGIiLCJzdWIiOiJsb2NhbHxmZmRlZDcxOS1jODcxLTQyMmItOTE5Ni0zNzcyNjIyZDM5Y2EiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfaWQiOiI4MzdjODQwZC03NWRkLTRiNGYtYTMxOC03OWNiMTZjYTI0OGQiLCJjbGllbnRfbmFtZSI6ImFwaS1wbGF5Z3JvdW5kIiwiY2xpZW50X3R5cGUiOiJwdWJsaWMiLCJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODM3Yzg0MGQtNzVkZC00YjRmLWEzMTgtNzljYjE2Y2EyNDhkIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjUwODIzZWE2LTQxZjItNDlkZi05N2IyLTczM2U2MzJkYTNmNSIsImlhdCI6MTcyMDA3MjkwMiwiZXhwIjoxNzIwMDczMjAyfQ.cocmAyjGEx8jNHMgmPRZSamyNEbEuy9wCFWBi9lmFv1FwFBmjstDat3Kz7UHcNT8FRR2SFEy2e9beGZYUk_g5w' -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.
