Automatic Cloud Key Discovery
This section describes how to create and run job configurations to add KMS containers for different clouds. A KMS container job automatically detects the KMS containers based on the Azure Cloud connection and adds them to the CipherTrust Cloud Key Manager.
Creating Add KMS Container Job Configuration
Use the post /v1/scheduler/job-configs API to create a new add KMS container job configuration.
Syntax
curl -k '<IP>/api/v1/scheduler/job-configs' -H 'Authorization: Bearer AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n "name": "<configuration name>",\n "operation": "<operation>",\n "description": "<description>",\n "run_at": "<time when you want to run the job>"\n "cckm_add_containers_params": {<KMS container addition parameters>}\n}' --compressed
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| name | string | Name of the job configuration. |
| operation | string | Type of operation that can be scheduled. For KMS container addition, specify cckm_add_containers. Also, specify cckm_add_containers_params. |
| run_at | string | Time when a job will run. Specify this parameter using the cron expression format: "* * * * *". |
| cckm_add_containers_params | JSON | Parameters required for configuring an add KMS container job. Refer to Add KMS Container Parameters for details. |
| description | string | Description for the job configuration. |
| disabled | boolean | Flag to disable job configuration. Set to true to disable the job. |
| end_date | string | End date for a job configuration. The job becomes inactive at this time. Specify the value in the RFC3339 format. |
| start_date | string | Time to start a job configuration. The job becomes active at this time. Specify the value in the RFC3339 format. |
Add KMS Container Parameters
| Parameter | Type | Description |
|---|---|---|
| cloud_name | string | Name of the cloud. The cloud name can be gcp and AzureCloud. |
| connection | string | Resource ID of the connection added to the CipherTrust Data Security Platform Service. |
| acls | array of JSONs | Default permissions to be granted to users and groups on the KMS containers to be added. Refer to ACLs for details. |
| discover_only | boolean | Whether to only discover the KMS containers. Set to false to discover the containers and add them to CCKM. The default setting is true, that is, the containers will be discovered but not added to CCKM. |
| enable_success_audit_event | boolean | (Applicable to GCP cloud) Whether to enable audit recording of successful operations within an external key store. The default and recommended value is false. Enabling the auditing (that is, setting to true) can affect the performance. |
ACLs
| Parameter | Type | Description |
|---|---|---|
| actions | array of strings | List of permitted actions. Refer to Actions for the supported actions and details. |
| group | string | Name of the user group to be granted permissions. User ID and group are mutually exclusive. Specify either. |
| permit | boolean | Whether to permit users to perform specific operations. Set true to permit, false to deny. |
| user_id | string | ID of the user to be granted permissions. User ID and group are mutually exclusive. Specify either. |
Actions
The following table lists the accepted values:
| APIs | Actions Required | Description |
|---|---|---|
| Create Key | keycreate | Permission to create keys. |
| Update Key | keyupdate | Permission to update keys. |
| Synchronize Key | keysynchronize | Permission to synchronize keys. |
| View Key | view | Permission to view keys. |
| Destroy Key | keydestroy | Permission to destroy keys. |
| Cancel Destroy Key | keycanceldestroy | Permission to cancel key destroy. |
| Upload Key | keyupload | Permission to upload keys. |
| Create Report | reportcreate | Permission to create reports. |
| Delete Report | reportdelete | Permission to delete reports. |
| View Report | reportview | Permission to view reports. |
| Download Report | reportdownload | Permission to download reports. |
Example Request
curl -k 'https://127.0.0.1/api/v1/scheduler/job-configs' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiIzMTNhMDc2ZS1kOTU4LTRjZTktYTY3Ni1lNDYyNzI1YjFhYTciLCJzdWIiOiJsb2NhbHxkNWM5Njk4Zi0xZmQ2LTRiN2MtODBhZi05YTU4ZmE0OGQzNWQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiMmI0MjFhYWItNDNiNy00NzdmLTgzYjUtOTA3M2U1NGZhN2FiIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjE0YTY2YjQ0LTk3ODAtNGZlYS05MzI5LWM4YWY5NjAyNzU2MSIsImlhdCI6MTU5NTU3NTgyNywiZXhwIjoxNTk1NTc2MTI3fQ.tAZ3qiehHuvV9q8aq3a9s4stbIcVy-OHeoVnBaSlV0I' -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary $'{\n "name": "add_gcp_containers",\n "operation": "cckm_add_containers",\n "description": "This is to add GCP KMS containers",\n "run_at": "30 * * * *",\n "cckm_add_containers_params": {\n "cloud_name": "gcp",\n "connection": "8d854be7-e897-47d1-8016-44c35a2bf797",\n "enable_success_audit_event": false,\n "acls": [\n {\n "group": "CCKM Users",\n "actions": [\n "view", "keysynchronize", "keycreate"\n ],\n "permit": true\n }\n ]\n }\n}' --compressed
Example Response
{
"id": "71ec2e33-8669-4e8e-8f1d-23079b6c5e23",
"uri": "kylo:kylo:scheduler:job_configs:71ec2e33-8669-4e8e-8f1d-23079b6c5e23",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2023-07-26T07:22:11.356276061Z",
"name": "add_gcp_containers",
"updatedAt": "2023-07-26T07:22:11.356276061Z",
"description": "This is to add GCP KMS containers",
"operation": "cckm_add_containers",
"run_at": "30 * * * *",
"disabled": false,
"job_config_params": {
"acls": [
{
"actions": [
"view",
"keysynchronize",
"keycreate"
],
"group": "CCKM Users",
"permit": true
}
],
"cloud_name": "gcp",
"connection": "8d854be7-e897-47d1-8016-44c35a2bf797",
"enable_success_audit_event": false
}
}
The sample output shows that a job configuration is created and a unique ID (71ec2e33-8669-4e8e-8f1d-23079b6c5e23) for the job configuration is returned.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Updating Job Configurations
Use the patch /v1/scheduler/job-configs/{id} API to update an existing job configuration. You can modify job configuration parameters and cckm_add_containers_params parameters.
Syntax
curl -k '<IP>/api/v1/scheduler/job-configs/{id}' -X PATCH -H 'Authorization: Bearer AUTHTOKEN' -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary $'{\n "description": "<new job description>",\n"cckm_add_containers_params":{\n "acls": [\n {\n "group": <group>",\n "actions": [\n "<action1>"\n],\n "<action2>": <true|false>\n}\n],\n "connection": "<new cloud connection>",\n "discover_only": [true|false],\n "enable_success_audit_event": [true|false]\n },\n "run_at": "0 1 * * *"\n}' --compressed
Here, {id} represents the ID of the job configuration.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| description | String | Description of the job configuration. |
| cckm_add_containers_params | JSON | Add the KMS container parameters. Refer to Add KMS Container Parameters for details. |
Example Request
curl -k 'https://127.0.0.1/api/v1/scheduler/job-configs/71ec2e33-8669-4e8e-8f1d-23079b6c5e23' -X PATCH -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJiYzc5M2E4ZC00YWVhLTRlM2EtYWRiYy05YmRlMDhjYjE5MDYiLCJzdWIiOiJsb2NhbHw2MjgyZDZkNC0wZGI5LTRmZmEtYjc4Ny0xNzY0NTFiMmViNGQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiODI1OWFhZTEtNjkzMi00NzE2LTlhMjItNzAzZWFlNzc2MWUzIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjU4OWU2NjBjLWU1MzgtNGZmOS04MWQzLWNiMWI3MWYzZDNhYiIsImlhdCI6MTU5NDcyNjE3OCwiZXhwIjoxNTk0NzI2NDc4fQ.xzoksM7OjCC65lPg3keDS3iGnz4C6ZHFUgNlAHl7dVQ' -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary $'{\n "description": "automatic add GCP KMS containers job",\n "cckm_add_containers_params": {\n "acls": [\n {\n "actions": ["keysynchronize"],\n "group": "CCKM Users",\n "permit": false\n }\n ],\n "connection": "8d854be7-e897-47d1-8016-44c35a2bf797",\n "enable_success_audit_event": false\n },\n "run_at": "0 1 * * *"\n}' --compressed
Example Response
{
"id": "71ec2e33-8669-4e8e-8f1d-23079b6c5e23",
"uri": "kylo:kylo:scheduler:job_configs:71ec2e33-8669-4e8e-8f1d-23079b6c5e23",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2023-07-26T07:22:11.356276Z",
"name": "add_gcp_containers",
"updatedAt": "2023-07-26T07:57:47.257752002Z",
"description": "automatic add GCP KMS containers job",
"operation": "cckm_add_containers",
"run_at": "0 1 * * *",
"disabled": false,
"job_config_params": {
"acls": [
{
"actions": [
"view",
"keycreate"
],
"group": "CCKM Users",
"permit": true
}
],
"cloud_name": "gcp",
"connection": "8d854be7-e897-47d1-8016-44c35a2bf797",
"enable_success_audit_event": true
}
}
The sample output shows that keysynchronize is now the only permitted action.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
