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.
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. VPC can increase performance for wrap and unwrap operations, and consolidate network management in a secure Google Cloud environment.
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.
As well, there are 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. |
| meta | JSON | Optional. Additional information associated with this endpoint. |
| cvm_required_for_decrypt | boolean | Is a confidential VM (and valid attestation) required for decryption. Default is false. Applicable for UDE Endpoint only. |
| cvm_required_for_encrypt | boolean | Is a confidential VM (and valid attestation) required for encryption. Default is false. Applicable for UDE Endpoint only. |
| endpoint_type | string | EKM Endpoint type. Can be either "ekm" or "ekm-ude". Default is ekm. |
| key_type | string | EKM Key type. For existing keys, this must match the supplied key. Options are either symmetric or asymmetric. Default is symmetric. |
| algorithm | string | EKM Key Algorithm. For existing keys, this must match the supplied key. Default is AES256. Supported values are AES256, RSA_SIGN_PSS_2048_SHA256, RSA_SIGN_PSS_3072_SHA256, RSA_SIGN_PSS_4096_SHA256, RSA_SIGN_PSS_4096_SHA512, RSA_SIGN_PKCS1_2048_SHA256, RSA_SIGN_PKCS1_3072_SHA256, RSA_SIGN_PKCS1_4096_SHA256, RSA_SIGN_PKCS1_4096_SHA512, EC_SIGN_P256_SHA256,EC_SIGN_P384_SHA384 |
| existing_key_id | string | ID of existing key to use. This is applicable for migrating EKM integration from another CipherTrust Manager deployment. If not supplied, a new key will be created. |
| raw_policy_enabled | boolean | Flag to denote if the sent policy is in raw format. Default is false. EKM Policy in basic format is required if raw_policy_enabled=false. |
| policy | JSON | EKM Policy Attributes |
Policy Parameters
| Policy Parameter | Type | Description |
|---|---|---|
| rego | string | EKM Policy in rego format. Required field if raw_policy_enabled=true. |
| basic | JSON | EKM Policy in basic format. Required field if raw_policy_enabled=false. |
Basic Format Policy Parameters
| Basic Format Policy Parameter | Type | Description |
|---|---|---|
| clients | array | Allowed Service Accounts. Required. |
| attestation_instance_names | array | Allowed Instance Names. Applicable for UDE Endpoint only. |
| attestation_project_ids | array | Allowed Project IDs. Applicable for UDE Endpoint only. |
| attestation_zones | array | Allowed zones. Applicable for UDE Endpoint only. |
| justification_reason | array | Justification reason can't be empty when justification_required is set to true. Allowed Key Access justification reasons. Options: • REASON_UNSPECIFIED, • CUSTOMER_INITIATED_SUPPORT, • GOOGLE_INITIATED_SERVICE, • THIRD_PARTY_DATA_REQUEST, • GOOGLE_INITIATED_REVIEW, • CUSTOMER_INITIATED_ACCESS •GOOGLE_INITIATED_SYSTEM_OPERATION, • REASON_NOT_EXPECTED • MODIFIED_CUSTOMER_INITIATED_ACCESS, • GOOGLE_RESPONSE_TO_PRODUCTION_ALERT |
| 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.
Listing 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. |
| 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. |
| 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. |
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": "1,",
"resources": [
{
"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": 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.
Viewing Details for an EKM or EKM UDE Endpoint
Use GET for /v1/cckm/ekm/endpoints/{id} to return the details of the given EKM endpoint.
Syntax
curl -k 'https://<ciphertrust_hostname>/api/v1/cckm/ekm/endpoints/<ekm_endpoint_id>' -H 'AUTHTOKEN' --compressed
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the EKM Endpoint |
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization Token |
Example Request
curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiYjQ5NDY5ZjgtMDJhNi00ZTgxLTliMDEtNGU1MTk2MjA0NzIwIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijc2ZTc1N2JiLWJiYTgtNDJiNy04OTI1LWMwYWFmZTQ0NzNiMSIsImlhdCI6MTYyNjExODk4OCwiZXhwIjoxNjI2MTE5Mjg4fQ.gwvR6t2-E5DFLatL6CdGdJnphDlkHp1Rog9xUlz_DWs' --compressed
Example Response
{
"application/json": {
"id": "a15d481e-9d30-4891-a55b-311a7f9d93c1",
"uri": "kylo:kylo:cckm:ekm-e2e-key:ekmendpoint-1",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2021-11-17T22:48:10.81538Z",
"name": "ekmendpoint_1",
"updatedAt": "2021-11-17T22:48:10.81538Z",
"keyURIHostname": "ekm.thales.com",
"keyURI": "https://ekm.thales.com/api/v1/cckm/ekm/endpoints/a15d481e-9d30-4891-a55b-311a7f9d93c1",
"kekName": "ks-4b9e5fe0d7934bf7a115db711a88b7073a933af817d04651a0323af811bcf95f",
"kekID": "4b9e5fe0d7934bf7a115db711a88b7073a933af817d04651a0323af811bcf95f",
"meta": {
"size": "big",
"color": "blue"
},
"enabled": true,
"kekVersion": "0",
"cvm_required_for_encrypt": true,
"cvm_required_for_decrypt": true,
"endpoint_type": "ekm-ude",
"key_type": "symmetric",
"raw_policy_enabled": true,
"policy": {
"basic": {},
"rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n input.justificationReason = {\"REASON_UNSPECIFIED\",\"CUSTOMER_INITIATED_SUPPORT\",\"GOOGLE_INITIATED_SERVICE\",\"THIRD_PARTY_DATA_REQUEST\",\"GOOGLE_INITIATED_REVIEW\",\"CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_INITIATED_SYSTEM_OPERATION\",\"REASON_NOT_EXPECTED\",\"MODIFIED_CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n input.attestationZones = {\"us-east1a\"}[_]\r\n input.attestationProjectIDs = {\"project1\"}[_]\r\n input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n allowedClient\r\n allowedJustification\r\n allowAttestation\r\n}"
},
"algorithm": "AES256"
}
}
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Update An EKM or EKM UDE Endpoint
Use PATCH with /v1/cckm/ekm/endpoints/{id} to update the endpoint's base hostname, meta data, confidential VM requirements for operations, policy format, or policies. If you are changing policies, the syntax varies depending on whether the policy is provided in basic or rego format
Syntax with policy in basic format
curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>' -X PATCH -H 'Authorization: AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n "keyURIHostname": "<new_URL"\n, "meta": {<key>:<value>}\n "cvm_required_for_encrypt": <boolean>,\n "cvm_required_for_decrypt": <boolean>,\n "raw_policy_enabled":false,\n "policy": {\n "basic": {\n "clients": [<allowed-service-accounts>], \n "attestation_instance_names": [<allowed-instance-names>],\n "attestation_project_ids": [<allowed-project-ids>],\n "attestation_zones": [<allowed-zones>],\n "justification_reason": [<allowed-key-access justification-reasons>],\n "justification_required": boolean \n}'}' --compressed
Syntax with policy in rego format
curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>' -X PATCH -H 'Authorization: AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n "keyURIHostname": "<new_URL"\n, "meta": {<key>:<value>}\n "cvm_required_for_encrypt": <boolean>,\n "cvm_required_for_decrypt": <boolean>,\n "raw_policy_enabled": true,\n "policy": {\n "rego": <rego-policy-string> \n }\n}'}' --compressed
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the EKM or EKM UDE Endpoint |
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization Token |
| keyURIHostname | string | Base url hostname for KeyURI. |
| meta | JSON | Optional. Additional information associated with this endpoint. |
| cvm_required_for_encrypt | boolean | Is a confidential VM (and valid attestation) required for encryption. Default is false. Applicable for UDE Endpoint only. |
| cvm_required_for_decrypt | boolean | Is a confidential VM (and valid attestation) required for decryption. Default is false. Applicable for UDE Endpoint only. |
| raw_policy_enabled | boolean | Flag to denote if the sent policy is in raw format. Default is false. |
| policy | JSON | EKM Policy Attributes |
Policy Parameters
| Policy Parameter | Type | Description |
|---|---|---|
| rego | string | EKM Policy in rego format. |
| basic | JSON | EKM Policy in basic format. |
Basic Format Policy Parameters
| Basic Format Policy Parameter | Type | Description |
|---|---|---|
| clients | array | Allowed Service Accounts. Required. |
| attestation_instance_names | array | Allowed Instance Names. Applicable for UDE Endpoint only. |
| attestation_project_ids | array | Allowed Project IDs. Applicable for UDE Endpoint only. |
| attestation_zones | array | Allowed zones. Applicable for UDE Endpoint only. |
| justification_reason | array | Justification reason can't be empty when justification_required is set to true. Allowed Key Access justification reasons. Options: • REASON_UNSPECIFIED, • CUSTOMER_INITIATED_SUPPORT, • GOOGLE_INITIATED_SERVICE, • THIRD_PARTY_DATA_REQUEST, • GOOGLE_INITIATED_REVIEW, • CUSTOMER_INITIATED_ACCESS •GOOGLE_INITIATED_SYSTEM_OPERATION, • REASON_NOT_EXPECTED • MODIFIED_CUSTOMER_INITIATED_ACCESS, • GOOGLE_RESPONSE_TO_PRODUCTION_ALERT |
| justification_required | boolean | Flag to denote if key access justification should be enforced. Default is false. |
Example Request
curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test' -X PATCH -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhMWU0ODRhMi05MGQxLTQ3MmItYjk1ZC05MTJlOGRkMjQ3NGEiLCJzdWIiOiJsb2NhbHwyZGE3ZWI4Ny1iZGU0LTQ3ZDgtYmVlNC1mMDJiMzk0ODIxZWIiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiYTNiNmRjNWMtY2Y4YS00ZTVkLWEwYWUtN2UxZjQ0NjczNTI1Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6ImI4MWUxNzg5LWMwMTItNDFmZC1hZjJlLTJmNGQyM2ZlN2Q2MCIsImlhdCI6MTYzODU0NDAwMCwiZXhwIjoxNjM4NTQ0MzAwfQ.HOGqk0pOUDyJsVahADs5vJKuZanZW1dnfNC9G_-HmFs' -H 'Content-Type: application/json' --data-binary $'{\n "keyURIHostname": "ciphertrust.newcompany.com",\n "cvm_required_for_encrypt": false,\n "cvm_required_for_decrypt": false,\n "raw_policy_enabled": false,\n "policy": {\n "basic": {\n "clients": [\n "abc@google.com"\n ],\n "justification_required": true,\n "justification_reason": [\n "REASON_UNSPECIFIED",\n "CUSTOMER_INITIATED_SUPPORT"\n ],\n "attestation_zones": [\n "zone1",\n "zone2"\n ],\n "attestation_project_ids": [\n "project1",\n "project2"\n ],\n "attestation_instance_names": [\n "instance1",\n "instance2"\n ]\n }\n }\n}' --compressed
Example Response
{
"application/json": {
"id": "04f63144-940c-4c4f-8426-1917b54e0c33",
"uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2021-02-10T00:19:40.321138Z",
"name": "ekmendpoint_1",
"updatedAt": "2021-02-10T00:20:25.036189Z",
"keyURIHostname": "ciphertrust.newcompany.com",
"keyURI": "https://ciphertrust.newcompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
"kekName": "ekmendpoint_1",
"kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
"meta": {
"size": "big",
"color": "yellow"
},
"enabled": true,
"kekVersion": "0"
"cvm_required_for_encrypt": false,
"cvm_required_for_decrypt": false,
"endpoint_type": "ekm",
"key_type": "symmetric",
"algorithm": "AES256",
"raw_policy_enabled": false,
"policy": {
"basic": {
"clients": [
"abc@google.com"
],
"justification_required": true,
"justification_reason": [
"REASON_UNSPECIFIED",
"CUSTOMER_INITIATED_SUPPORT"
],
"attestation_zones": [
"zone1",
"zone2"
],
"attestation_project_ids": [
"project1",
"project2"
],
"attestation_instance_names": [
"instance1",
"instance2"
]
},
"rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n input.justificationReason = {\"REASON_UNSPECIFIED\",\"CUSTOMER_INITIATED_SUPPORT\",\"GOOGLE_INITIATED_SERVICE\",\"THIRD_PARTY_DATA_REQUEST\",\"GOOGLE_INITIATED_REVIEW\",\"CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_INITIATED_SYSTEM_OPERATION\",\"REASON_NOT_EXPECTED\",\"MODIFIED_CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n input.attestationZones = {\"us-east1a\"}[_]\r\n input.attestationProjectIDs = {\"project1\"}[_]\r\n input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n allowedClient\r\n allowedJustification\r\n allowAttestation\r\n}"
}
}
}
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Delete An EKM or EKM UDE Endpoint
To permanantly delete an EKM or EKM UDE Endpoint, and therefore the Key Encryption Key (KEK) associated with it, send a DELETE request to /v1/cckm/ekm/endpoints/{id}
Syntax
curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/<ekm_endpoint_id>' -X DELETE -H 'AUTHTOKEN' --compressed
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the EKM or EKM UDE Endpoint |
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization Token |
Example Request
curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test' -X DELETE -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA5MjViMzktYzQ0OS00YWYzLWI0Y2UtOTJlYzkxODc1YTk2Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjhjYzAyNzhjLTIxODItNGRkZC1iNGZmLTYwYWMyNTgzYjVmZiIsImlhdCI6MTYyNjEyNDAzMiwiZXhwIjoxNjI2MTI0MzMyfQ.mPf1683qErNbtipKLPUKKShdmLwtx0XRD5rj2ft6UMI' --compressed
Example Response
{
"status": 204
}
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
List EKM or EKM UDE Policies
Use GET with /v1/cckm/ekm/endpoints/{id}/policies to list the active policies for an endpoint. The policy language and model are derived from the Open Policy Agent (OPA) policy engine.
Syntax
curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>/policies' -H 'AUTHTOKEN' --compressed
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the EKM or EKM UDE Endpoint |
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization Token |
Example Request
curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test/policies' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA5MjViMzktYzQ0OS00YWYzLWI0Y2UtOTJlYzkxODc1YTk2Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjIwNmVlMWVjLTY2MjMtNGZhNC05MjJiLWYwZGI3ZWFlMDRiOCIsImlhdCI6MTYyNjEyNTU1MywiZXhwIjoxNjI2MTI1ODUzfQ.bTQwMEQ3ivt20QluBKeA-KJBlEQ-n67kATeLMQbHlTs' --compressed
Example Response
{
"text/plain": "package example default allow = false allowedClient {\n input.client = {\"abc@google.com\"}[_]\n} allowedJustification {\n input.justificationReason == {\"REASON_UNSPECIFIED\",\"CUSTOMER_INITIATED_SUPPORT\",\"GOOGLE_INITIATED_SERVICE\",\"THIRD_PARTY_DATA_REQUEST\",\n \"GOOGLE_INITIATED_REVIEW\",\"CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_INITIATED_SYSTEM_OPERATION\",\"REASON_NOT_EXPECTED\",\n \"MODIFIED_CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\n} default allowAttestation = false allowAttestation {\n\tinput.attestationRequired = false\n} allowAttestation {\n input.attestationZones = {\"us-east1a\"}[_]\n input.attestationProjectIDs = {\"project1\"}[_]\n input.instanceNames = {\"instance1\"}[_]\n} allow {\n allowedClient\n allowedJustification\n allowAttestation\n}\n"
} }
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Update EKM or EKM UDE Policies
Use PATCH with /v1/cckm/ekm/endpoints/{id}/policies to edit the active policies for an endpoint. The policy language and model are derived from the Open Policy Agent (OPA) policy engine. You can also edit policies with the endpoint to update the endpoint generally. ).
Syntax
curl -k 'https://<ciphertrust_fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>/policies' -X PATCH -H 'AUTHTOKEN' -H 'Content-Type: text/plain' --data-binary '{ "clients" : <allowed_clients>", "justificationReason" : "<allowed_justification_reasons>", "attestationZones":<allowed-attestation-zones>, "attestationProjectIDs":<allowed-project-ids>, "instanceNames":<allowed-instance-names> }' --compressed
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the EKM or EKM UDE Endpoint |
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization Token |
| clients | string | Clients permitted to access the endpoint. |
| justificationReason | string | Justification reasons required in the request to wrap or unwrap with the endpoint. |
| attestationZones | string | Set param with Zones that should be allowed during UDE Attestation. Applicable only for UDE Endpoints. |
| attestationProjectIDs | string | Set param with Project IDs that should be allowed during UDE Attestation. Applicable only for UDE Endpoints. |
| instanceNames | string | Set param with Instance Names that should be allowed during UDE Attestation. Applicable only for UDE Endpoints. |
Example Request
curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test/policies' -X PATCH -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA1NzZkODgtMjFhNy00ZmY4LThmZWYtN2IyY2JlZWRkYjE4Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijg0M2I0Njc0LWJlZWQtNDFjNS04YjgxLWUyNzBhYzI1ZTU3ZiIsImlhdCI6MTYyNjE4MTEwNywiZXhwIjoxNjI2MTgxNDA3fQ.3nG8PoPEWOagovTpM8LVk90BxU-jgiVqaqMo0d1OcXA' -H 'Content-Type: text/plain' --data-binary '{ "clients" : "abc@yahoo.com", "justificationReason" : "REASON_UNSPECIFIED" }' --compressed
Example Response
{
"text/plain": "package example default allow = false allow {\n input.clients == {\"abc@yahoo.com\", \"abc@google.com\", \"abc@msn.com\"}[_]\n input.justificationReason == {\"REASON_UNSPECIFIED\",\"CUSTOMER_INITIATED_SUPPORT\",\"GOOGLE_INITIATED_SERVICE\",\"THIRD_PARTY_DATA_REQUEST\",\"GOOGLE_INITIATED_REVIEW\",\"CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_INITIATED_SYSTEM_OPERATION\",\"REASON_NOT_EXPECTED\",\"MODIFIED_CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\n}\n"
}
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Rotate An EKM or EKM UDE Endpoint
Use POST with /v1/cckm/ekm/endpoints/{id}/rotate to add a new key version with new key material to the endpoint's KEK. The Key URI remains the same.
Syntax
curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>/rotate' -X POST -H 'AUTHTOKEN' --compressed
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the EKM or EKM UDE Endpoint |
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization Token |
Example Request
curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test/rotate' -X POST -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA1NzZkODgtMjFhNy00ZmY4LThmZWYtN2IyY2JlZWRkYjE4Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijg0M2I0Njc0LWJlZWQtNDFjNS04YjgxLWUyNzBhYzI1ZTU3ZiIsImlhdCI6MTYyNjE4MTEwNywiZXhwIjoxNjI2MTgxNDA3fQ.3nG8PoPEWOagovTpM8LVk90BxU-jgiVqaqMo0d1OcXA' --compressed
Example Response
{
"application/json": {
"id": "04f63144-940c-4c4f-8426-1917b54e0c33",
"uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2021-02-10T00:19:40.321138Z",
"name": "ekmendpoint_1",
"updatedAt": "2021-02-10T00:20:25.036189Z",
"keyURIHostname": "ciphertrust.mycompany.com",
"keyURI": "https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
"kekName": "ekmendpoint_1",
"kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
"meta": {
"size": "big",
"color": "blue"
},
"enabled": true,
"kekVersion": "1"
"cvm_required_for_encrypt": false,
"cvm_required_for_decrypt": false,
"endpoint_type": "ekm",
"key_type": "symmetric",
"algorithm": "AES256",
"raw_policy_enabled": false,
"policy": {
"basic": {
"clients": [
"abc@google.com"
],
"justification_required": true,
"justification_reason": [
"REASON_UNSPECIFIED",
"CUSTOMER_INITIATED_SUPPORT"
],
"attestation_zones": [
"zone1",
"zone2"
],
"attestation_project_ids": [
"project1",
"project2"
],
"attestation_instance_names": [
"instance1",
"instance2"
]
},
"rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n input.justificationReason = {\"REASON_UNSPECIFIED\",\"CUSTOMER_INITIATED_SUPPORT\",\"GOOGLE_INITIATED_SERVICE\",\"THIRD_PARTY_DATA_REQUEST\",\"GOOGLE_INITIATED_REVIEW\",\"CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_INITIATED_SYSTEM_OPERATION\",\"REASON_NOT_EXPECTED\",\"MODIFIED_CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n input.attestationZones = {\"us-east1a\"}[_]\r\n input.attestationProjectIDs = {\"project1\"}[_]\r\n input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n allowedClient\r\n allowedJustification\r\n allowAttestation\r\n}"
}
}
}
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Enable an EKM or EKM UDE Endpoint
Use POST with /v1/cckm/ekm/endpoints/{id}/enable to allow wrap or unwrap operation using the EKM or EKM UDE endpoint.
Syntax
curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>/enable' -X POST -H 'AUTHTOKEN' --compressed
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the EKM or EKM UDE Endpoint |
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization Token |
Example Request
curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test/enable' -X POST -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA1NzZkODgtMjFhNy00ZmY4LThmZWYtN2IyY2JlZWRkYjE4Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijg0M2I0Njc0LWJlZWQtNDFjNS04YjgxLWUyNzBhYzI1ZTU3ZiIsImlhdCI6MTYyNjE4MTEwNywiZXhwIjoxNjI2MTgxNDA3fQ.3nG8PoPEWOagovTpM8LVk90BxU-jgiVqaqMo0d1OcXA' --compressed
Example Response
{
"application/json": {
"id": "04f63144-940c-4c4f-8426-1917b54e0c33",
"uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2021-02-10T00:19:40.321138Z",
"name": "ekmendpoint_1",
"updatedAt": "2021-02-10T00:20:25.036189Z",
"keyURIHostname": "ciphertrust.mycompany.com",
"keyURI": "https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
"kekName": "ekmendpoint_1",
"kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
"meta": {
"size": "big",
"color": "blue"
},
"enabled": true,
"kekVersion": "1"
"cvm_required_for_encrypt": false,
"cvm_required_for_decrypt": false,
"endpoint_type": "ekm",
"key_type": "symmetric",
"algorithm": "AES256",
"raw_policy_enabled": false,
"policy": {
"basic": {
"clients": [
"abc@google.com"
],
"justification_required": true,
"justification_reason": [
"REASON_UNSPECIFIED",
"CUSTOMER_INITIATED_SUPPORT"
],
"attestation_zones": [
"zone1",
"zone2"
],
"attestation_project_ids": [
"project1",
"project2"
],
"attestation_instance_names": [
"instance1",
"instance2"
]
},
"rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n input.justificationReason = {\"REASON_UNSPECIFIED\",\"CUSTOMER_INITIATED_SUPPORT\",\"GOOGLE_INITIATED_SERVICE\",\"THIRD_PARTY_DATA_REQUEST\",\"GOOGLE_INITIATED_REVIEW\",\"CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_INITIATED_SYSTEM_OPERATION\",\"REASON_NOT_EXPECTED\",\"MODIFIED_CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n input.attestationZones = {\"us-east1a\"}[_]\r\n input.attestationProjectIDs = {\"project1\"}[_]\r\n input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n allowedClient\r\n allowedJustification\r\n allowAttestation\r\n}"
}
}
}
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Disable an EKM or EKM UDE Endpoint
Use POST with /v1/cckm/ekm/endpoints/{id}/disable to disallow wrap or unwrap operation using the EKM or EKM UDE endpoint. This is a way to temporarily suspend client operations with an endpoint without deleting it and its associated KEK.
Syntax
curl -k 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>/disable' -X POST -H 'AUTHTOKEN' --compressed
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the EKM or EKM UDE Endpoint |
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization Token |
Example Request
curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test/disable' -X POST -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA1NzZkODgtMjFhNy00ZmY4LThmZWYtN2IyY2JlZWRkYjE4Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijg0M2I0Njc0LWJlZWQtNDFjNS04YjgxLWUyNzBhYzI1ZTU3ZiIsImlhdCI6MTYyNjE4MTEwNywiZXhwIjoxNjI2MTgxNDA3fQ.3nG8PoPEWOagovTpM8LVk90BxU-jgiVqaqMo0d1OcXA' --compressed
Example Response
{
"application/json": {
"id": "04f63144-940c-4c4f-8426-1917b54e0c33",
"uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2021-02-10T00:19:40.321138Z",
"name": "ekmendpoint_1",
"updatedAt": "2021-02-10T00:20:25.036189Z",
"keyURIHostname": "ciphertrust.mycompany.com",
"keyURI": "https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
"kekName": "ekmendpoint_1",
"kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
"meta": {
"size": "big",
"color": "blue"
},
"enabled": true,
"kekVersion": "1"
"cvm_required_for_encrypt": false,
"cvm_required_for_decrypt": false,
"endpoint_type": "ekm",
"key_type": "symmetric",
"algorithm": "AES256",
"raw_policy_enabled": false,
"policy": {
"basic": {
"clients": [
"abc@google.com"
],
"justification_required": true,
"justification_reason": [
"REASON_UNSPECIFIED",
"CUSTOMER_INITIATED_SUPPORT"
],
"attestation_zones": [
"zone1",
"zone2"
],
"attestation_project_ids": [
"project1",
"project2"
],
"attestation_instance_names": [
"instance1",
"instance2"
]
},
"rego": "package example\r\n\r\ndefault allow = false\r\n\r\nallowedClient {\r\n input.client = {\"abc@google.com\"}[_]\r\n}\r\n\r\nallowedJustification {\r\n input.justificationReason = {\"REASON_UNSPECIFIED\",\"CUSTOMER_INITIATED_SUPPORT\",\"GOOGLE_INITIATED_SERVICE\",\"THIRD_PARTY_DATA_REQUEST\",\"GOOGLE_INITIATED_REVIEW\",\"CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_INITIATED_SYSTEM_OPERATION\",\"REASON_NOT_EXPECTED\",\"MODIFIED_CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\r\n}\r\n\r\ndefault allowAttestation = false\r\n\r\nallowAttestation {\r\n\tinput.attestationRequired = false\r\n}\r\n\r\nallowAttestation {\r\n input.attestationZones = {\"us-east1a\"}[_]\r\n input.attestationProjectIDs = {\"project1\"}[_]\r\n input.instanceNames = {\"instance1\"}[_]\r\n}\r\n\r\nallow {\r\n allowedClient\r\n allowedJustification\r\n allowAttestation\r\n}"
}
}
}
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
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="
}
}
