CT-VL Tokenization REST APIs
The CipherTrust Vaultless Tokenization API consists of:
tokenize- A POST call that tokenizes data. A user submits sensitive data, the CipherTrust Vaultless Tokenization Server returns a token. The token is then stored in the production database.detokenize- A POST call that detokenizes data. A user submits a token to the CipherTrust Vaultless Tokenization Server and the actual data is returned detokenized. Permission settings for that user dynamically specify the appropriate data mask.log- Changes the log level. Four different log levels (error, info, debug, and trace) can be selected. Chose ‘error’ or ‘info’ for normal operation, or ‘debug’ when instructed to do so by Thales eSecurity support.
Using the APIs
To enable tokenization, you do not have to change your database schema, because CipherTrust Vaultless Tokenization preserves the format of your data. However, you must change your application code.
When a user makes a request to tokenize or detokenize, the username and password must be provided. This is a part of a REST request. The username/password is validated by either the AD/LDAP server or CT-VL, depending on where the user is defined.
Note
The data passed to and from the CipherTrust Vaultless Tokenization Server; user name, tokenization group name, tokens, and sensitive data, is case-sensitive, and the application code that passes data to CT-VL must be aware of this.
Tokenization input can be a normal text format.
The maximum input data size for CT-VL Tokenization REST APIs is given below:
| API | Maximum Input Data Size |
|---|---|
| Tokenization and Detokenization | 128 KB |
| Batch Tokenization and Detokenization | 1.25 MB (maximum records: 5000, maximum individual record size: 128 KB) |
Create a Token
Description
Use the tokenize endpoint to encrypt a data string to a token using format-preserving encryption (FPE or FF1).
Tokenize Endpoint Details
| Data | Description |
|---|---|
| HTTP Request | https://IP_Address/vts/rest/v2.0/tokenize |
| Method | POST |
| CT-VL IP Address | The IP address of the CT-VL instance to access with the API call. |
| Response Format | JSON |
| Required Authentication | A valid user name and password must be passed as an argument. The values are case sensitive. |
Tokenize Parameters
The parameters for tokenize endpoint are described in the table below:
| Parameter | Required | Type | Description |
|---|---|---|---|
| tokengroup | Y | string | Defines a group name space in the configuration database. For example, let’s say you are a credit card company and you want the CT-VL to support three departments supporting Store1, Store2, and Store3. You want employees in these departments to have access to data for those respective stores. Two actions are required: • The application code must specify a different tokengroup parameter in the POST calls for each group supported (example: Store1, Store2, and Store3). The tokengroup parameter is case sensitive. • The CT-VL GUI administrator must create token groups that match the tokengroup parameter names used in the application code. If you do not support multiple token groups, then tokengroup will always be the same value. Example value: store1 |
| data | Y | string | The data string to tokenize. The argument considers case and is limited to 128KiBs Example value: 1432445695309134 |
| tokentemplate | Y | string | CT-VL GUI Administrator-defined name for a group of properties that define tokenization operation. Properties include the token group to which the template applies, the tokenization format (date, FPE or FPE with Luhn check, or FF1 or FF1 with Luhn check, or Random (lookup) or Random with Luhn check), number of leftmost or rightmost characters to not tokenize, whether you wish to never detokenize a tokenized entry, the character set used for tokenization, and an optional prefix for tokens. Example value: Credit Card |
| returnData | N | string | Tokenization requests can return the plaintext string together with the encrypted data in the response. To enable, add the "returnData" parameter and set it to true. |
Tokenize Response Parameters
The tokenize endpoint response parameters, their types, and corresponding descriptions are listed in the table below:
| Parameter | Type | Description |
|---|---|---|
| token | string | Token for the sensitive data. Example value: 2134234509874567 |
| status | string | •Succeeded (if request succeeded) •Error (if request failed) |
| reason | string | If status is Error a reason is displayed. Otherwise the reason is omitted. |
| data | string | f returnData in the request is set to true, contains the plaintext string for the encrypted data. |
Create Token CURL Example
Note
If you use the --tlsv1.2 CURL Command syntax option, you must use CURL version 7.34 or higher.
Example Request
curl -k -X POST -u Donald_Duckmiller:Panda45# -d'{"tokengroup" :
"ctsUsers-t" , "data" : "9453677629008564", "tokentemplate" :
"ctsUsersTemplate" }' https://192.168.118.140/vts/rest/v2.0/tokenize
The user name (Donald_Duckmiller) and tokengroup (ctsUsers-t) are case sensitive.
Example Response
{"token":"CC-0332335756020172","status":"Succeed"}
If FPE-luhn, FF1-luhn, or Random-luhn is selected in the Change Token Template page of the CT-VL GUI, the data must pass a Luhn check or tokenization will fail with the error message: "status":"error","reason":"Luhn check failed for input data."
Tokenizing Multiple Data Items
Up to 5,000 data items can be tokenized in a single curl command by submitting a JSON array in the REST request. For example, to tokenize four data items you might enter the following in a postcnn.txt file:
Example Request
cat postccn.txt
[{"tokengroup" : "ctsUsers-t" , "data" : "9453677629008564",
"tokentemplate" : "ctsUsersTemplate" },{"tokengroup" : "ctsUserst"
, "data" : "9453677629008564", "tokentemplate" :
"ctsUsersTemplate" },{"tokengroup" : "ctsUsers-t" , "data" :
"9453677629008564", "tokentemplate" : "ctsUsersTemplate"
},{"tokengroup" : "ctsUsers-t" , "data" : "9453677629008564",
"tokentemplate" : "ctsUsersTemplate" }]
curl -k -X POST -u Donald_Duckmiller:Panda45# --data-binary
@postccn.txt https://192.168.118.140/vts/rest/v2.0/tokenize
Warning
Newlines are NOT allowed in the input.
Example Response
[{"token":" 9465976792116170","status":"Succeed"},
{"token":" 9465976792116170","status":"Succeed"},
{"token":" 9465976792116170","status":"Succeed"},
{"token":" 9465976792116170","status":"Succeed"}]
The tokenized data is returned in the CURL Command syntax response, in order of submission.
Get Detokenize Resource Data
Get detokenized data from a resource.
Detokenize Endpoint Details
| Data | Description |
|---|---|
| HTTP Request | https://IP_Address/vts/rest/v2.0/detokenize |
| Method | POST |
| CT-VL IP Address | The IP address of the CT-VL instance to access with the API call. |
| Response Format | JSON |
| Required Authentication | A valid user name and password must be passed as an argument. The values are case sensitive. |
Detokenize Request Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| token | Y | string | The token to detokenize. token is case sensitive. Example value: 6029541314537206 |
| tokengroup | Y | string | Defines a group name space in the configuration database. For example, let’s say you are a credit card company and you want the CT-VL to support three departments supporting Store1, Store2, and Store3. You want employees in these departments to have access to data for those respective stores. Two actions are required: • The application code must specify a different tokengroup parameter in the POST calls for each group supported (example: Store1, Store2, and Store3). The tokengroup parameter is casesensitive. • The CT-VL GUI administrator must create token groups that match the tokengroup parameter names used in the application code. If you do not support multiple token groups, then tokengroup will always be the same value. Example value: store1 |
| tokentemplate | Y | string | CT-VL GUI Administrator-defined name for a group of properties that define tokenization operation. Properties include the token group to which the template applies, the tokenization format (date, FPE or FPE with Luhn check, or FF1 or FF1 with Luhn check, or Random (lookup) or Random with Luhn check), number of leftmost or rightmost characters to not tokenize, whether you wish to never detokenize a tokenized entry, the character set used for tokenization, and an optional prefix for tokens. Example value: Credit Card |
Detokenize Response Parameters
| Parameter | Type | Description |
|---|---|---|
| data | string | The detokenized sensitive data. May be masked depending on the configuration. data is case sensitive and limited to 128KiB characters. |
| status | string | Succeeded (if request successful) or Error (if request failed). |
| reason | string | If status is Error, then a reason will be displayed. Otherwise the reason will be omitted. |
Example
Note
If you use the --tlsv1.2 CURL option, you must use CURL version 7.34 or higher.
Request
curl -k -X POST -u tok-user1:Panda45# -d'{"tokengroup" : "ctsUsers-t" , "token" : "CC-0332335756020172", "tokentemplate" : "ctsUsersTemplate" }' https://192.168.118.140/vts/rest/v2.0/detokenize
If the client authentication feature is enabled, the example syntax is as follows:
curl -k --key client.key --cert client.crt -X POST -u tok-user1:Panda45# -d'{"tokengroup" : "ctsUsers-t" , "token" : "CC-0332335756020172", "tokentemplate" : "ctsUsersTemplate" }' https://192.168.118.140/vts/rest/v2.0/detokenize
Response
{"data":"9453677629008564","status":"Succeed"}
Detokenizing Multiple Data Items
Up to 5,000 data items can be detokenized in a single curl command by adding multiple data items. For example, to detokenize four data items, you might enter the following in the posttoken.txt file:
Request
cat posttoken.txt
[{"tokengroup" : "ctsUsers-t" , "token" : "CC-0332335756020172",
"tokentemplate" : "ctsUsersTemplate" },{"tokengroup" :
"ctsUsers-t" , "token" : "CC-0332335756020172", "tokentemplate"
: "ctsUsersTemplate" },{"tokengroup" : "ctsUsers-t" , "token" :
"CC-0332335756020172", "tokentemplate" : "ctsUsersTemplate"
},{"tokengroup" : "ctsUsers-t" , "token" : "CC-
0332335756020172", "tokentemplate" : "ctsUsersTemplate" }]
curl -k -X POST -u tok-user1:Panda45# --data-binary
@posttoken.txt https://192.168.118.140/vts/rest/v2.0/detokenize
Response
[{"data":"9453677629008564","status":"Succeed"},{"data":"9453677
629008564","status":"Succeed"},{"data":"9453677629008564","statu
s":"Succeed"},{"data":"9453677629008564","status":"Succeed"}]
The detokenized data is returned in the CURL response in corresponding order of submission.
Note
Newlines are NOT allowed in the input.
If FPE-luhn, FF1-luhn, or Random-luhn is selected in the Change Token Template page of the CT-VL GUI, the data must pass a Luhn check or detokenization will fail with the error message.
Set Log Levels
Set the log level for the REST API.
Log Endpoint Details
| Data | Description |
|---|---|
| HTTP Request | https://IP_Address/vts/rest/v2.0/log |
| Method | POST |
| CT-VL IP Address | The IP address of the CT-VL instance to access with the API call. |
| Response Format | JSON |
| Required Authentication | None |
Log Request Parameter
| Parameter | Required | Type | Description |
|---|---|---|---|
| loglevel | Y | Enum | loglevel can take one of the following values: • error - Default value used in normal production environment.• debug - Use only when directed by support.• info - Do not use unless maximum logging is required. |
Note
The performance of tokenization and detokenization operations are severely affected by a log level of debug, and substantially affected by a log level of info. For maximum throughput, use a loglevel of error.
Log Response Parameter
| Parameter | Type | Description |
|---|---|---|
| status | string | Success (if request succeeded) or Error (if request failed). |
Example
Note
If you use the --tlsv1.2 cURL option, you must use CURL version 7.34 or higher.
Request
curl -k --tlsv1.2 -X POST https://127.0.0.1/vts/rest/v2.0/log --databinary '{"loglevel":"debug"}'
Response
{"status":"success"}
