User's Guide: Tokenization

  • Updated on Mar 12, 2025
  • Published on Jun 20, 2024
  • 53 minute(s) read

1.0 Introduction

The Fortanix-Data-Security-Manager (DSM) tokenization feature eliminates the link to sensitive data and is used in credit card processing and other use cases to reduce or eliminate breaches. This is a highly secure method of protecting payment credentials which include substituting sensitive data such as credit card/ account numbers are generated by using FPE option.

2.0 Fortanix DSM Tokenization Security Objects Types

This section describes the build-in tokenization types. If you are already familiar with the type of tokenization, then you can proceed directly with Section 3.0: Create a Security Object.

2.1 Tokenization Data Types

A security object token can belong to any of the following categories:

  • General

  • Identification Numbers (USA)

  • Military Service Numbers

  • Custom 

Depending on the type of data the users want to protect, they can create security objects belonging to any of the four tokenization data type groups.

Tokenization replaces a customer’s data type (for example, credit card number, SSN, IMSI, custom, and so on) token with a randomly generated code, or token, obfuscating the original data.

2.2 General

When you select General, Fortanix DSM provides the following data types:

  • Credit card

  • IMSI

  • IMEI

  • IP address (v4)

  • Phone number (USA)

  • Fax number (USA)

  • Email address

  • Date

2.2.1 Credit Card Tokenization

A typical credit card number comes with a Personal Account Number (PAN) which can be tokenized. When a merchant swipes a customer’s credit card, the PAN is automatically replaced with a format-preserving numeric ID (“token”). The minimum supported length is the 13 and the maximum supported length is 19.

A Fortanix DSM user can choose to tokenize certain digits of a credit card number using a pattern. There are 4 types of tokenization patterns that can be applied:

  • Fully tokenize the credit card number – full token. For example:
     1.png

    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.

    With the full token pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     2.png

  • Tokenize all but the last four digits of the credit card number – token + 4 digits. For example:
     3.png

    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the last four digits since these digits of the credit card number are set to be visible by the user. 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.

     4.png

  • Tokenize all but the first six digits of the credit card number – 6 digits + token. For example:
     5.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the first six digits since those digits of the credit card number are set to be visible by the user. 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.

     6.png

  • Tokenize all but the first six digits and last four digits of the credit card number – 6 digits + token + 4 digits. For example:
     7.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the first six digits and the last four digits, as those digits of the credit card number are set to be visible by the user. 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.

    8.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.2.2 IMSI Tokenization

The IMSI is a 15-digit number that uniquely identifies every user of a cellular network. For IMSI, the minimum supported length is 14 and the maximum supported length is 15. It is stored as a 64-bit field and is sent by the mobile device to the network.

The phone identifies the subscriber by transmitting the IMSI number. To prevent eavesdroppers from identifying and tracking the subscriber on the radio interface using the IMSI number, a Fortanix DSM user can tokenize the IMSI number so that it is automatically replaced with a format-preserving numeric ID (“token”).

A Fortanix DSM user can choose to tokenize certain digits of an IMSI number using a pattern. There are 4 types of tokenization patterns that can be applied:

  • Fully tokenize the IMSI number – full token. For example:
     1.png

    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     2.png

  • Tokenize all but the last four digits of the IMSI number – token + 4 digits. For example:
     3.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the last four since these digits of the IMSI number are set to be visible by the user. 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.

     4.png

  • Tokenize all but the first six digits of the IMSI number – 6 digits + token. For example:
     5.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the first six digits since these digits of the IMSI number are set to be visible by the user. 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.

     6.png

  • Tokenize all but the first six digits and last four digits of the IMSI number – 6 digits + token + 4 digits. For example:
     7.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the first six digits and the last four digits since these digits of the IMSI number are set to be visible by the user. 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.

     8.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.2.3 IMEI

The International Mobile Equipment Identity (IMEI) is a 15-digit number that uniquely identifies every mobile phone of a cellular network.

A Fortanix DSM user can choose to tokenize certain digits of an IMEI number using a pattern. There are 4 types of tokenization patterns that can be applied:

  • Fully tokenize the IMEI number – full token. For example:
     mceclip84.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip1.png

  • Tokenize all but the first six digits of the IMSI number – first 6 digits + token. For example:
     mceclip2.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the first six digits since these digits of the IMEI number are set to be visible by the user. 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.

     mceclip3.png

  • Tokenize all but the last four digits of the IMEI number – token + 4 digits. For example:
     mceclip4.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the last four since these digits of the IMEI number are set to be visible by the user. 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.

     mceclip5.png

  • Tokenize all but the first six digits and the last four digits of the IMEI number – first 6 digits + token + 4 digits. For example:
     mceclip1.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the first six and last four since these digits of the IMEI number are set to be visible by the user. 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.

     mceclip2.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.2.4 IP Address (V4)

