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

How to Run a Demo

Create Policies, Configurations, Registration Token through REST API from API Playground

search

Please Note:

Create Policies, Configurations, Registration Token through REST API from API Playground

Everything that can be configured and managed through the CipherTrust Manager GUI can also be configured and managed through the REST API of the CipherTrust Manager. This section demonstrates how to use the API playground of the CipherTrust Manager to create and configure policies and configuration.

Note

This section does not list all the APIs of Application Data Protection, for the exhaustive list, refer to the Data Protection section of the CipherTrust Manager's API Playground.

Acquire authorization token

  1. Open the CipherTrust Manager URL in a browser.

  2. Click the API & CLI Documentation link. The API playground is displayed.

  3. At the top right, click Authenticate.

  4. Enter username and password.

  5. Click POST.

On successful token generation, the remaining token expiry time in seconds is displayed. Two new buttons, Clear Credentials and Re Authenticate, are also displayed at the top right.

Note

This acquires an API token and prefills it in the playground examples. The token expires in 300 seconds (5 minutes). When it expires, use this tool again to acquire a new token.

Create character sets

Use the post /v1/data-protection/character-sets API to create a character set.

Sample Request


{
    "name": "DPGAlphaNum",
    "range": [
        "0030-0039",
        "0041-005A",
        "0061-007A"
    ],
    "encoding": "UTF-8"
}

Sample Response


{
"id": "e3984c47-8096-4d43-8c60-3250148a4f26",
"uri": "kylo:kylo:adp-central-configuration:characterSet:dpgalphanum-e3984c47-8096-4d43-8c60-3250148a4f26",
"account": "kylo:kylo:admin:accounts:kylo",
"createdAt": "2021-10-11T11:05:13.19053792Z",
"updatedAt": "2021-10-11T11:05:13.178142065Z",
"name": "DPGAlphaNum",
"description": "",
"alphabet": "",
"encoding": "UTF-8",
"predefined": false,
"range": [
    "0030-0039",
    "0041-005A",
    "0061-007A"
        ]
}

The sample output shows that the character set named DPGAlphaNum is created. A unique ID (e3984c47-8096-4d43-8c60-3250148a4f26) for the character set is returned.

Create user set

Use the post /v1/data-protection/user-sets API to create a user set.

Sample Request


{
"name": "plainttextuserset",
"description": "user set description",
"users": [
    "paymentclient",
    "refundclient"
        ]
}

Sample Response


{
"id": "87a057b9-80de-4683-8ca3-10b659f7a3c3",
"uri": "kylo:kylo:adp-central-configuration:userSet:plainttextuserset-87a057b9-80de-4683-8ca3-10b659f7a3c3",
"account": "kylo:kylo:admin:accounts:kylo",
"createdAt": "2022-06-10T08:48:14.08801166Z",
"updatedAt": "2022-06-10T08:48:14.08801166Z",
"created_by": "local|2f84c4d9-2b05-46eb-aab4-ab7d6f7c6e23",
"name": "plainttextuserset",
"description": "user set description",
"users": [
    "paymentclient",
    "refundclient"
    ],
"version": 1
}

The sample shows that the User Set, plainttextuserset is created. A unique ID, 87a057b9-80de-4683-8ca3-10b659f7a3c3 for the User Set is returned. The user set contains two users named, paymentclient and refundclient.

Create masking format

Use the post /v1/data-protection/masking-formats API to create masking format. Application Data Protection allows you to create static masking format and dynamic masking format. Refer to Managing Masking Formats for details.

Sample Request


{
  "name": "preserver_first2_last2",
  "starting_characters": 2,
  "ending_characters": 2,
  "static": true
}

Sample Response


{
    "id": "f1d96fd7-4267-4761-975a-c6394d34b2e3",
    "uri": "kylo:kylo:adp-central-configuration:maskingFormat:preserver-first2-last2-f1d96fd7-4267-4761-975a-c6394d34b2e3",
    "account": "kylo:kylo:admin:accounts:kylo",
    "createdAt": "2023-09-11T10:24:01.543226833Z",
    "updatedAt": "2023-09-11T10:24:01.543226833Z",
    "created_by": "local|cf07cf1e-3502-443f-af98-5143beaf689c",
    "name": "preserver_first2_last2",
    "description": "",
    "starting_characters": 2,
    "ending_characters": 2,
    "show": false,
    "mask_char": "",
    "static": true,
    "predefined": false
}

The sample shows that a static masking format, named preserver_first2_last2 is created. A unique ID, f1d96fd7-4267-4761-975a-c6394d34b2e3 for the static masking format is returned.

Create access policy

