Your suggested change has been received. Thank you.

close

Suggest A Change

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

Thales Logo

All

  • All
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 CCKM 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, or to encrypt data using a symmetric key. In this scenario, Google Cloud KMS does not store the external key material.

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

Note

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

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

  • BigQuery

  • Compute Engine

All other Google CMEK integration services for Google Cloud EKM are not validated by Thales, but are expected to work and are supported. Consult Google EKM documentation for the full list of Google CMEK services for EKM. Only CMEK services integrated with Google Cloud EKM are supported with CCKM EKM endpoints.

These are "Hold Your Own Key" (HYOK) integrations, where you manage and control the base KEK inside of CCKM. Google Cloud has additional CMEK services that do not follow the HYOK model and do not integrate with EKM.

Google Cloud EKM API Endpoints on CipherTrust Manager

Create an EKM Endpoint

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

Syntax

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}' --compressed

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token
namestringUnique name for EKM Endpoint.
keyURIHostnamestringBase url hostname for KeyURI.
metaJSONOptional. Additional information associated with this Endpoint.

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiYjQ5NDY5ZjgtMDJhNi00ZTgxLTliMDEtNGU1MTk2MjA0NzIwIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijc2ZTc1N2JiLWJiYTgtNDJiNy04OTI1LWMwYWFmZTQ0NzNiMSIsImlhdCI6MTYyNjExODk4OCwiZXhwIjoxNjI2MTE5Mjg4fQ.gwvR6t2-E5DFLatL6CdGdJnphDlkHp1Rog9xUlz_DWs' -H 'Content-Type: application/json' --data-binary $'{\n  "name": "ekmEndpoint_1",\n  "keyURIHostname": "ciphertrust.mycompany.com",\n  "meta": {\n    "color": "blue",\n    "size": "big"\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"
        }
    }

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer errors

Refer to HTTP status codes for details.

Listing EKM Endpoints

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

Syntax

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

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token

Request Query Parameters

ParameterTypeDescription
idstringFilter the result based on EKM Endpoint ID.
namestringFilter the result based on EKM Endpoint name.
skipintegerThe index of the first resource to return. Equivalent to 'offset' in SQL.
limitintegerThe max number of resources to return. Equivalent to 'limit' in SQL.

Example Request

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

Example Response

{
    "application/json": {
        "skip": "0,",
        "limit": "10,",
        "total": "1,",
        "resources": [
            {
                "id": "04f63144-940c-4c4f-8426-1917b54e0c33",
                "uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
                "account": "kylo:kylo:admin:accounts:kylo",
                "application": "ncryptify:gemalto:admin:apps:kylo",
                "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
                "createdAt": "2021-02-10T00:19:40.321138Z",
                "name": "ekmendpoint_1",
                "updatedAt": "2021-02-10T00:20:25.036189Z",
                "keyURIHostname": "ciphertrust.mycompany.com",
                "keyURI": "https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
                "kekName": "ekmendpoint_1",
                "kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
                "meta": {
                    "size": "big",
                    "color": "blue"
                },
                "enabled": true,
                "kekVersion": "0"
            }
        ]
    }
}

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer errors

Refer to HTTP status codes for details.

Viewing Details for an EKM Endpoint

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

Syntax

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

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token

Example Request

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

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer errors

Refer to HTTP status codes for details.

Update An EKM Endpoint

Use PATCH with /v1/cckm/ekm/endpoints/{id} to update the endpoint's base hostname or meta data.

Syntax

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}' --compressed

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token
keyURIHostnamestringBase url hostname for KeyURI.
metaJSONOptional. Additional information associated with this endpoint.

Example Request

curl -k 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test' -X PATCH -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA5MjViMzktYzQ0OS00YWYzLWI0Y2UtOTJlYzkxODc1YTk2Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjhjYzAyNzhjLTIxODItNGRkZC1iNGZmLTYwYWMyNTgzYjVmZiIsImlhdCI6MTYyNjEyNDAzMiwiZXhwIjoxNjI2MTI0MzMyfQ.mPf1683qErNbtipKLPUKKShdmLwtx0XRD5rj2ft6UMI' -H 'Content-Type: application/json' --data-binary $'{\n  "keyURIHostname": "ciphertrust.newcompany.com"\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"
    }
}

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer errors

Refer to HTTP status codes for details.

Delete An EKM Endpoint

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

Syntax

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

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token

Example Request

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

Example Response

{
    "status": 204
}

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer errors

Refer to HTTP status codes for details.

List EKM Policies

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

Syntax

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

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token

Example Request

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

Example Response

{
    "text/plain": "package example default allow = false 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\",\n\"GOOGLE_INITIATED_REVIEW\",\"CUSTOMER_INITIATED_ACCESS\",\"GOOGLE_INITIATED_SYSTEM_OPERATION\",\"REASON_NOT_EXPECTED\",\"MODIFIED_CUSTOMER_INITIATED_ACCESS\"}[_] }\n"
}

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer errors

