Creating DKE Endpoints
Use the post /v1/cckm/microsoft/dke/endpoints API to create a DKE endpoint for the Microsoft Double Key Encryption service.
You can create a new key encryption key (KEK) or specify an existing KEK for the getkey and decrypt operations.
The existing KEK is applicable for migrating DKE integration from another CipherTrust Manager deployment.
Specify the following details.
Unique name for the endpoint
Base hostname for the key URI
Note
In the Microsoft Azure application, go to the API Permissions section and configure the Directory.Read.All permission. Ensure that the
Typefor this permission is Application.
Syntax
curl -k '<CCKM IP address>/api/v1/cckm/microsoft/dke/endpoints' -H 'Authorization: Bearer AUTHTOKEN' -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary $'{\n "name": "<unique_name_dke_endpoint>",\n "description": "<dke_endpoint_description>",\n "key_uri_hostname": "<base_url_hostname_for_key_uri>",\n "algorithm": "<dke_key_algorithm>",\n "enable_success_audit_event": <true|false>,\n "meta": {\n "color": "blue",\n "size": "big"\n },\n "authorization_params": {\n "valid_issuers": [\n "<a_valid_issuer_for_dke_endpts>/"\n ],\n "authorization_type": "email",\n "email_authz_params": {\n "authorized_email_addresses": [\n "<authorized_email_address>",\n "<authorized_email_address>"\n ]\n }\n }\n}' --compressed
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| auth_tenants | string | List of IDs of authorized tenants for the DKE endpoint. |
| key_uri_hostname | string | Base URL hostname for KeyURI. If you changed the web interface port within CipherTrust Manager from the default port of 443 to another port, ensure to add that same port number when configuring url hostname for KeyURI by specifying the new port number along with the url hostname. For example, example.com:8443. For more information changing the web interface port, refer to Support for Changing the Default Port of Web Interface Setting. |
| name | string | Unique name for the endpoint. |
| algorithm | string | DKE key algorithm. The only option currently supported is RSA_DECRYPT_OAEP_2048_SHA256, which is the default value. |
| description | string | Description for the endpoint. |
| enable_success_audit_event | boolean | Flag to denote whether audit recording of successful operations for the DKE endpoint is enabled or disabled. Default value is true. |
| enabled | boolean | Flag to denote whether endpoint is enabled. Default value is true. |
| 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 a asymmetric key type. The asymmetric key must have Sign and Verify usage masks. In addition, this key must not be exportable or deletable. A DKE 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 the migration of a DKE endpoint from one CipherTrust Manager deployment to another. When creating a new DKE 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. |
| key_type | string | DKE key type. The only option currently supported is asymmetric. |
| meta | JSON | Additional information associated with this endpoint. |
Note
To change the web interface port within CipherTrust Manager from the default port of 443 to another port, specify the new port number along URL hostname for KeyURI when configuring key_uri_hostname. For example, https://example.com:8443.
DKE Authorization Parameters
| Parameter | Type | Description |
|---|---|---|
| authorization_type | string | Authorization type for DKE key: email and role. |
| email_authz_params | string | Parameters for email-based authorization. Required field, if authorization_type is email. |
| authorized_email_addresses | string | Allowed email addresses. Required field, if authorization_type is email. |
| role_authz_params | string | Parameters for role-based authorization. Required field, if authorization_type is set to role. |
| authorized_roles | string | Allowed roles in active directory. Required field, if authorization_type is set to role. |
| valid_issuers | string | A valid issuer for the DKE endpoint. Currently, only one issuer is supported. For example, https://sts.windows.net/azure tenant ID/. This issuer must match the issuer within the JWT that the CCKM receives. |
Note
The use of wildcards '*' and '?' are supported for email addresses. The following are examples of supported wildcard formats:
abc*@gmail.com: supports any email that starts with abc and ends with "@gmail.com".
abc@?.com: supports any email that starts with abc, contains "@" followed by at least one character and ends with ".com".
abc@?.?*: supports any email that starts with abc, contains "@" followed by at least one character, followed by the dot character (.), and ends with at least one character.
?*@gmail.com: supports any email that starts with at least one character and ends with "@gmail.com".
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/microsoft/dke/endpoints' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI1ZTc3Y2Q3NC0wMmVhLTRhNzYtODIzMi1hNDY4YTg1MGQwM2UiLCJzdWIiOiJsb2NhbHw0ODMyZDM4ZS04YzdhLTRiMjYtYTc5Ni1kNjk3NWQyOTg2ZGIiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJjbGllbnRfdHlwZSI6InVucmVnaXN0ZXJlZCIsImRvbWFpbl9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImdyb3VwcyI6WyJhZG1pbiJdLCJzaWQiOiIzMGJiZTYxNS1hNWQzLTQwNzAtYTNjYi01NDA0Y2YzMmE5OTYiLCJ6b25lX2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIn0sImp3dGlkIjoiOTE4YzFhZmEtYzY2My00Yzg0LWE3MDAtNzIzZWUwMzMxNzdjIiwiaWF0IjoxNjkyOTIzNzY5LCJleHAiOjE2OTI5MjQwNjl9.Dx43G2HQHnhzcHq6eXrdOfWCCMVW-j-JTMTSXorjEf8' -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary $'{\n "name": "my dke endpoint 7",\n "description": "demo dke endpoint 7",\n "key_uri_hostname": "dke.thales.com",\n "algorithm": "RSA_DECRYPT_OAEP_2048_SHA256",\n "enable_success_audit_event": "true",\n "meta": {\n "color": "red",\n "size": "big"\n },\n "authorization_params": {\n "valid_issuers": [\n "https://sts.windows.net/9c99431e-b513-44be-a7d9-e7b500002d4b/"\n ],\n "authorization_type": "email",\n "email_authz_params": {\n "authorized_email_addresses": [\n "richard-roe@example.com",\n "gopa-desai@example.com"\n ]\n }\n }\n}' --compressed
Example Response
{
"id": "8fbd67ea-3925-4361-9326-c73a84ae872c",
"uri": "kylo:kylo:cckm:dke-endpoint:8fbd67ea-3925-4361-9326-c73a84ae872c",
"account": "kylo:kylo:admin:accounts:kylo",
"createdAt": "2023-06-23T02:58:31.192776Z",
"updatedAt": "2023-06-23T02:58:31.192776Z",
"name": "TestDKEEndpoint_001",
"description": "demo dke endpoint 1",
"key_uri_hostname": "dke.thales.com",
"key_uri": "https://dke.thales.com/api/v1/cckm/microsoft/dke-data-plane/endpoints/8fbd67ea-3925-4361-9326-c73a84ae872c/keys/ks-e998720b0e8e4ccc9ecf6a6e125ccce16356ba90b31540478a4d23fed4216203",
"kek_name": "ks-e998720b0e8e4ccc9ecf6a6e125ccce16356ba90b31540478a4d23fed4216203",
"kek_id": "e998720b0e8e4ccc9ecf6a6e125ccce16356ba90b31540478a4d23fed4216203",
"kek_uuid": "efc5544d-53bd-42ab-b582-d6985458f37c",
"meta": {
"color": "blue",
"size": "big"
},
"kek_version": "0",
"key_type": "asymmetric",
"algorithm": "RSA_DECRYPT_OAEP_2048_SHA256",
"enable_success_audit_event": true,
"auth_tenants": [
"95180635-b494-4f57-b9ba-a250aeac741f"
],
"auto_rotate": false,
"status": "Enabled"
}
The sample output shows that the DKE endpoint with the name of my dke endpoint 7 and an ID of f222ffdf-80e1-4fd5-8f17-1b60a26dba5d along with other specified parameters is created.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
