Your suggested change has been received. Thank you.

close

Suggest A Change

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

Thales Logo
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.

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.

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

Create an EKM or EKM UDE Endpoint

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

Specify the following required details:

  • Unique name for the endpoint.

  • Base hostname for the Key URi

  • Policy attributes in rego or basic format, including allowed service accounts.

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

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

Syntax with policy in basic format

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

Syntax with policy in rego format

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

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token
name string Unique name for EKM or EKM UDE Endpoint.
keyURIHostname string Base url hostname for KeyURI.
meta JSON Optional. Additional information associated with this endpoint.
cvm_required_for_decrypt boolean Is a confidential VM (and valid attestation) required for decryption. Default is false. Applicable for UDE Endpoint only.
cvm_required_for_encrypt boolean Is a confidential VM (and valid attestation) required for encryption. Default is false. Applicable for UDE Endpoint only.
endpoint_type string EKM Endpoint type. Can be either "ekm" or "ekm-ude". Default is ekm.
key_type string EKM Key type. For existing keys, this must match the supplied key. Options are either symmetric or asymmetric. Default is symmetric.
algorithm string EKM Key Algorithm. For existing keys, this must match the supplied key. Default is AES256. Supported values are AES256, RSA_SIGN_PSS_2048_SHA256, RSA_SIGN_PSS_3072_SHA256, RSA_SIGN_PSS_4096_SHA256, RSA_SIGN_PSS_4096_SHA512, RSA_SIGN_PKCS1_2048_SHA256, RSA_SIGN_PKCS1_3072_SHA256, RSA_SIGN_PKCS1_4096_SHA256, RSA_SIGN_PKCS1_4096_SHA512, EC_SIGN_P256_SHA256,EC_SIGN_P384_SHA384
existing_key_id string Identifier to be used to find the latest version of an existing CipherTrust Manager key. This identifier can be the ID of any version or the name of a CipherTrust Manager key. This key is either a symmetric or an asymmetric key type. The symmetric key must have Encrypt, Decrypt, Wrap, and Unwrap usage masks while the asymmetric key must have sign and verify usage masks. In addition, this key must not be exportable or deletable. An EKM endpoint will be created using the latest version of this key. If the identifier is not supplied, a new CipherTrust Manager key will be created. This identifier is applicable to migrating an EKM endpoint from one CipherTrust Manager deployment to another. When creating a new EKM endpoint using an existing CipherTrust Manager key in the new deployment, CCKM uses this identifier to associate all of the existing versions of a CipherTrust Manager key to the new endpoint.
raw_policy_enabled boolean Flag to denote if the sent policy is in raw format. Default is false. EKM Policy in basic format is required if raw_policy_enabled=false.
policy JSON EKM Policy Attributes

Policy Parameters

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

Basic Format Policy Parameters

Basic Format Policy Parameter Type Description
clients array Allowed Service Accounts. Required.
attestation_instance_names array Allowed Instance Names. Applicable for UDE Endpoint only.
attestation_project_ids array Allowed Project IDs. Applicable for UDE Endpoint only.
attestation_zones array Allowed zones. Applicable for UDE Endpoint only.
justification_reason array Justification reason can't be empty when justification_required is set to true. Allowed Key Access justification reasons. Options:
• REASON_UNSPECIFIED
• CUSTOMER_INITIATED_SUPPORT
• GOOGLE_INITIATED_SERVICE
• THIRD_PARTY_DATA_REQUEST
• GOOGLE_INITIATED_REVIEW
• CUSTOMER_INITIATED_ACCESS
•GOOGLE_INITIATED_SYSTEM_OPERATION
• REASON_NOT_EXPECTED
• MODIFIED_CUSTOMER_INITIATED_ACCESS
• GOOGLE_RESPONSE_TO_PRODUCTION_ALERT
justification_required boolean Flag to denote if key access justification should be enforced. Default is false.

Example Request

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

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

List EKM or EKM UDE Endpoints

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

Syntax

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

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Request Query Parameters

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

Example Request

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

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

Viewing Details for an EKM or EKM UDE Endpoint

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

Syntax

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

Path Parameters

Parameter Type Description
id string ID of the EKM Endpoint

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Example Request

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

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

Update An EKM or EKM UDE Endpoint

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

Syntax with policy in basic format

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

Syntax with policy in rego format

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

Path Parameters

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

Request Parameters

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

Policy Parameters

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

Basic Format Policy Parameters