An Internet Protocol Version 4 (IPv4) address is a numerical label that is used to identify a network interface of a computer or a network node participating in an IPv4 computer network and for locating the computer or the network node in the network. An IPv4 address consists of 32 bits divided into four 8-bit blocks.

A Fortanix DSM user can choose to tokenize certain digits of an IPv4 address using a pattern. There are 4 types of tokenization patterns that can be applied:

  • Fully tokenize the IP address – full token. For example:
     mceclip6.png

    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip7.png

  • Tokenize all but the last three digits of the IPv4 address – token + 3 digits. For example:
     mceclip8.png

    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the last three digits since those digits of the IPv4 address are set to be visible by the user. 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.

     mceclip9.png

  • Tokenize all but the first six digits of the IPv4 address – 6 digits + token. For example:
     mceclip10.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the first six digits since these digits of the IPv4 address are set to be visible by the user. 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.

     mceclip11.png

  • Tokenize all but the first six digits and last three digits of the IPv4 address – 6 digits + token + 3 digits. For example:
     mceclip12.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the first six digits and the last three digits since these digits of the IPv4 address are set to be visible by the user. 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.

     mceclip13.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.2.5 Phone Number (USA)

The standard American telephone number is ten digits, such as (555) 555-1234. The first three digits are the "area code," followed by a seven-digit phone number.

A Fortanix DSM user can choose to tokenize certain digits of a phone number using a pattern. There are 3 types of tokenization patterns that can be applied:

  • Fully tokenize the phone number – full token. For example:
     mceclip14.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip15.png

  • Tokenize all but the last four digits of the phone number – token + 4 digits. For example:
     mceclip16.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the last four since these digits of the phone number are set to be visible by the user. 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.
     mceclip17.png

  • Tokenize all but the first six digits of the phone number – 6 digits + token. For example:
     mceclip18.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the first six digits since these digits of the phone number are set to be visible by the user. 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.
     mceclip19.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.2.6 Fax Number (USA)

A USA fax number is just a phone number that has a fax machine (or fax service, fax server, computer with fax software, and so on) connected to it.

A Fortanix DSM user can choose to tokenize certain digits of a fax number using a pattern. There are 3 types of tokenization patterns that can be applied:

  • Fully tokenize the fax number – full token. For example:
     mceclip20.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip21.png

  • Tokenize all but the last four digits of the fax number – token + 4 digits. For example:
     mceclip22.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the last four since these digits of the fax number are set to be visible by the user. 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.

     mceclip23.png

  • Tokenize all but the first six digits of the fax number – 6 digits + token. For example:
     mceclip24.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the first six digits since these digits of the fax number are set to be visible by the user. 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.

     mceclip25.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.2.7 Email Address

The following is the structure of an email address:

A typical email address consists of a ‘username’ and ‘domain’ name. The following is the typical format of an email:

local-part@domain

A Fortanix DSM user can choose to tokenize certain digits of an email address using a pattern. There are 3 types of tokenization patterns that can be applied:

  • Fully tokenize the email address – full token. For example:
     mceclip26.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip27.png

  • Tokenize the first character of the email address – first character + token. For example:
     mceclip0.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the first character of the email address since it is set to be visible by the user. 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.
    mceclip1.png

  • Tokenize all but the local part of the email address – local part + token. For example:
     mceclip28.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the local part since these digits of the email address are set to be visible by the user. 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.

     mceclip29.png

  • Tokenize all but the domain part of the email address – token + domain. For example:
     mceclip30.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except for the domain part since these digits of the email address are set to be visible by the user. 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.

     mceclip31.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.2.8 Date

The following Date formats are supported:

  • MM/DD/YYYY

  • DD/MM/YYYY

The default date format is MM/DD/YYYY with a full token. The input token allows the following delimiters:

  • slash (/)

  • dot (.)

  • hyphen (-)

  • space ( )

A Fortanix DSM user can choose to tokenize certain digits of a date using a pattern. There are 3 types of tokenization patterns that can be applied:

  • Fully tokenize the date in both date formats (MM DD YYYY) and (DD MM YYYY) – full token. For example:
     Datetoken1.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the date token’s identity.
     Datetoken2.png

  • Tokenize the year YYYY in the input date token – mm dd + token or dd mm + token. For example:
     Datetoken3.png
    With this pattern, a Fortanix DSM user can choose to mask only the year part of the input date token (YYYY) but not the month (MM) and day (DD) in the token since it is set to be visible by the user. 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.
     Datetoken4.png

  • Tokenize the month (MM) and the day (DD) – token + yyyy. For example:
     Datetoken5.png
    With this pattern, a Fortanix DSM user can choose to mask only the month and day part of the input date token (MM and DD) but not the year (YYYY) in the token since it is set to be visible by the user. 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.
     Datetoken6.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

    Fortanix DSM also allows you to enter a date range as an input token that should be in MM DD YYYY format where all the dates from the starting date to the ending date will be tokenized. For example:
    If the starting date is 02-20-2021 and the ending date is 10-27-2021, then we can tokenize all the dates from 02-20-2021 to 10-27-2021.
    To specify a date range,

    1. Click Add Date Range link in the "Date" section.
       Datetoken7.png

    2. Enter the starting date and the ending date in MM DD YYYY format.
       Datetoken8.png
      All the dates in the above date range will be tokenized.