Refer to HTTP status codes for details.

Update EKM 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.

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>" }' --compressed

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token
clientsstringClients permitted to access the endpoint.
justificationReasonstringJustification reasons required in the request to wrap or unwrap with the endpoint.

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\"}[_]\n  input.justificationReason == {\"REASON_UNSPECIFIED\"}[_] }\n"
}

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer errors

Refer to HTTP status codes for details.

Rotate An EKM Endpoint

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

Syntax

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

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token

Example Request

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

Example Response

{
    "application/json": {
        "id": "04f63144-940c-4c4f-8426-1917b54e0c33",
        "uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
        "account": "kylo:kylo:admin:accounts:kylo",
        "application": "ncryptify:gemalto:admin:apps:kylo",
        "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
        "createdAt": "2021-02-10T00:19:40.321138Z",
        "name": "ekmendpoint_1",
        "updatedAt": "2021-02-10T00:20:25.036189Z",
        "keyURIHostname": "ciphertrust.mycompany.com",
        "keyURI": "https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "kekName": "ekmendpoint_1",
        "kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "meta": {
            "size": "big",
            "color": "blue"
        },
        "enabled": true,
        "kekVersion": "1"
    }
}

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer errors

Refer to HTTP status codes for details.

Enable an EKM Endpoint

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

Syntax

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

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token

Example Request

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

Example Response

{
    "application/json": {
        "id": "04f63144-940c-4c4f-8426-1917b54e0c33",
        "uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
        "account": "kylo:kylo:admin:accounts:kylo",
        "application": "ncryptify:gemalto:admin:apps:kylo",
        "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
        "createdAt": "2021-02-10T00:19:40.321138Z",
        "name": "ekmendpoint_1",
        "updatedAt": "2021-02-10T00:20:25.036189Z",
        "keyURIHostname": "ciphertrust.mycompany.com",
        "keyURI": "https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "kekName": "ekmendpoint_1",
        "kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "meta": {
            "size": "big",
            "color": "blue"
        },
        "enabled": true,
        "kekVersion": "0"
    }
}

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer errors

Refer to HTTP status codes for details.

Disable an EKM Endpoint

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

Syntax

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

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
AUTHTOKENstringAuthorization Token

Example Request

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

Example Response

{
    "application/json": {
        "id": "04f63144-940c-4c4f-8426-1917b54e0c33",
        "uri": "kylo:kylo:cckm:kacls-ekm:ekmendpoint-1",
        "account": "kylo:kylo:admin:accounts:kylo",
        "application": "ncryptify:gemalto:admin:apps:kylo",
        "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
        "createdAt": "2021-02-10T00:19:40.321138Z",
        "name": "ekmendpoint_1",
        "updatedAt": "2021-02-10T00:20:25.036189Z",
        "keyURIHostname": "ciphertrust.mycompany.com",
        "keyURI": "https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "kekName": "ekmendpoint_1",
        "kekID": "626fdff442284cf1ad4b9030c21bfcddb2004e1cfd2b420da7c33d7f50e78c91",
        "meta": {
            "size": "big",
            "color": "blue"
        },
        "enabled": false,
        "kekVersion": "0"
    }
}

Response Codes

Response CodeDescription
2xxSuccess
4xxClient errors
5xxServer errors

Refer to HTTP status codes for details.

Wrap with an EKM Endpoint

Use POST with /v1/cckm/ekm/endpoints/{id}:wrap to perform a wrap operation with the EKM endpoint. 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.

Syntax

curl --location --request POST 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>:wrap' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <GOOGLE_TOKEN>' \
--data-raw '{
"plaintext": "SGVsbG8gISBob3cgYXJlIHlvdSA/",
        "additionalContext":
        {
            "accessReasonContext":
            {
                "reason":" CUSTOMER_INITIATED_ACCESS"
            },
        "RelativeResourceName": "projects/demo-proj/locations/us/keyRings/demo-key-ring/cryptoKeys/demo-1/cryptoKeyVersions/16"
        }
}'

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

ParameterTypeDescription
GOOGLE_TOKENstringAuthorization Token
plaintextstringRequired. The data to be wrapped (base64 encoded). Must be no larger than 64KiB.
additionalAuthenticatedDatastringOptional data that, if specified, must also be provided during unwrap. The AAD must be no larger than 64KiB.
additionalContextJSONMore context provided during Wrap operation. Required if Key Access Justification is enabled for GCP project. See Wrap additionalContext Parameters for allowed values.

Wrap additionalContext parameters

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

Example Request

