1.0 Introduction
This article provides detailed steps on Security-object tokenization in Fortanix-Data-Security-Manager (DSM), covering both API schemas and user interface (UI) steps.
You can tokenize the data either through the Fortanix APIs or Fortanix DSM UI.
2.0 Through Fortanix DSM User Interface
2.1 Creating an Account
Access the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM. For example, https://eu.smartkey.io.
Figure 1: Logging In
2.2 Creating a Group
Perform the following steps to create a group in the Fortanix DSM:
Click the Groups menu item in the DSM left navigation bar and click the + button on the Groups page to add a new group.
Figure 2: Add Groups
On the Adding new group page, enter the following details:
Title: Enter a title for your group.
Description (optional): Enter a short description for the group.
Click the SAVE button to create the new group.
The new group has been added to the Fortanix DSM successfully.
2.3 Creating an Application
Perform the following steps to create an application (app) in the Fortanix DSM:
Click the Apps menu item in the DSM left navigation bar and click the + button on the Apps page to add a new app.
Figure 3: Add Application
On the Adding new app page, enter the following details:
App name: Enter the name of your application.
Interface (optional): Select the REST option as interface type from the drop down menu.
ADD DESCRIPTION (optional): Enter a short description for the application.
Authentication method: Select the default API Key as the method of authentication from the drop down menu. For more information on these authentication methods, refer to User's Guide: Authentication documentation.
Set app secret key size: Select the required size of the application secret key in bytes from the drop down menu.
Assigning the new app to groups: Select the group created in Section 2.2: Creating a Group from the list.
Click the Save button to add the new application.
The new application has been added to the Fortanix DSM successfully.
2.4 Creating a Security Object
In this example, let us understand the tokenization and masking feature using the Social Security Number (SSN) type.
The tokenization of a security object converts sensitive data, such as a Social Security Number, into a random string of characters (called a token) that has no meaningful value if breached. A typical SSN consists of 9 digits. A token representing an SSN may need to retain the real first 5 digits. This enables representatives to verify user identities without access to the rest of the SSN.
Perform the following steps to create a SSN tokenization security object:
Click the Security Objects menu item from the DSM left navigation and click the + button on the Security Objects page to create a new security object.
Figure 4: Add Security Object
On the Add new Security Object page, do the following:
Security Object Name: Enter the name of your security object.
Group: Select the group as created in Section 2.2: Creating a Group.
Select the GENERATE radio button.
In the Choose a type section, select the Tokenization key type.
Figure 5: Generate Tokenization Object
Key Size: Enter a key size for the security object in bits. The following key sizes are available:
128 bits
192 bits
256 bits
In the Data type section, select the SSN tokenization type for the tokenization security object.
Figure 6: Select Security Object and Data Type
If you want to mask your token, then select the Apply dynamic data masking pattern check box.
You can choose to tokenize certain digits of a SSN using a pattern. There are two types of tokenization patterns that can be applied:Fully tokenize the SSN – full token. For example:
In this pattern, a Fortanix DSM user can also choose to tokenize the complete token using the toggle button.
Apply dynamic data masking pattern: The Apply dynamic data masking pattern is an optional field that can be applied when the data is detokenized so that the detokenizing application with Masked Decrypt permission sees the masked data instead of original data in plain text.
NOTE
The Apply dynamic data masking pattern option is not applicable for the full token pattern, instead masking can be applied only to the last 4 digits.
With this pattern, a Fortanix DSM user can choose to mask only the last four digits. Masking can be applied using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the selected digits of the token with asterisks (*), further securing the token’s identity.Tokenize all but the last 4 digits of the SSN – token + 4 digits. For example:
NOTE
The Apply dynamic data masking pattern option is not applicable for this pattern.
In the Key operations permitted section, select the required operations to define the actions that can be performed with the cryptographic keys.
Tokenize (encrypt)
Detokenize (decrypt)
App Manageable
Export
Figure 7: Select Key Operations
Click the GENERATE button to generate a tokenization security object.
The new tokenization security object for SSN is created.
You can proceed with Section 4.0: Masked Detokenization to use this newly created key, or follow the steps mentioned in Section 3.0: Through API Schema to create a key using the Fortanix REST API.
3.0 Through API Schema
3.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.
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.
Some of the constraints are listed as follows:
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.
{
"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]
}
}
]3.2 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.3 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.4 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.
3.5 Masking Using API
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]
}
},
{"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]
},
"mask": "all"
}
]
}To mask a Compound subpart, specify true instead of "all".
4.0 Masked Detokenization
4.1 Through Fortanix DSM User Interface
You can also generate a masked detokenization key by updating the configuration in the App permissions settings in the detailed view of a Fortanix DSM app created in Section 2.3: Creating an Application.
Perform the following steps to change the app permission from Decrypt to Masked Decrypt:
Navigate to the Apps menu item from the DSM left navigation bar.
Select the application created in created in Section 2.3: Creating an Application.
Click the
icon under Groups column. The following dialog box appears on the screen:
Figure 8: Operations Permitted Dialog Box
From the Decrypt drop down menu, select Masked Decrypt permission.
Figure 9: Select Masked Decrypt Permission
By selecting this option, the attribute
"masked": truewill be internally added in the request body.
4.2 Using API Schema
You can detokenize the cipher text and mask specific characters that were specified in the masking pattern in the Fortanix DSM Rest API (One-Time Masked Detokenization).
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.
Response:
{
"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/dsm.