Your suggested change has been received. Thank you.

close

Suggest A Change

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

back

CCKM API

Google Cloud EKM APIs

search

Please Note:

Google Cloud EKM APIs

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

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.

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:

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

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

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

  4. 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:

  1. In case 1, the guarantee that the protected DEK/data is only accessible by a confidential VM.

  2. In case 2, the guarantee that data encrypted on-premise and migrated to the cloud will only be accessible by a confidential VM.

  3. In case 3, the guarantee that data retrieved from the cloud and decrypted, was originated in a confidential VM.

  4. In case 4, the guarantee is that the data is only decryptable when the KEK is accessible.

Google Cloud EKM API Endpoints on CipherTrust Manager

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

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

ParameterTypeDescription
AUTHTOKENstringAuthorization Token
namestringUnique name for EKM or EKM UDE Endpoint.
keyURIHostnamestringBase url hostname for KeyURI.
metaJSONOptional. Additional information associated with this endpoint.
cvm_required_for_decryptbooleanIs a confidential VM (and valid attestation) required for decryption. Default is false. Applicable for UDE Endpoint only.
cvm_required_for_encryptbooleanIs a confidential VM (and valid attestation) required for encryption. Default is false. Applicable for UDE Endpoint only.
endpoint_typestringEKM Endpoint type. Can be either "ekm" or "ekm-ude". Default is ekm.
key_typestringEKM Key type. For existing keys, this must match the supplied key. Options are either symmetric or asymmetric. Default is symmetric.
algorithmstringEKM 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_idstringID 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_enabledbooleanFlag 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.
policyJSONEKM Policy Attributes

Policy Parameters

Policy ParameterTypeDescription
regostringEKM Policy in rego format. Required field if raw_policy_enabled=true.
basicJSONEKM Policy in basic format. Required field if raw_policy_enabled=false.

Basic Format Policy Parameters

Basic Format Policy ParameterTypeDescription
clientsarrayAllowed Service Accounts. Required.
attestation_instance_namesarrayAllowed Instance Names. Applicable for UDE Endpoint only.
attestation_project_idsarrayAllowed Project IDs. Applicable for UDE Endpoint only.
attestation_zonesarrayAllowed zones. Applicable for UDE Endpoint only.
justification_reasonarrayJustification 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_requiredbooleanFlag 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 CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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

ParameterTypeDescription
AUTHTOKENstringAuthorization Token

Request Query Parameters

ParameterTypeDescription
idstringFilter the result based on EKM Endpoint ID.
namestringFilter the result based on EKM Endpoint name.
skipintegerThe index of the first resource to return. Equivalent to 'offset' in SQL.
limitintegerThe max number of resources to return. Equivalent to 'limit' in SQL.
key_typestringFilter the results based on EKM key type.
endpoint_typestringFilter the results based on EKM endpoint type, ekm or ekm-ude.
algorithmstringFilter 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 CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization 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 CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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

ParameterTypeDescription
idstringID of the EKM or EKM UDE Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token
keyURIHostnamestringBase url hostname for KeyURI.
metaJSONOptional. Additional information associated with this endpoint.
cvm_required_for_encryptbooleanIs a confidential VM (and valid attestation) required for encryption. Default is false. Applicable for UDE Endpoint only.
cvm_required_for_decryptbooleanIs a confidential VM (and valid attestation) required for decryption. Default is false. Applicable for UDE Endpoint only.
raw_policy_enabledbooleanFlag to denote if the sent policy is in raw format. Default is false.
policyJSONEKM Policy Attributes

Policy Parameters

Policy ParameterTypeDescription
regostringEKM Policy in rego format.
basicJSONEKM Policy in basic format.

Basic Format Policy Parameters

Basic Format Policy ParameterTypeDescription
clientsarrayAllowed Service Accounts. Required.
attestation_instance_namesarrayAllowed Instance Names. Applicable for UDE Endpoint only.
attestation_project_idsarrayAllowed Project IDs. Applicable for UDE Endpoint only.
attestation_zonesarrayAllowed zones. Applicable for UDE Endpoint only.
justification_reasonarrayJustification 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_requiredbooleanFlag 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 CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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