Basic Format Policy Parameter Type Description
clients array Allowed Service Accounts. Required.
attestation_instance_names array Allowed Instance Names. Applicable for UDE Endpoint only.
attestation_project_ids array Allowed Project IDs. Applicable for UDE Endpoint only.
attestation_zones array Allowed zones. Applicable for UDE Endpoint only.
justification_reason array Justification reason can't be empty when justification_required is set to true. Allowed Key Access justification reasons. Options:
• REASON_UNSPECIFIED
• CUSTOMER_INITIATED_SUPPORT
• GOOGLE_INITIATED_SERVICE
• THIRD_PARTY_DATA_REQUEST
• GOOGLE_INITIATED_REVIEW
• CUSTOMER_INITIATED_ACCESS
•GOOGLE_INITIATED_SYSTEM_OPERATION
• REASON_NOT_EXPECTED
• MODIFIED_CUSTOMER_INITIATED_ACCESS
• GOOGLE_RESPONSE_TO_PRODUCTION_ALERT
justification_required boolean Flag to denote if key access justification should be enforced. Default is false.

Example Request

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

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

Delete An EKM or EKM UDE Endpoint

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

Syntax

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

Path Parameters

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

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Example Request

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

Example Response

{
    "status": 204
}

Response Codes

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

Refer to HTTP status codes for details.

List EKM or EKM UDE Policies

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

Syntax

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

Path Parameters

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

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Example Request

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

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

Update EKM or EKM UDE Policies

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

Syntax

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

Path Parameters

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

Request Parameters

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

Example Request

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

Example Response

{
    "text/plain": "package example default allow = false allow {\n  input.clients == {\"abc@yahoo.com\", \"abc@google.com\", \"abc@msn.com\"}[_]\n  input.justificationReason == {\"REASON_UNSPECIFIED\",\"CUSTOMER_INITIATED_SUPPORT\",\"GOOGLE_INITIATED_SERVICE\",\"THIRD_PARTY_DATA_REQUEST\",\"GOOGLE_INITIATED_REVIEW\",\"CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_INITIATED_SYSTEM_OPERATION\",\"REASON_NOT_EXPECTED\",\"MODIFIED_CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_RESPONSE_TO_PRODUCTION_ALERT\"}[_]\n}\n"
}

Response Codes

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

Refer to HTTP status codes for details.

Rotate An EKM or EKM UDE Endpoint

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

Syntax

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

Path Parameters

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

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Example Request

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

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

Enable an EKM or EKM UDE Endpoint

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

Syntax

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

Path Parameters

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

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Example Request

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

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

Disable an EKM or EKM UDE Endpoint

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

Syntax

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

Path Parameters

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

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Example Request

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

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

Get Information about EKM Software

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

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

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization token

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

EKM UDE Session

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

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

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

Begin an EKM UDE Session

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

Request Parameters
Parameter Type Description
tlsRecords string Serialized message to begin a TLS handshake.
Response Elements
Element Type Description
sessionContext string Information associated with the session including session ID.
tlsRecords string Serialized response.

Complete the EKM UDE Session Handshake

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

Request Parameters
Parameter Type Description
tlsRecords string Result from /v1/cckm/ekm/session/beginsession
sessionContext string Result from /v1/cckm/ekm/session/beginsession
Response Elements

Empty JSON object.

Negotiate Attestation for an EKM UDE Session

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

Request Parameters
Parameter Type Description
sessionContext string Result from /v1/cckm/ekm/session/beginsession
offeredEvidenceTypeRecords string Set of attestation options the client can provide.
Response Elements
Element Type Description
requiredEvidenceTypeRecords string Set of attestation options the server requires.

Finalize an EKM UDE Session

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

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

Empty JSON object.

End an EKM UDE Session

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

Request Parameters
Parameter Type Description
sessionContext string Information associated with the session including session ID.
Response Elements

Empty JSON object.

Perform a Confidential Wrap with an EKM UDE endpoint

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

Path Parameters

Parameter Type Description
id string ID of the EKM UDE Endpoint

Request Parameters

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

Example Response

{
"status": 204
}

Response Codes

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

Refer to HTTP status codes for details.

Perform a Confidential Unwrap with an EKM UDE Endpoint

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

Path Parameters

Parameter Type Description
id string ID of the EKM UDE Endpoint

Request Parameters

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

Example Response

{
"status": 204
}

Response Codes

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

Refer to HTTP status codes for details.

Perform an Asymmetric Signature Verification Operation

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

The request contains:

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

  • The base64 signature that needs to be verified.

  • Additional Context containing Key Access Justification details.