Use the post /v1/data-protection/access-policies API to create an access policy.

Sample Request


{
"name": "cc_access_policy",
"description": "access policy description",
"default_reveal_type": "Error Replacement Value",
"default_error_replacement_value": "143001",
"user_set_policy": [
    {
    "user_set_id": "87a057b9-80de-4683-8ca3-10b659f7a3c3",
    "reveal_type": "Plaintext"
    }
]
}

Sample Response


{
"id": "2c751d09-4633-49da-85d3-2bc17ab38b22",
"uri": "kylo:kylo:adp-central-configuration:accessPolicy:cc-access-policy-2c751d09-4633-49da-85d3-2bc17ab38b22",
"account": "kylo:kylo:admin:accounts:kylo",
"createdAt": "2022-06-10T08:51:15.457315354Z",
"updatedAt": "2022-06-10T08:51:15.475233808Z",
"created_by": "local|2f84c4d9-2b05-46eb-aab4-ab7d6f7c6e23",
"name": "cc_access_policy",
"description": "access policy description",
"default_reveal_type": "Error Replacement Value",
"default_error_replacement_value": "143001",
"default_masking_format_id": null,
"user_set_policy": [
    {
    "user_set_id": "87a057b9-80de-4683-8ca3-10b659f7a3c3",
    "reveal_type": "Plaintext",
    "error_replacement_value": null,
    "masking_format_id": null
    }
],
"version": 1
}

The sample shows that a access policy, named cc_access_policy is created. A unique ID, 2c751d09-4633-49da-85d3-2bc17ab38b22 for the Access Policy is returned. Here, the reveal format for the User Set (87a057b9-80de-4683-8ca3-10b659f7a3c3), created in previous step, is configured to display Plaintext.

Create protection policies

Use the post /v1/data-protection/protection-policies API. When creating a protection policy, ensure that the key (used to perform cryptographic operation) is created on the CipherTrust Manager. For this demo, a key named dpgKey is used to perform Format Preserving Encryption. This key is marked exportable on the CipherTrust Manager.

Sample Request to add protection policy for employee name


{
    "name": "cvv_ProtectionPolicy",
    "key": "dpgKey",    
    "algorithm": "FPE/FF1v2/UNICODE",
    "character_set_id": "e3984c47-8096-4d43-8c60-3250148a4f26",
    "access_policy_name": "cc_access_policy",
    "masking_format_id": "324571f9-e5cc-4f02-ad6b-dc4006b69f09",
    "use_external_versioning": false,
    "disable_versioning": false
}

Sample Response to add protection policy for employee name


{
    "id": "258ed787-fd9a-4665-9fd8-323a622c3c63",
    "uri": "kylo:kylo:adp-central-configuration:protectionPolicy:cvv-protectionpolicy-258ed787-fd9a-4665-9fd8-323a622c3c63",
    "account": "kylo:kylo:admin:accounts:kylo",
    "createdAt": "2023-09-11T10:19:25.88195048Z",
    "updatedAt": "2023-09-11T10:19:25.872984083Z",
    "name": "cvv_ProtectionPolicy",
    "version": 1,
    "latest_version": true,
    "description": "",
    "key": "dpgKey",
    "iv": "",
    "tweak": "",
    "tweak_algorithm": "",
    "character_set_id": "e3984c47-8096-4d43-8c60-3250148a4f26",
    "masking_format_id": "324571f9-e5cc-4f02-ad6b-dc4006b69f09",
    "algorithm": "FPE/FF1v2/UNICODE",
    "use_external_versioning": false,
    "disable_versioning": false,
    "access_policy_name": "cc_access_policy"
}

Sample Request to add protection policy for Credit Card (CC)


{
    "name": "CC_ProtectionPolicy",
    "key": "dpgKey",
    "algorithm": "FPE/AES/UNICODE",
    "character_set_id": "e3984c47-8096-4d43-8c60-3250148a4f26",
    "access_policy_name": "cc_access_policy",
    "masking_format_id": "324571f9-e5cc-4f02-ad6b-dc4006b69f09",
    "use_external_versioning": false,
    "disable_versioning": false
}

Sample Response to add protection policy for Credit Card (CC)


{
    "id": "58f9ee28-1ada-8c09-927a-1da432az6870",
    "uri": "kylo:kylo:adp-central-configuration:protection policy:CC_ProtectionPolicy-58f9ee28-1ada-8c09-927a-1da432az6870",
    "account": "kylo:kylo:admin:accounts:kylo",
    "createdAt": "2023-09-11T10:19:25.88195048Z",
    "updatedAt": "2023-09-11T10:19:25.872984083Z",
    "name": "CC_ProtectionPolicy",
    "version": 1,
    "latest_version": true,
    "description": "",
    "key": "dpgKey",
    "iv": "",
    "tweak": "",
    "tweak_algorithm": "",
    "algorithm": "FPE/AES/UNICODE",
    "use_external_versioning": false,
    "disable_versioning": false,
    "access_policy_name": "cc_access_policy"
}