2.3 Identification Numbers (USA)

When you select Identification numbers (USA), Fortanix DSM provides the following data types:

  • SSN

  • Passport Number (USA)

  • Driver’s license

  • Individual Taxpayer Identification Number (USA)

  • Employer Identification Number (USA)

2.3.1 SSN Tokenization

This method of tokenization 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 Social Security number 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.

A Fortanix DSM user can choose to tokenize an SSN using the following two patterns.

  • 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.

    6.png

    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.

     Screenshot 2023-07-17 154358.png
    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: 
     3.png

    NOTE

    • The Apply dynamic data masking pattern option is not applicable for this pattern.

    • To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.3.2 Passport Number (USA)

A US Passport number consists of six and nine alphanumeric characters (letters and numbers).

A Fortanix DSM user can choose to tokenize a passport number using the below patterns.

  • Fully tokenize the passport number – full token. For example:
     mceclip32.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip33.png

  • Tokenize all but the last 4 digits of the passport number– token + 4 digits. For example:
     mceclip34.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except the last four digits since these digits of the passport number are set to be visible by the user. 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.

     mceclip35.png

  • Tokenize all but the first 4 digits of the passport number – first 4 digits + token. For example:
     mceclip36.png
    With this pattern, a Fortanix DSM user can choose to mask the complete token except the first four digits since these digits of the passport number are set to be visible by the user. 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.

     mceclip37.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.3.3 Driver's License Number

A Driver’s License Number is a nine-digit number used as a tracking number by the U.S. It supports a minimum 2 characters. Any letter must be in upper case.

You can fully tokenize the Driver’s license number. For example:

mceclip38.png

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.

With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

NOTE

To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.3.4 Individual Taxpayer Identification Number (USA)

A Tax Identification Number (TIN) is a nine-digit number used as a tracking number by the U.S. Internal Revenue Service (IRS) and is required information on all tax returns filed with the IRS.

A Fortanix DSM user can choose to tokenize a TIN using the below two patterns.

  • Fully tokenize the TIN – full token. For example:
     mceclip39.png
    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.

    mceclip40.png

  • Tokenize all but the last four digits of the TIN – token + 4 digits. For example:
     mceclip41.png

    NOTE

    • The Apply dynamic data masking pattern option is not applicable for this pattern.

    • To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.3.5 Employer Identification Number (USA)

Employer Identification Number (EIN) is a unique 9-digit number. It is used by Internal Revenue Service (IRS) to report employment taxes.

A Fortanix DSM user can choose to tokenize an EIN using the below patterns.

  • Fully tokenize EIN – full token. For example:
     mceclip43.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip44.png

  • Tokenize all but the first 2 digits of EIN – first 2 digits + token. For example:
     mceclip45.png
    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the first 2 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip46.png

  • Tokenize all but the last 4 digits of EIN – token + last four digits. For example:
     mceclip47.png
    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the last 4 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip48.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.4 Military Service Numbers (USA)

When you select ‘Military Service Number’, Fortanix DSM provides the following data types:

  • Army and Air Force Service Number (USA)

  • Navy Service Number (USA)

  • Coast Guard Service Number (USA)

  • Marine Corps Service Number (USA)

  • Military Officers Service Numbers (USA)

2.4.1 Army and Air Force Service Number (USA)

An Army and Air Force Service Number (USA) is an 8-digit number assigned to the US Army and Air Force personnel.

A Fortanix DSM user can choose to tokenize an Army and Air Force Service Number (USA) using the below patterns.

  • Fully tokenize Army and Air Force Service Number – full token. For example:
     mceclip49.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip50.png

  • Tokenize all but the first 2 digits of Army and Air Force Service Number – first 2 digits + token. For example:
     mceclip51.png
    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the first 2 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip52.png

  • Tokenize all but the last 3 digits of Army and Air Force Service Number – token + last 3 digits. For example:
     mceclip53.png
    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the last 3 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip54.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.4.2 Navy Service Number (USA)

A Navy Service Number (USA) is a 7-digit number assigned to the US Navy personnel.