curl --location --request POST 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test:wrap' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA1NzZkODgtMjFhNy00ZmY4LThmZWYtN2IyY2JlZWRkYjE4Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijg0M2I0Njc0LWJlZWQtNDFjNS04YjgxLWUyNzBhYzI1ZTU3ZiIsImlhdCI6MTYyNjE4MTEwNywiZXhwIjoxNjI2MTgxNDA3fQ.3nG8PoPEWOagovTpM8LVk90BxU-jgiVqaqMo0d1OcXA' \
--data-raw '{
"plaintext": "SGVsbG8gISBob3cgYXJlIHlvdSA/",
        "additionalContext":
        {
            "accessReasonContext":
            {
                "reason":" CUSTOMER_INITIATED_ACCESS"
            },
        "RelativeResourceName": "projects/demo-proj/locations/us/keyRings/demo-key-ring/cryptoKeys/demo-1/cryptoKeyVersions/16"
        }
}'

Example Response

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

Unwrap with an EKM Endpoint

Use POST with /v1/cckm/ekm/endpoints/{id}:unwrap to perform an unwrap operation with the EKM endpoint. 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.

Syntax

curl --location --request POST 'https://<ciphertrust-fqdn>/api/v1/cckm/ekm/endpoints/<ekm-endpoint-id>:unwrap' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <GOOGLE_TOKEN>' \
--data-raw '{   
    "wrappedBlob":"ZXlKM2NtRndjR1ZrWDJKc2IySWlPaUpGZVdKVmFYRnZSbGxIV0RsSGIwRXJXRUpuY214alR6WlZkRlpOTkcxemIwY3JWRkp0UW5WcVpWQnJaeUlzSW10bGExOXBaQ0k2SWpBeU5HRTRZV1ppTldSa01qUTFaakU1TlRabU1UTTBNemcwTm1Wa05XSTVZakUwWW1Wak9UTTBabU0yTkdWaE9Ea3pPVE5pWkdJMll6aGxZek16T0RraUxDSnJaV3RmZG1WeWMybHZiaUk2SWpBaUxDSmhaR1JwZEdsdmJtRnNYMkYxZEdobGJuUnBZMkYwWldSZlpHRjBZU0k2Ym5Wc2JDd2lZV0ZrWDJWdVptOXlZMlZrSWpwMGNuVmxmUT09",
    "additionalContext":
     {
           "accessReasonContext":
           {
                "reason":" CUSTOMER_INITIATED_ACCESS"
           },
           "RelativeResourceName": "projects/demo-proj/locations/us/keyRings/demo-key-ring/cryptoKeys/demo-1/cryptoKeyVersions/16"
     }
}'

Path Parameters

ParameterTypeDescription
idstringID of the EKM Endpoint

Request Parameters

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

Unwrap additionalContext Parameters

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

Example Request

curl --location --request POST 'https://ciphertrust.mycompany.com/api/v1/cckm/ekm/endpoints/ekm-test:unwrap' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1MzU4Y2QyMi1lODE5LTRmYjUtODg1Ni02YTI5NTUyYTJhMGMiLCJzdWIiOiJsb2NhbHwwYmIyZWY0ZC1kMGViLTQzNDktOGNkYS1kNDZlZWIyN2Y3NWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODA1NzZkODgtMjFhNy00ZmY4LThmZWYtN2IyY2JlZWRkYjE4Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6Ijg0M2I0Njc0LWJlZWQtNDFjNS04YjgxLWUyNzBhYzI1ZTU3ZiIsImlhdCI6MTYyNjE4MTEwNywiZXhwIjoxNjI2MTgxNDA3fQ.3nG8PoPEWOagovTpM8LVk90BxU-jgiVqaqMo0d1OcXA' \
--data-raw '{   
    "wrappedBlob":"ZXlKM2NtRndjR1ZrWDJKc2IySWlPaUpGZVdKVmFYRnZSbGxIV0RsSGIwRXJXRUpuY214alR6WlZkRlpOTkcxemIwY3JWRkp0UW5WcVpWQnJaeUlzSW10bGExOXBaQ0k2SWpBeU5HRTRZV1ppTldSa01qUTFaakU1TlRabU1UTTBNemcwTm1Wa05XSTVZakUwWW1Wak9UTTBabU0yTkdWaE9Ea3pPVE5pWkdJMll6aGxZek16T0RraUxDSnJaV3RmZG1WeWMybHZiaUk2SWpBaUxDSmhaR1JwZEdsdmJtRnNYMkYxZEdobGJuUnBZMkYwWldSZlpHRjBZU0k2Ym5Wc2JDd2lZV0ZrWDJWdVptOXlZMlZrSWpwMGNuVmxmUT09",
    "additionalContext":
     {
           "accessReasonContext":
           {
                "reason":" CUSTOMER_INITIATED_ACCESS"
           },
           "RelativeResourceName": "projects/demo-proj/locations/us/keyRings/demo-key-ring/cryptoKeys/demo-1/cryptoKeyVersions/16"
     }
}'

On this page