The sample output shows that two protection policies named cvv_ProtectionPolicy and CC_ProtectionPolicy are created. A unique ID for each protection policy is returned. These policies will govern the crypto operations on DPG.

Create DPG policy

Use the post /v1/data-protection/dpg-policies API to create a DPG policy.

Sample Request


{
    "name":"CC_Policy",
    "description":"",
    "proxy_config":[
        {
            "api_url":"/api/sample/resource/{id}",           
            "json_request_post_tokens":[
            {
                "name":"creditCard.[*].CCNumber",
                "operation":"protect",
                "protection_policy":"CC_ProtectionPolicy"
            },
            {
                "name":"creditCard.[*].cvv",
                "operation":"protect",
                "protection_policy":"cvv_ProtectionPolicy"
            }
            ],           
            "json_response_get_tokens":[
            {
                "name":"creditCard.[*].cvv",
                "operation":"reveal",
                "protection_policy":"cvv_ProtectionPolicy"              
            }
            ]
        }
    ]
}

Sample Response


{
    "id": "0759023b-67e4-40a0-b039-3fdbb07431ee",
    "uri": "kylo:kylo:adp-central-configuration:dpg_policies:dpgpolicy-0759023b-67e4-40a0-b039-3fdbb07431ee",
    "account": "kylo:kylo:admin:accounts:kylo",
    "createdAt": "2021-10-11T11:29:01.162744712Z",
    "updatedAt": "2021-10-11T11:29:01.151752881Z",
    "name": "CC_Policy",
    "version": 1,
    "description": "",
    "proxy_config": [
        {
            "id": "f0e344d3-e0e9-4c2a-bcdf-76a0504b6add",
            "uri": "kylo:kylo:adp-central-configuration:dpg_api_urls:f0e344d3-e0e9-4c2a-bcdf-76a0504b6add",
            "account": "kylo:kylo:admin:accounts:kylo",
            "createdAt": "2021-10-11T11:29:01.196202803Z",
            "updatedAt": "2021-10-11T11:29:01.184829115Z",
            "dpg_policy_id": "0759023b-67e4-40a0-b039-3fdbb07431ee",
            "api_url": "/api/sample/resource",
            "destination_url": "",
            "json_request_post_tokens": [
                {
                    "name":"ssn",
                    "operation":"protect",
                    "protection_policy":"ssn_ProtectionPolicy"
                },
                {
                    "name":"creditCard.[*].cvv",
                    "operation":"protect",
                    "protection_policy":"cvv_ProtectionPolicy"
                }
            ],              
            "json_request_get_tokens": null,
            "json_response_get_tokens": [
                {
                    "name":"creditCard.[*].cvv",
                    "operation":"reveal",
                    "protection_policy":"cvv_ProtectionPolicy"              
                }
            ]       
        }
    ]
}

The sample output shows that the DPG policy named, CC_Policy is created. A unique ID (0759023b-67e4-40a0-b039-3fdbb07431ee) for the DPG policy is returned. The DPG policy uses the protection policies (created in the previous step) to protect/reveal data. While revealing the data, DPG also uses the access policies (configured while creating protection policy) to display the output to the application users.

Tip

For DPG, the access policy can be configured while defining an application or creating protection policy. If both the methods are used, the precedence is given to the access policy associated with the protection policy.

Create client profile

Use the post /v1/data-protection/client-profiles API from API playground to create a client profile.

Note

The Common Name (csr_cn) must be same as the key owner.

Sample Request