A Fortanix DSM user can choose to tokenize a Navy Service Number (USA) using the below patterns.

  • Fully tokenize Navy Service Number – full token. For example:
     mceclip55.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip56.png

  • Tokenize all but the first 3 digits of Navy Service Number – first 3 digits + token. For example:
     mceclip57.png
    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the first 3 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip58.png

  • Tokenize all but the last 2 digits of Navy Service Number – token + last 2 digits. For example:
     mceclip59.png
    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the last 2 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip60.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.4.3 Coast Guard Service Number (USA)

A Coast Guard Service Number (USA) is a 7-digit number assigned to the US Coast Guard personnel.

A Fortanix DSM user can choose to tokenize a Coast Guard Service Number (USA) using the below patterns.

  • Fully tokenize Coast Guard Service Number – full token. For example:
     mceclip61.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip62.png

  • Tokenize all but the first 4 digits of Coast Guard Service Number – first 4 digits + token. For example:
     mceclip63.png
    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the first 4 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip64.png

  • Tokenize all but the last 3 digits of Coast Guard Service Number – token + last 3 digits. For example:
     mceclip65.png
    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the last 3 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip66.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.4.4 Marine Corps Service Number (USA)

A Marine Corps Service Number (USA) is a 6-digit number assigned to the US Marine Corps personnel.

A Fortanix DSM user can choose to tokenize a Marine Corps Service Number (USA) using the below patterns.

  • Fully tokenize Marine Corps Service Number – full token. For example:
     mceclip67.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip68.png

  • Tokenize all but the first 4 digits of Marine Corps Service Number – first 4 digits + token. For example:
     mceclip69.png
    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the first 4 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip70.png

  • Tokenize all but the last 4 digits of Marine Corps Service Number – token + last 4 digits. For example:
     mceclip71.png
    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the last 4 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip72.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.4.5 Military Officers Service Numbers (USA)

A Military Officers Service Number (USA) is a 5-digit number assigned to the US Military officers.

A Fortanix DSM user can choose to tokenize a Marine Corps Service Number (USA) using the below patterns.

  • Fully tokenize Military Officers Service Number – full token. For example:
     mceclip73.png
    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.

    With this pattern, a Fortanix DSM user can also choose to mask the complete token using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

    mceclip74.png

  • Tokenize all but the first 3 digits of Military Officers Service Number – first 3 digits + token. For example:

    mceclip78.png

    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the first 4 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

     mceclip81.png

  • Tokenize all but the last 3 digits of Military Corps Service Number – token + last 3 digits. For example:
     mceclip82.png
    With this pattern, a Fortanix DSM user can also choose to mask the complete token except the last 3 digits using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.

    mceclip83.png

    NOTE

    To apply a custom masking pattern that is different than the above supported data type patterns, create a Custom security object as described in Section 2.4: Custom and apply your own masking pattern to it.

2.5 Custom

A Fortanix DSM user can use this method of tokenization to protect any kind of data other than the available categories. You can choose to tokenize any combination of any characters in the data.

  • You can create a token that consists of a maximum of five parts.

  • Each part can have a maximum of 1 character. There is no maximum limit.  

  • Each part can start with a suffix or end with a prefix.

  • For the suffix/prefix you can select any of the five available delimiters values provided in the UI or create your own custom delimiter using the add  Plus.png button

1.png

Each part of a token can be of the following types with delimiters

  • Numbers

  • Alphanumeric

  • Characters

  • Hexadecimal

2.png

Each token can be of any Length, where the minimum (min) length can be greater or equal to 1 and the maximum (max) length is limited to any value within (2^32) – 1. Tokenization or preserving of characters is based on the min length. The default min length is 12 and the max length is 100, therefore you can choose to token or preserve any/all of the first 6 or last 6 characters.

  • If the min and max length are the same and less than/equal to 12, the ellipsis box will not be displayed.
     2.png

  • If the min length is less than 12 and an odd or even number except 1, you will see an ellipsis box in the center that indicates the remaining characters of the max length.

  • If the min length is greater than 12, you will notice two arrows above and below the ellipsis box in the center of the token pattern.

    • The arrow on top of the ellipsis box will have a number displayed on top of it and is used to expand the token.

    • The arrow on the bottom of the ellipsis box is used to contract the token.

  • If the min length is greater than 12 and an even number, then the number on the top arrow in the token pattern will be an even number. Click this arrow to expand the token in increments of 2.
     3.png
    After expanding the token, the token pattern will appear as shown below. Click the arrow below the ellipsis box to contract the token in decrements of 2.
     4.png

  • If the min length is greater than 12 and an odd number, then the number on the top arrow will be an odd number. Click this arrow to expand the token in increments of 2.
     5.png
    To display the last 1 character, select the dotted box on the left or right of the ellipsis box and click the arrow above the ellipsis box to display the last character on the selected dotted box.
     6.png
    The last character is now displayed on the selected box. The other dotted box is disabled.
     7.png
    Click the arrow below the ellipsis box to contract the token in decrements of 2.

    TIP

    When creating custom tokenization objects with multiple parts, where one of the parts is of variable length, place the delimiters between any two parts that have overlapping character sets.

    For example, if the first part is of type "Numbers" and the second part is of type "Alphanumeric", then add a delimiter (such as a “space”) between the parts. The delimiter should itself be a character (or characters) outside of the character sets of the two parts. (This may prevent subtle parsing errors by the tokenization engine due to local ambiguities.)

    The following example shows tokenization using different output data type:

    {
   "name": "<sobject name>",
   "description": "",
   "obj_type": "AES",
   "key_ops": [
       "ENCRYPT",
       "DECRYPT",
       "APPMANAGEABLE"
   ],
   "key_size": 256,
   "fpe": {
       "description": "<description>",
       "format": {
           "char_set": [
               [
                   "0",
                   "9"
               ]
           ],
           "cipher_char_set": [
               [
                   "a",
                   "j"
               ]
           ],
           "min_length": 13,
           "max_length": 19
       }
   },
   "expirationDate": null,
   "enabled": true,
   "group_id": "<group id>"
}