ParameterTypeDescription
idstringID of the EKM or EKM UDE Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization 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 CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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

ParameterTypeDescription
idstringID of the EKM or EKM UDE Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization 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 CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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

ParameterTypeDescription
idstringID of the EKM or EKM UDE Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token
clientsstringClients permitted to access the endpoint.
justificationReasonstringJustification reasons required in the request to wrap or unwrap with the endpoint.
attestationZonesstringSet param with Zones that should be allowed during UDE Attestation. Applicable only for UDE Endpoints.
attestationProjectIDsstringSet param with Project IDs that should be allowed during UDE Attestation. Applicable only for UDE Endpoints.
instanceNamesstringSet 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 CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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

ParameterTypeDescription
idstringID of the EKM or EKM UDE Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization 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 CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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

ParameterTypeDescription
idstringID of the EKM or EKM UDE Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization 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 CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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

ParameterTypeDescription
idstringID of the EKM or EKM UDE Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization 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 CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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.

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
ParameterTypeDescription
tlsRecordsstringSerialized message to begin a TLS handshake.
Response Elements
ElementTypeDescription
sessionContextstringInformation associated with the session including session ID.
tlsRecordsstringSerialized 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
ParameterTypeDescription
tlsRecordsstringResult from /v1/cckm/ekm/session/beginsession
sessionContextstringResult 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
ParameterTypeDescription
sessionContextstringResult from /v1/cckm/ekm/session/beginsession
offeredEvidenceTypeRecordsstringSet of attestation options the client can provide.
Response Elements
ElementTypeDescription
requiredEvidenceTypeRecordsstringSet 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
ParameterTypeDescription
sessionContextstringInformation associated with the session including session ID.
attestationEvidenceRecordsstringAttestion 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
ParameterTypeDescription
sessionContextstringInformation 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

ParameterTypeDescription
idstringID of the EKM UDE Endpoint

Request Parameters

ParameterTypeDescription
sessionContextstringSession context identifier.
tlsRecordsstringTLS records, base64 encoded.

Example Response

{
"status": 204
}

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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

ParameterTypeDescription
idstringID of the EKM UDE Endpoint

Request Parameters

ParameterTypeDescription
sessionContextstringSession context identifier.
tlsRecordsstringTLS records, base64 encoded.

Example Response

{
"status": 204
}

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer 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

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
datastringRequired. The signed data to be verified (base64 encoded). Must be no larger than 64KiB.
key_pathstringRequired. A unique, External-KMS-defined resource identifier for the key.
signaturestringRequired. The data signature (base64 encoded).
key_uri_prefixstringOptional data that, if specified, defines the full key URI.
additionalContextJSONMore 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

ParameterTypeDescription
accessReasonContextJSONOptional. Request that has an empty AccessReasonContext is a valid request.
reasonstringKey Access Justification reason. Required if Key Access Justification is enabled for GCP project.
fullResourceNamestringThe full resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See For a Cloud KMS CryptoKey resource, this includes the Cloud KMS Location associated with the resource.
isKeyHealthCheckbooleanOptional. Whether the request is a key health check that contains a canonical plaintext or its encryption instead of customer data.
relativeResourceNamestringOptional. The relative resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See This is a substring of the RequestContext's full_resource_name.

Example Response

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

Perform an Asymmetric Sign Operation

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

  • A JWT asserting that asymmetricsign operation is done by a legitimate User.

  • The base64 signature that needs to be signed.

  • Additional Context containing Key Access Justification details.

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization token
datastringRequired. The data to be signed (base64 encoded). Must be no larger than 64KiB.
key_pathstringRequired. A unique, External-KMS-defined resource identifier for the key.
key_uri_prefixstringOptional data that, if specified, defines the full key URI.
additionalContextJSONMore 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