{
    "name": "CC_profile",
    "nae_iface_port": 9000,
    "app_connector_type": "DPG",
    "policy_id": "0759023b-67e4-40a0-b039-3fdbb07431ee",
    "lifetime": "30d",
    "cert_duration": 730,
    "max_clients": 200,
    "ca_id": "51941790-40af-4880-a6c0-5b75956196bc",
    "csr_parameters": {
    "csr_cn": "admin",
    "csr_country": "",
    "csr_state": "",
    "csr_city": "",
    "csr_org_name": "",
    "csr_org_unit": "",
    "csr_email": ""
    },
    "configurations": {
    "symmetric_key_cache_enabled": true,
    "verify_ssl_certificate": false,
    "syslog_server_ip": "",
    "syslog_server_port": 514,
    "syslog_server_protocol": "tcp_ok",
    "syslog_no_of_retries": 3,
    "syslog_retry_interval": 1,
    "syslog_retry_limit": 2,
    "use_persistent_connections": true,
    "size_of_connection_pool": 300,
    "load_balancing_algorithm": "round-robin",
    "connection_idle_timeout": 600000,
    "connection_retry_interval": 600000,
    "cluster_synchronization_delay": 170,
    "cert_file_location": "",
    "credentials_encrypted": false,
    "asymmetric_key_cache_enabled": false,
    "persistent_cache_enabled": false,
    "persistent_cache_directory": "",
    "persistent_cache_expiry_keys": 43200,
    "persistent_cache_max_size": 100,
    "log_level": "INFO",
    "log_file": "",
    "log_rotation": "Daily",
    "log_size_limit": "100k",
    "log_max_backup_index": 10,
    "log_type": "Console",
    "maximum_idle_connection": 10000,
    "maximum_idle_connection_per_host": 10000,
    "dial_timeout": 10,
    "dial_keep_alive": 10,
    "key_non_exportable_policy": true,
    "symmetric_key_cache_expiry": 43200,
    "connection_timeout": 60000,
    "connection_read_timeout": 7000,
    "heartbeat_interval": 300,
    "heartbeat_timeout_count": -1,
    "tls_to_appserver": {
        "tls_skip_verify": true,
        "tls_enabled": false
    },
    "auth_method_used": {
            "scheme_name": "Basic"
    }
    }
}

Sample Response


{
    "id": "6c5d6156-e991-4ba1-b57b-8bfc480e6109",
    "uri": "kylo:kylo:adp-central-configuration:clientProfile:dpg-profile-6c5d6156-e991-4ba1-b57b-8bfc480e6109",
    "account": "kylo:kylo:admin:accounts:kylo",
    "createdAt": "2021-10-11T11:34:11.356503159Z",
    "updatedAt": "2021-10-11T11:34:11.356503159Z",
    "name": "CC_profile",
    "nae_iface_port": 9000,
    "owner": "local|e9b1d00b-4ada-419d-a409-a196b058ac53",
    "reg_token": "YZyiw0yUcuQDtPRJEtdukDjX50kSppc5qqpRq0CrBHujDt9HslA8M20bkgQzBD6g",
    "app_connector_type": "DPG",
    "csr_parameters": {
        "csr_cn": "admin"
    },
    "configurations": {
        "symmetric_key_cache_enabled": true,
        "asymmetric_key_cache_enabled": false,
        "symmetric_key_cache_expiry": 43200,
        "persistent_cache_enabled": false,
        "persistent_cache_expiry_keys": 43200,
        "persistent_cache_max_size": 100,
        "verify_ssl_certificate": false,
        "use_persistent_connections": true,
        "size_of_connection_pool": 300,
        "load_balancing_algorithm": "round-robin",
        "connection_timeout": 60000,
        "connection_read_timeout": 7000,
        "connection_idle_timeout": 600000,
        "connection_retry_interval": 600000,
        "cluster_synchronization_delay": 170,
        "credentials_encrypted": false,
        "log_level": "INFO",
        "log_rotation": "Daily",
        "log_size_limit": "100k",
        "log_max_backup_index": 10,
        "log_type": "Console",
        "key_non_exportable_policy": true,
        "maximum_idle_connection": 10000,
        "maximum_idle_connection_per_host": 10000,
        "dial_timeout": 10,
        "dial_keep_alive": 10,
        "heartbeat_interval": 300,
        "heartbeat_timeout_count": -1,
        "tls_to_appserver": {
            "tls_skip_verify": true,
            "tls_enabled": false
        },
        "auth_method_used": {
            "scheme_name": "Basic"
        },
        "cert_file_location": "",
        "log_file": "",
        "syslog_server_ip": "",
        "syslog_server_port": 514,
        "syslog_server_protocol": "tcp_ok",
        "syslog_no_of_retries": 3,
        "syslog_retry_interval": 1,
        "syslog_retry_limit": 2,
        "persistent_cache_directory": ""
    },
    "policy_id": "0759023b-67e4-40a0-b039-3fdbb07431ee",
    "ca_id": "51941790-40af-4880-a6c0-5b75956196bc"
}

The sample output shows that the client profile named CC_profile is created. A unique ID (6c5d6156-e991-4ba1-b57b-8bfc480e6109) for the client profile is returned. When a client profile is created, a reg_token (YZyiw0yUcuQDtPRJEtdukDjX50kSppc5qqpRq0CrBHujDt9HslA8M20bkgQzBD6g) is returned. The client uses this reg_token to register it on the CipherTrust Manager.

On this page