2.5.1 Token Types

  • Number: If you want the data type as 'number', then use this option to create a custom token containing only numbers.
     8.png

    • If you want the token input to be within a minimum and maximum value range, then type the minimum and maximum values in the min and max Value fields, respectively. For example, if you type the minimum value as 10 and the maximum value as 100, then, the input value (tokenization value) should be in the range of 10 to 100. There is no limit to the max value.

    • Special characters are printable ASCII characters that are not letters or numbers. If you want to use special characters in the customized token, select the Allow special characters check box. Selecting this will disable the min and max Value fields since the special characters in a custom token cannot be attributed to the minimum or maximum values.

    • If you want to add whitespaces as characters anywhere in the token, select the Allow white spaces check box. 

    • You can change the type of output datatype to upper case alphabets from A to J. If you want to perform alphabetical output datatype on the characters, select the Use different output datatype toggle button. This feature is disabled if you select the Allow special character or Allow white spaces check boxes.
      In the Fortanix DSM UI, for raw input data, this option is available only for the “Number” data type and the tokenized output data is only available as uppercase “alphabetic characters” from (A to J). However, for all other token types for input data and uppercase, lowercase, and the mixed case for tokenized output data, you can use the Fortanix DSM API.
      The following example shows tokenization using different output data types:

      {
    "name": "<sobject name>",
    "description": "",
    "obj_type": "AES",
    "key_ops": [
        "ENCRYPT",
        "DECRYPT",
        "APPMANAGEABLE"
    ],
    "key_size": 256,
    "fpe": {
        "description": "<description>",
        "format": {
            "char_set": [
                [
                    "0",
                    "9"
                ]
            ],
            "cipher_char_set": [
                [
                    "a",
                    "j"
                ]
            ],
            "min_length": 13,
            "max_length": 19
        }
    },
    "expirationDate": null,
    "enabled": true,
    "group_id": "<group id>"
}

      NOTE

      • If you select the Use different output datatype toggle button, then ensure that the length of the output and input data type must be the same.

      • Selecting this toggle button will also display the information related to the Data type on the Details page. The following image illustrates a sample screen:

      dif_char_2.PNG

    • A LUHN check is a mathematical formula used to verify various identification numbers. If you want to perform a LUHN check on the characters, select the Perform LUHN check option.

      NOTE

      This feature is disabled if you select the Use different output datatype toggle button, as it is not applicable to the encrypted part with a non-numeric character set.

  • Hexadecimal: If you want the data type as ‘hexadecimal’, then use this option to create a custom token containing hexadecimal values.

    • A hexadecimal token can be only Lowercase, only Uppercase, or a combination of Lowercase and uppercase letters.

     9.png

  • Alphanumeric: If you want the data type as ‘alphanumeric’, then use this option to create a custom token containing alphanumeric values.

    • An alphanumeric token can be only Lowercase, only Uppercase, or a combination of Lowercase and uppercase letters.

    • Select the Allow special characters check box if you want to use special characters.

     10.png

  • Characters: If your data is of type ‘Characters’, then use this option to create a custom token containing customized character values.

    • A Character token can be only Lowercase, only Uppercase, or a combination of Lowercase and uppercase letters.

    • Select the Allow special characters check box if you want to use special characters.

     11.png

A Fortanix DSM user can choose to either tokenize the entire input string (token) or preserve some characters in that string. For example, in the figure below, the 2nd and 4th characters are preserved and will not be tokenized.

12.png

2.5.2 Masking Pattern

Dynamic data masking pattern: The 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.