Path Parameters

Parameter Type Description
id string ID of the EKM Endpoint

Request Parameters

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

Verify additionalContext parameters

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

Example Response

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

Perform an Asymmetric Sign Operation

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

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

  • The base64 signature that needs to be signed.

  • Additional Context containing Key Access Justification details.

Path Parameters

Parameter Type Description
id string ID of the EKM Endpoint

Request Parameters

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

Sign additionalContext parameters

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

Example Response

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

Get the Public Key from an EKM endpoint

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

Path Parameters

Parameter Type Description
id string ID of the EKM Endpoint

Request Parameters

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

GetPublicKey additionalContext parameters

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

Example Response

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

Wrap with an EKM or EKM UDE Endpoint

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

Specify the following details:

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

  • The base64 blob that needs to be wrapped.

  • Additional Context containing Key Access Justification details.

Path Parameters

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

Request Parameters

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

Wrap additionalContext parameters

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

Example Response

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

Unwrap with an EKM or EKM UDE Endpoint

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

Specify the following details:

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

  • The base64 blob that needs to be wrapped.

  • Additional Context containing Key Access Justification details.

Path Parameters

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

Request Parameters

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

Unwrap additionalContext Parameters

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

Example Response

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

Google Cloud EKM Cryptospace APIs

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

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

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

As part of creating a cryptospace in CCKM, you define a default Key Access Justification (KAJ) policy to apply to it in addition to other required parameters. Keys created in a given cryptospace inherit the cryptospace’s default policy. For more information about the required parameters, see Create an EKM Cryptospace.

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

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

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

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

Create an EKM Cryptospace

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

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

Specify the following required details for the cryptospace:

  • Cryptospace name

  • Hostname

  • Cryptospace type

  • GCP Project ID

  • Indicate whether the policy is in a raw format

  • Indicate whether cryptospace is blocked

  • Policy attributes in rego or basic format including the allowed service accounts

  • Attestation parameter for encrypt (applicable only if type is ekm-ude)

  • Attestation parameter for decrypt (applicable only if type is ekm-ude)

  • List of service accounts and permissions for these service accounts

  • Location of the cryptospace

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

Syntax with policy in basic format

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

Syntax with policy in rego format

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

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token
name string Name of a cryptospace. The name must be unique in a domain.
hostname string Base url hostname for Ciphertrust Manager.
type string There are two types of cryptospaces. One for EKM endpoints (ekm) and another for EKM UDE endpoints (ekm-ude). The default is ekm.
project_id string The project ID of the Google Cloud project to be associated with the given cryptospace.
meta object Additional information associated with the given cryptospace.
blocked boolean This field indicates whether the cryptospace is blocked. The default is false.
raw_policy_enabled boolean Flag to denote whether the sent policy is in raw format. The default is false. Cryptospace Policy in a basic format is required if raw_policy_enabled=false.
policy object Cryptospace Key Access Justification (KAJ) Policy attributes. Endpoints in a cryptospace are to inherit the cryptospace's policy. EKM endpoint in a cryptospace can have its own policy as well.
location string Location of a cryptospace.
description string Description of a cryptospace.
permissions object List of service accounts and permissions. Service account used to call EKM cryptospace APIs. Service account is a string. List of permissions assigned to a service account. This list is an array. Options:
• CREATE_KEY
• DESTROY_KEY
• WRAP
• UNWRAP
• GET_PUBLIC_KEY
• ASYMMETRIC_SIGN
• GET_INFO

Policy Parameters

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

Basic Format Policy Parameters

Basic Format Policy Parameter Type Description
clients array Allowed Service Accounts. Required.
attestation_instance_names array Allowed Instance Names. Applicable for UDE Endpoint only.
attestation_project_ids array Allowed Project IDs. Applicable for UDE Endpoint only.
attestation_zones array Allowed zones. Applicable for UDE Endpoint only.
justification_reason array Justification reason cannot be empty when justification_required is set to true. Allowed Key Access justification reasons. Options:
• REASON_UNSPECIFIED,
• CUSTOMER_INITIATED_SUPPORT,
• GOOGLE_INITIATED_SERVICE,
• THIRD_PARTY_DATA_REQUEST,
• GOOGLE_INITIATED_REVIEW,
• CUSTOMER_INITIATED_ACCESS
•GOOGLE_INITIATED_SYSTEM_OPERATION,
• REASON_NOT_EXPECTED
• MODIFIED_CUSTOMER_INITIATED_ACCESS,
• GOOGLE_RESPONSE_TO_PRODUCTION_ALERT
justification_required boolean Flag to denote if key access justification should be enforced. The default is false.