ParameterTypeDescription
accessReasonContextJSONOptional. Request that has an empty AccessReasonContext is a valid request.
reasonstringKey Access Justification reason. Required if Key Access Justification is enabled for GCP project.
fullResourceNamestringThe full resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See For a Cloud KMS CryptoKey resource, this includes the Cloud KMS Location associated with the resource.
isKeyHealthCheckbooleanOptional. Whether the request is a key health check that contains a canonical plaintext or its encryption instead of customer data.
relativeResourceNamestringOptional. The relative resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See This is a substring of the RequestContext's full_resource_name.

Example Response

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

Get the Public Key from an EKM endpoint

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

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization token
key_pathstringRequired. A unique, External-KMS-defined resource identifier for the key.
key_uri_prefixstringOptional data that, if specified, defines the full key URI.
additionalContextJSONMore 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

ParameterTypeDescription
accessReasonContextJSONOptional. Request that has an empty AccessReasonContext is a valid request.
reasonstringKey Access Justification reason. Required if Key Access Justification is enabled for GCP project.
fullResourceNamestringThe full resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See For a Cloud KMS CryptoKey resource, this includes the Cloud KMS Location associated with the resource.
isKeyHealthCheckbooleanOptional. Whether the request is a key health check that contains a canonical plaintext or its encryption instead of customer data.
relativeResourceNamestringOptional. The relative resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See This is a substring of the RequestContext's full_resource_name.

Example Response

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

Wrap with an EKM or EKM UDE Endpoint

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

Specify the following details:

  • A JWT asserting that unwrap operation is done by legitimate User

  • The base64 blob that needs to be wrapped.

  • Additional Context containing Key Access Justification details.

Path Parameters

ParameterTypeDescription
idstringID of the EKM or EKM UDE Endpoint

Request Parameters

ParameterTypeDescription
GOOGLE_TOKENstringAuthorization Token
plaintextstringRequired. The data to be wrapped (base64 encoded). Must be no larger than 64KiB.
additionalAuthenticatedDatastringOptional data that, if specified, must also be provided during unwrap. The AAD must be no larger than 64KiB.
additionalContextJSONMore 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

ParameterTypeDescription
accessReasonContextJSONOptional. Request that has an empty AccessReasonContext is a valid request.
reasonstringKey Access Justification reason. Required if Key Access Justification is enabled for GCP project.
fullResourceNamestringThe full resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See For a Cloud KMS CryptoKey resource, this includes the Cloud KMS Location associated with the resource.
isKeyHealthCheckbooleanOptional. Whether the request is a key health check that contains a canonical plaintext or its encryption instead of customer data.
relativeResourceNamestringOptional. The relative resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See This is a substring of the RequestContext's full_resource_name.

Example Response

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

Unwrap with an EKM or EKM UDE Endpoint

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

Specify the following details:

  • A JWT asserting that unwrap operation is done by legitimate User

  • The base64 blob that needs to be wrapped.

  • Additional Context containing Key Access Justification details.

Path Parameters

ParameterTypeDescription
idstringID of the EKM or EKM UDE Endpoint

Request Parameters

ParameterTypeDescription
GOOGLE_TOKENstringAuthorization Token
additionalAuthenticatedDatastringMust match the data originally supplied in the wrap request.
additionalContextJSONMore context provided during the unwrap operation. Required if Key Access Justification is enabled for GCP project. See Unwrap additionalContext Parameters for allowed values.
wrappedBlobstringRequired. The wrapped data to be unwrapped, originally returned in the wrap request.

Unwrap additionalContext Parameters

ParameterTypeDescription
accessReasonContextJSONOptional. Request that has an empty AccessReasonContext is a valid request.
reasonstringKey Access Justification reason. Required if Key Access Justification is enabled for GCP project.
fullResourceNamestringOptional. The full resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See For a Cloud KMS CryptoKey resource, this includes the Cloud KMS Location associated with the resource.
isKeyHealthCheckbooleanOptional. Whether the request is a key health check that contains a canonical plaintext or its encryption instead of customer data.
relativeResourceNamestringOptional. The relative resource name for the GCP resource being directly wrapped by the KEK. This is also known as the Cloud KMS CryptoKey resource. See This is a substring of the RequestContext's full_resource_name.

Example Response

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