A Fortanix DSM user can also choose to mask the partial or complete token with asterisks (*), further securing the token’s identity. Masking can be applied to any combination of digits using the Dynamic data masking pattern option in the UI. You can click some or all the characters that you want to mask. The remaining character values will be retained, if applicable.

For example, the following is an example of masking patterns for the custom token where the first three digits are masked by clicking them. If you want to mask all the characters, click on the first character, and drag the mouse to the right till you reach the last digit.
13.png

2.5.3 Create Your Own Token

To create your own custom token:

  1. Select CUSTOM as Data type.

  2. To create the first part, select the type for the token – Numbers/Alphanumeric/Characters/Hexadecimal.

  3. Enter Length min to max range for the first part. The default values are Length 12 to 100.

  4. Optionally, enter Value min to max range.

  5. Optionally, check the Allow special characters check box.

  6. Optionally, check the Perform LUHN check check box. This option is not available when you have entered Value min to max range.

  7. Optionally add a suffix or a prefix or both for the first part.

    • To add a prefix, select from the available prefix values or create your own prefix.

    • To add a suffix, select from the available suffix values or create your own suffix/delimiter.

  8. Optionally, select the Dynamic data masking pattern.

  9. You will now see the token generated based on your selection in the Token pattern panel.

  10. Click ADD NEXT PART.

  11. Repeat steps 2-8 to create the remaining parts and complete creating your own custom token.

Example 1:

Let us look at a simple example to understand how custom tokenization works.

In this example, we will tokenize an Indian driving license.

The following are the conditions for a valid driver’s license:

  • It must consist of 16 characters, including space or hyphen.

  • The format should be HR-0619850034761.
    Where,

    • The first 2 characters represent the state code. They must be upper case letters.

    • The next 2 characters represent the RTO code and must be digits.

    • The next 4 characters represent the license issued year and must be digits.

    • The last 7 characters must consist of digits from 0 to 9.

The following is an example of tokenizing an Indian driver’s license satisfying the above conditions:

  1. In the example, the first 2 characters (state code) are alphabets, so select the Characters option.

  2. Type Length 2 to 2 to define the length of the first part and select the Uppercase radio button since the characters are uppercase.

  3. Now, let us add a suffix/delimiter by clicking ‘-‘ (Hyphen).

  4. Now, click ADD NEXT PART to configure the second part.
     Example-1.png

  5. Select the Numbers option since the second part consists of characters that are digits.

  6. Type Length 2 to 2 to define the length of the second part (RTO code).

  7. Now, click ADD NEXT PART to configure the third part.
    15.png

  8. Select the Numbers option since the third part consists of characters that are digits.

  9. Type Length 4 to 4 to define the length of the third part (License issued year).

  10. Now, click ADD NEXT PART to configure the fourth and the last part.
     16.png

  11. Select the Numbers option since the last part consists of characters that are digits.

  12. Type Length 7 to 7 to define the length of the last part (any digit from 0-7).
     17.png
    The final tokenized driver’s license will look like this:
     18.png

Example 2:

In this example, we will tokenize an SSN number.

The following are the conditions for a valid SSN number :

  • It must consist of 9 characters, including space or hyphen.

  • The format should be 061-98-5003.
    Where,

    • The first 3 characters represent the area number and must be digits.

    • The next 2 characters represent the group number and must be digits.

    • The next 4 characters represent the serial number and must be digits.

The following is an example of tokenizing an SSN number satisfying the above conditions:

  1. In the example, the first 3 characters are digits, so select the Numbers option.

  2. Type Length 3 to 3 to define the length of the first part.

  3. Now, let us add a suffix/delimiter by clicking ‘-‘ (Hyphen).

  4. Now, click ADD NEXT PART to configure the second part.
     19.png

  5. Select the Numbers option since the second part consists of characters that are digits.

  6. Type Length 2 to 2 to define the length of the second part.

  7. Now, let us add a suffix/delimiter by clicking ‘-‘ (Hyphen).

  8. Now, click ADD NEXT PART to configure the third part.
     20.png

  9. Select the Numbers option since the third part consists of characters that are digits.

  10. Type Length 4 to 4 to define the length of the third part.
     21.png

The final tokenized SSN number will look like this:
22.png

Additionally, you can also choose to mask the partial or complete token with asterisks (*), further securing the token’s identity. Masking can be applied to any combination of digits using the Dynamic data masking pattern option in the UI. You can click some or all the characters that you want to mask. The remaining character values will be retained, if applicable.

  • If you want to mask some of the numbers:
     23.png

  • If you want to mask all the numbers:
     24.png

3.0 Create a Security Object

Refer to Security Objects Tokenization Examples to view the list tokenization policy JSON examples for the build-in tokenization types.