Example Request

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

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

List EKM Cryptospaces

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

Syntax

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

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Request Query Parameters

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

Example Request

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

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

View Details of an EKM Cryptospace

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

Syntax

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

Path Parameters

Parameter Type Description
id string ID of the EKM cryptospace.

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Example Request

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

Example Response

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

Response Codes

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

Refer to HTTP status codes for details.

Update an EKM Cryptospace

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

Syntax

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

Path Parameters

Parameter Type Description
id string ID of the EKM cryptospace.

Request Parameters

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

Policy Parameters

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

Basic Format Policy Parameters

Basic Format Policy Parameter Type Description
clients array Allowed Service Accounts. Required.
attestation_instance_names array Allowed Instance Names. Applicable for UDE Endpoint only.
attestation_project_ids array Allowed Project IDs. Applicable for UDE Endpoint only.
attestation_zones array Allowed zones. Applicable for UDE Endpoint only.
justification_reason array Justification reason can't be empty when justification_required is set to true. Allowed Key Access justification reasons. Options:
• REASON_UNSPECIFIED,
• CUSTOMER_INITIATED_SUPPORT,
• GOOGLE_INITIATED_SERVICE,
• THIRD_PARTY_DATA_REQUEST,
• GOOGLE_INITIATED_REVIEW,
• CUSTOMER_INITIATED_ACCESS
•GOOGLE_INITIATED_SYSTEM_OPERATION,
• REASON_NOT_EXPECTED
• MODIFIED_CUSTOMER_INITIATED_ACCESS,
• GOOGLE_RESPONSE_TO_PRODUCTION_ALERT
justification_required boolean Flag to denote if key access justification should be enforced. Default is false.

Example Request

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

Example Response

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

}

Response Codes

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

Refer to HTTP status codes for details.

Delete an EKM Cryptospace

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

Syntax

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

Path Parameters

Parameter Type Description
id string ID of a cryptospace.

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Example Request

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

Example Response

{
    "status": 204
}

Response Codes

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

Refer to HTTP status codes for details.

Block an EKM Cryptospace

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

Syntax

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

Path Parameters

Parameter Type Description
id string ID of a cryptospace.

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Example Request

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

Example Response

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

}

Response Codes

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

Refer to HTTP status codes for details.

Unblock an EKM Cryptospace

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

Syntax

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

Path Parameters

Parameter Type Description
id string ID of a cryptospace.

Request Parameters

Parameter Type Description
AUTHTOKEN string Authorization Token

Example Request

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

Example Response

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

}

Response Codes

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

Refer to HTTP status codes for details.

Required User Permissions

This section provides the complete list of permissions required by a CipherTrust Manager user to perform operations on Google Cloud EKM resources using CCKM.

For managing EKM endpoints that do not reside in a cryptospace, a user must belong to CCKM Admin group and Key User group to perform any operation (create ekm, list ekm, get ekm, update ekm, delete ekm, get policy, update policy, rotate ekm, enable ekm, and disable ekm).

Ensure to configure the appropriate ACLs within the Google Cloud project in CCKM after giving these permissions to a user or custom group.

This section provides the complete list of permissions required by a CipherTrust Manager user to perform operations on EKM cryptospace endpoints using CCKM.

Operation Required Permissions ACLs
read ekm ReadEKMEndpoint
ReadEKMPolicy		 cryptospaceekmview
enable ekm ReadEKMEndpoint
ReadEKMPolicy
UpdateEKMCryptospaceEndpoint		 cryptospaceekmenable
disable ekm ReadEKMEndpoint
ReadEKMPolicy
UpdateEKMCryptospaceEndpoint		 cryptospaceekmdisable

This section provides the complete list of permissions required by a CipherTrust Manager user to perform operations on EKM cryptospaces using CCKM.

Operation Required Permissions ACLs
Create ReadEKMCryptospace
ReadEKMCryptospacePolicy
CreateEKMCryptospace		 cryptospacecreate
list ReadEKMCryptospace cryptospaceview
get ReadEKMCryptospace cryptospaceview
update ReadEKMCryptospace
ReadEKMCryptospacePolicy
PermissionUpdateEKMCryptospace		 cryptospaceupdate
delete ReadEKMCryptospace
DeleteEKMCryptospace		 cryptospacedelete
block BlockEKMCryptospace cryptospaceblock
unblock UnBlockEKMCryptospace cryptospaceunblock