1.0 Introduction
This article describes the security object tokenization and API schemas.
2.0 Tokenization Scheme
2.1 Prerequisites
The following code block illustrates the value for the FPE field in a JSON format:
{
"format": <JSON object containing datatype format goes here!>,
"description": "An optional string describing this data format"
}Here, the formatfield is a JSON object, which specifies the format of the datatype.
The following are the type of sub-parts of JSON tree structure:
- Encrypted: It represents a homogeneous sequence of characters using a single character set. For example, all digits or all letters.
- Literal: It represents a section of the token that is not to be encrypted. For example, spaces or dashes for tokens like credit card numbers or IDs.
- Compound: It contains any of the following three JSON subparts:
- Concat: Represents a concatenation of heterogeneous token sections, each with its own format. For example, a token can consist of five letters followed by six digits.
- Or: Represents a token section that can match any one of the formats specified by the subparts of the Or part. For example, a section of the token can be either ten digits or ten letters.
- Multiple: Specifies that a particular subpart occurs multiple times. For example, there are multiple subsections of the token, occurring one after the other, that each match a specified format.
The leaf nodes of the tree-like structure are Encrypted and Literal parts.
The format field consists of a tree-like structure, where a data type may be divided into subparts, which in turn can be composed of further subparts. For instance, if we have a 16-digit credit card number with every 4 digits separated by spaces, we can represent this as a concatenation of 7 subparts – 4 subparts for every 4 digits, and space delimiters between the digit groups. Additionally, we can specify heterogeneous token types, such as a sequence of 4 letters (from A to Z) followed by 5 digits (from 0 to 9).
In addition to specifying the general format of a particular part, it is useful to be able to specify additional constraints that must apply to that part. For example, you may want to restrict numerical part values up to 256.
Some of the constraints are listed as follows:
- The number must be greater than, less than, or not equal to some value.
- The number must satisfy the Luhn checksum.
- The token section must have a valid date.
2.1.1 American Social Security Number
The Social Security Number (SSN) is a nine-digit number assigned to each of the American citizens, permanent residents, and eligible non-immigrant workers in the country. This number is used to report wages to the government, track Social Security benefits and for other identification purposes.
Constraints:
- The format of this number is AAA-GG-SSSS.
- It is a hyphen-separated nine-digit number.
- The first part must be less than 900 and cannot be 0 or 666.
- The second part cannot be 0.
- The third part cannot be 0.
- There is a concatenation of multiple token subparts. Each group of digits (AAA, GG, SSSS) is one Encrypted subpart, and the hyphen delimiters are literal subparts.
- Each Encrypted subpart specifies a minimum and maximum length, along with a character set that indicates what type of characters are present.
- Only digits are used; hence, the characters set is from 0 to 9.
{
{
"min_length": 3,
"max_length": 3,
"char_set": [["0", "9"]],
"constraints": {
"num_lt": 900,
"num_ne": [0, 666]
}
},
{"literal": ["-"]},
{
"min_length": 2,
"max_length": 2,
"char_set": [["0", "9"]],
"constraints": {
"num_ne": [0]
}
},
{"literal": ["-"]},
{
"min_length": 4,
"max_length": 4,
"char_set": [["0", "9"]],
"constraints": {
"num_ne": [0]
}
}
]
3.0 Using API for Tokenization
3.1 Create AES Security Object with FPE Field
Perform the following steps to create a tokenization key:
- Send a request to the security object creation endpoint with the FPE field of the security object request containing a JSON object representing an FpeOptions value.
The request JSON for creating a key to tokenize the SSN:
{
"name": "<sobject name>",
"description": "",
"obj_type": "AES",
"key_ops": [
"ENCRYPT",
"DECRYPT",
"APPMANAGEABLE"
],
"key_size": 256,
"fpe": {
"format": {
"concat": [
{
"min_length": 3,
"max_length": 3,
"char_set": [
[
"0",
"9"
]
],
"constraints": {
"num_lt": 900,
"num_ne": [
0,
666
]
}
},
{
"literal": [
"-"
]
},
{
"min_length": 2,
"max_length": 2,
"char_set": [
[
"0",
"9"
]
],
"constraints": {
"num_ne": [
0
]
}
},
{
"literal": [
"-"
]
},
{
"min_length": 4,
"max_length": 4,
"char_set": [
[
"0",
"9"
]
],
"constraints": {
"num_ne": [
0
]
},
"preserve": []
}
]
},
"description": "<sobject description>"
},
"expirationDate": null,
"enabled": true,
"group_id": "<sobject group id>"
} - The security object must be an AES security object. FPE cannot be used with any other security object type.
3.2 Tokenize by Calling Encrypt API
When the security object is created, the response contains the "kid" field. This field is required for calling the encrypt or decrypt APIs. The following example illustrates how to tokenize the number 123-12-1234.
The API to tokenize is /crypto/v1/encrypt.
JSON Request
{
"alg": "AES",
"plain": "MTIzLTEyLTEyMzQ=",
"mode": "FPE"
"key": {
"name": "17-May-Key"
}
}
Where, the value of the plain field is base64 encoded SSN. The result of decoding the "plain" field is “123-12-1234”, the original data provided.
Response
{
"kid": "<tokenization sobject kid>",
"cipher": "NDU2LTU2LTQ1Njc="
}
The cipher is a base64 encoded value of the token. The result of decoding the "cipher" field is “456-45-4567”.
3.3 Detokenize by Calling Decrypt API
The API to de-tokenize is /crypto/v1/keys/{kid}/decrypt.
JSON Request
{
"alg": "AES",
"cipher": "NDU2LTU2LTQ1Njc=",
"mode": "FPE"
}
Response
{
"kid": "<tokenization sobject kid>",
"plain": "MTIzLTEyLTEyMzQ="
}
The "plain" field is the base64 encoded value of the original data. The result of decoding the "plain" field is “123-12-1234”, the original data provided.
4.0 Masking
When detokenizing, it is recommended to mask a part of the token such as replacing the token with asterisks. For example, if an application only needs to see the last four digits of a detokenized ID, there is no need to show the entire ID. This can be done by specifying a mask field with information about what to mask.
Consider the following FpeDataPart for masking the schema:
{
"min_length": 10,
"max_length": 10,
"char_set": [["0", "9"]],
"mask": [0, -1]
}
This represents a datatype consisting of 10 numeric digits, where the first and last characters are masked.
It is also possible to mask entire parts at a time. For instance, masking the first group of digits:
{
"concat": [
{
"min_length": 3,
"max_length": 3,
"char_set": [["0", "9"]],
"constraints": {
"num_lt": 900,
"num_ne": [0, 666]
},
"mask": "all"
},
{"literal": ["-"]},
{
"min_length": 2,
"max_length": 2,
"char_set": [["0", "9"]],
"constraints": {
"num_ne": [0]
}
},
{"literal": ["-"]},
{
"min_length": 4,
"max_length": 4,
"char_set": [["0", "9"]],
"constraints": {
"num_ne": [0]
}
}
]
}
To mask a Compound subpart, specify true instead of "all".
4.1 Masked Detokenization
You can detokenize the cipher text and mask specific characters that were specified in the masking pattern in the response using either of the following ways:
- Fortanix DSM Rest API (One-Time Masked Detokenization)
- Fortanix DSM App Permission Settings (Always Masked Detokenization) - Refer to User’s Guide: Tokenization for more details.
Method 1 - Fortanix DSM REST API
You can detokenize the cipher text and mask specific characters that were specified in the masking pattern by passing the masked parameter as true in the request body.
Request body:
{
"alg": "AES",
"mode": "FPE",
"cipher": "NDU2LTU2LTQ1Njc="
"masked": true
}The "cipher" field is the base64 encoded value of the token. For this example, the cipher received from the previous version was used.
The response is:
{
"kid": "<tokenization sobject kid>",
"plain": "MTIzLTEyLSoqKio="
}The "plain" field is the base64 encoded value of the original data. The result of masked decoding of the "plain" field is “123-12-****”.
To learn more about Fortanix API, refer to https://www.fortanix.com/fortanix-restful-api-references/open-api-3-beta.
Comments
Please sign in to leave a comment.