To create a Tokenization security object, perform the following steps:

  1. Log in to your Fortanix DSM account using the URL: https://eu.smartkey.io/ to access DSM SaaS for the AMER region. DSM SaaS supports multiple regions, as listed here.

  2. On the Fortanix DSM UI left panel, click the Security Objects tab, and then click the CREATE SECURITY OBJECT button ('+' sign) in the Security Objects page.

    CreateSO.png

    Figure 1: Create a Tokenizer Security Object

  3. In the Add New Security Object page, enter a name for your new security object, and assign the security object to a group.

  4. Select the GENERATE option, to generate a security object.

  5. Select the type of security object as Tokenization.  

    CreateSOform.png

    Figure 2: Generate Tokenizer Object

  6. In the Data type list, select the tokenization type for the Tokenization security object. There are four categories of data types to select from, namely:

    • General

    • Identification Numbers (USA)

    • Military Service Numbers (USA)

    • Custom

    Refer to the previous section for more details about these data types.

    CreateSOFormToken.png

    Figure 3: Select Security Object Type

  7. If you want to mask your token, then select Apply dynamic data masking pattern. 

  8. Move the slider below the token to choose a masking pattern.

  9. Enter a key size for the security object. The allowed values are 128 bits, 192 bits, and 256 bits.

  10. Select the permitted key operations on this security object. The key operations that are permitted for a Tokenization key are:

    • Tokenize (encrypt)

    • Detokenize (decrypt)

    • App (Application) Manageable

    • Export

    25.png

    Figure 4: Select Key Operations

  11. Lastly, click GENERATE to generate a Tokenization security object.

  12. The new Tokenization security object is created.

    TokenizerObjectCreated.png

    Figure 5: Tokenizer Security Object Created

4.0 Tokenization Operations Using REST API

Once the tokenization object is created, it can be used to tokenize and de-tokenize data. For the examples shown in this section the following tokenization object will be used:

26.png

Figure 6: Create a New Token

4.1 Generating a Token

To generate a token from the data given in Figure 6, the following API request should be used:

POST https://{{server}}/crypto/v1/keys/{{token_key_uuid}}/encrypt

 Request body:

{
 "alg": "AES",
 "mode": "FPE",
 "plain": "MjIyMjQwNTM0MzI0ODg3Nw=="
}

 the "plain" field is the base64 encoded value of the data to tokenize. For this example, the base64 encoding of “2222405343248877” was used.

The request-response is:

{
 "kid": "034a9879-8206-4898-bb6e-05e4cb69782d",
 "cipher": "MjIyMjQwMzYzNzE1MDQ0Ng=="
}

 The base64 decoded value of the returned "cipher" field is “2222403637150446”. The first 6 digits of the text (credit card number) are identical to the original plain text and the rest of the digits are tokenized.

4.2 Obtaining Original Data

To obtain the original data from a given token, the following API request should be used:

POST https://{{server}}/crypto/v1/keys/{{token_key_uuid}}/decrypt

 Request body:

{
 "alg": "AES",
 "mode": "FPE",
 "cipher": "MjIyMjQwMzYzNzE1MDQ0Ng=="
}

The "cipher" field is the base64 encoded value of the token. For this example, the cipher received from the previous version was used.

The request response is:

{
 "kid": "034a9879-8206-4898-bb6e-05e4cb69782d",
 "plain": "MjIyMjQwNTM0MzI0ODg3Nw=="
}

 The "plain" field is the base64 encoded value of the original data. The result of decoding the "plain" field is “2222405343248877”, the original data provided.

4.3 Operations Using Generic Batch API

Fortanix DSM provides the ability to perform batch encryption and decryption operations through the REST API.

4.3.1 Batch Encryption

Post Body:

POST https://{{server}}/batch/v1

Sample request body:

{
  "Batch": {
    "batch_execution_type": "Unordered",
    "items": [
      {
        "SingleItem": {
          "method": "POST",
          "operation": "/crypto/v1/encrypt",
          "body": {
            "alg": "AES",
            "plain": "6rqc6r6q65C+7Kqd66ym64q36rig67Ow6rmY7ZCs",
            "mode": "FPE",
            "key": {
              "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62"
            }
          }
        }
      },
      {
        "SingleItem": {
          "method": "POST",
          "operation": "/crypto/v1/encrypt",
          "body": {
            "alg": "AES",
            "plain": "6rqc6r6q65C+7Kqd66ym64q36rig67Ow6rmY7ZCs",
            "mode": "FPE",
            "key": {
              "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62"
            }
          }
        }
      }
    ]
  }
}

Sample response body:

{
  "Batch": {
    "items": [
      {
        "SingleItem": {
          "Result": {
            "status": 200,
            "body": {
              "cipher": "6rSO7JWq7Zu57K6M7Ymn67qm67SU7YaP6ryY7YaO",
              "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62"
            }
          }
        }
      },
      {
        "SingleItem": {
          "Result": {
            "status": 200,
            "body": {
              "cipher": "6rSO7JWq7Zu57K6M7Ymn67qm67SU7YaP6ryY7YaO",
              "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62"
            }
          }
        }
      }
    ]
  }
}

4.3.2 Batch Decryption

Post body:

POST https://{{server}}/batch/v1

Sample request body:

{
  "Batch": {
    "batch_execution_type": "Unordered",
    "items": [
      {
        "SingleItem": {
          "method": "POST",
          "operation": "/crypto/v1/decrypt",
          "body": {
            "alg": "AES",
            "cipher": "MDgzMTk2MDY0MDEyNDI3Nw==",
            "mode": "FPE",
            "key": {
              "kid": "7ef9e1d7-fbb1-4ec9-9ec0-94113c0735e7"
            }
          }
        }
      },
      {
        "SingleItem": {
          "method": "POST",
          "operation": "/crypto/v1/decrypt",
          "body": {
            "alg": "AES",
            "cipher": "MDgzMTk2MDY0MDEyNDI3Nw==",
            "mode": "FPE",
            "key": {
              "kid": "7ef9e1d7-fbb1-4ec9-9ec0-94113c0735e7"
            }
          }
        }
      }
    ]
  }
}

Sample response body:

{
    "Batch": {
        "items": [
            {
                "SingleItem": {
                    "Result": {
                        "status": 200,
                        "body": {
                            "kid": "7ef9e1d7-fbb1-4ec9-9ec0-94113c0735e7",
                            "plain": "NTIwMDgyODI4MjgyODIxMA=="
                        }
                    }
                }
            },
            {
                "SingleItem": {
                    "Result": {
                        "status": 200,
                        "body": {
                            "kid": "7ef9e1d7-fbb1-4ec9-9ec0-94113c0735e7",
                            "plain": "NTIwMDgyODI4MjgyODIxMA=="
                        }
                    }
                }
            }
        ]
    }
}

4.4 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)

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": "MjIyMjQwMzYzNzE1MDQ0Ng=="
"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 request response is:

{
"kid": "034a9879-8206-4898-bb6e-05e4cb69782d",
"plain": "MjIyMjQwNTM0MzI0KioqKg=="
}

The "plain" field is the base64 encoded value of the original data. The result of masked decoding the "plain" field is “222240534324****”.

Method 2 - Fortanix DSM App Settings

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. To do this you must change the app permission from Decrypt to Masked Decrypt.

By changing the app permission from Decrypt to Masked Decrypt, the detokenization (using the REST API) is always performed by masking certain characters in the output specified in the masking pattern. This way you do not need to pass "masked": true parameter in the request body explicitly.

By keeping the default Decrypt permission, during detokenization (using the REST API), you can still explicitly perform a one-time masking of certain characters in the output specified in the masking pattern by passing the "masked": true parameter as described in Method 1 above.

Perform the following steps to change the app permission from Decrypt to Masked Decrypt:

  1. Navigate to the Apps tab.

  2. Select the required application from the table.

  3. Click the  Edit_icon.PNG icon under Groups column. The following dialog box appears on the screen:
    Operations_Permitted_Dialog_Box.png
    Figure 7: Operations Permitted Dialog Box

  4. From the Decrypt drop down menu, select Masked Decrypt permission.

  5. By selecting this option, the attribute "masked": true will be internally added in the request body.

For a detailed guide on how to use Tokenization API with examples, refer to Developer's Guide: Tokenization.

5.0 Tweak Handling in Fortanix DSM

The tokenization feature in Fortanix DSM does not allow end user to directly specify a tweak in the REST API and instead the tweak is implicitly calculated from preserved characters.

The tweak is the concatenation of all preserved characters, as UTF-8 bytes. Specifically, Fortanix DSM splits the input string into Unicode codepoints, extracts all characters (codepoints) that are to be preserved, concatenates those characters together in a UTF-8 string, and uses those bytes as the tweak.

In Fortanix DSM, the tweak is constructed based on the encryption format. On decryption, the same tweak is reconstructed. For a given alphabet, you can select the format by specifying a set of preserved characters while creating the tokenization security object.

The "preserve" field in tokenization security object indicates the characters that must remain the same in both the plain text and the tokenized output. The application ignores those characters when generating tokenized value, and instead passes in those characters as a tweak to the FF1 algorithm.

If you want to encrypt the “YYYY” portion with FF1 in the data format “XXXXXX-YYYY-ZZZZ” and preserve the rest, for example, if the encrypted value for “abcdef-1234-9999” is “abcdef-6174-9999”, then the tweak value is “abcdef9999”. If there are no preserved characters, Fortanix DSM uses empty tweaks.

6.0 More Information

Related articles