User's Guide: Tokenization

1.0 Introduction

This article describes the features of the Fortanix DSM tokenization security object.

The Fortanix-Data-Security-Manager (DSM) tokenization feature eliminates the link to sensitive data and is commonly used in credit card processing and other applications to minimize or prevent breaches. This highly secure method protects payment credentials by utilizing Format-Preserving Encryption (FPE), which maintains the original format of data while encrypting it. Sensitive information, such as credit card or account numbers, is replaced with a secure, randomly generated alphanumeric ID that has no connection to an individual or their account.

It also contains information related to:

• Creating a tokenization security object.

• Data types when creating a tokenization object.

• API calls to do de-tokenization.

For more information, refer to the Fortanix Data Security Manager API Quickstart Guide – Security Objects Tokenization.

2.0 Fortanix DSM Tokenization Security Objects Types

This section describes the built-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 users want to protect, they can create security objects belonging to any of these four tokenization data type groups.

Tokenization replaces a customer’s data type (such as credit card number, SSN, IMSI, or custom value) with a randomly generated token, effectively 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 includes 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 supported length for the PAN is a minimum of 13 digits and a maximum of 19 digits.

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

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

  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.

  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the user interface (UI). This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.
  

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

  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the first six digits of the credit card number – 6 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first six digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the first six digits and last four digits of the credit card number – 6 digits + token + 4 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first six digits and the last four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

  NOTE

  To apply a custom masking pattern that differs from the supported data type patterns above, create a Custom security object as described in Section 2.5: 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 lengthranges from a minimum of 14 digits to a maximum of 15 digits. 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. To prevent eavesdroppers from identifying and tracking the subscriber over the radio interface using the IMSI, a Fortanix DSM user can tokenize the IMSI so that it is automatically replaced with a format-preserving numeric ID (“token”).

A Fortanix DSM user can choose to tokenize specific 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:
  

  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.

  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.
  

• Tokenize all but the last four digits of the IMSI number – token + 4 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the first six digits of the IMSI number – 6 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first six digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the first six digits and last four digits of the IMSI number – 6 digits + token + 4 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first six digits and the last four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

  NOTE

  To apply a custom masking pattern that differs from the supported data type patterns above, create a Custom security object as described in Section 2.5: 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 specific 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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

• Tokenize all but the first six digits of the IMSI number – first 6 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first six digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the last four digits of the IMEI number – token + 4 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the first six digits and the last four digits of the IMEI number – first 6 digits + token + 4 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first six and last four since these digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

  NOTE

  To apply a custom masking pattern that differs from the supported data type patterns above, create a Custom security object as described in Section 2.5: 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 used to identify a network interface of a computer or a network node participating in an IPv4 computer network, as well as to locate the computer or node within the network. An IPv4 address consists of 32 bits, divided into four 8-bit blocks.

A Fortanix DSM user can choose to tokenize specific 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:
  

  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

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

  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last three digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the first six digits of the IPv4 address – 6 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first six digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the first six digits and last three digits of the IPv4 address – 6 digits + token + 3 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first six digits and the last three digits since these digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  
  

  NOTE

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

2.2.5 Phone Number (USA)

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

A Fortanix DSM user can choose to tokenize specific 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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

• Tokenize all but the last four digits of the phone number – token + 4 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.
  

• Tokenize all but the first six digits of the phone number – 6 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first six digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.
  

  NOTE

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

2.2.6 Fax Number (USA)

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

A Fortanix DSM user can choose to tokenize specific 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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

• Tokenize all but the last four digits of the fax number – token + 4 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the first six digits of the fax number – 6 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first six digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

  NOTE

  To apply a custom masking pattern that differs from the above supported data type patterns above, create a Custom security object as described in Section 2.5: 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 a ‘domain’ name. The standard format of an email address is as follows:

local-part@domain

A Fortanix DSM user can choose to tokenize specific 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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

• Tokenize the first character of the email address – first character + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first character of the email address, which is typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.
  

• Tokenize all but the local part of the email address – local part + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the complete token except for the local part, as this is typically set to remain visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the domain part of the email address – token + domain. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the complete token except for the domain part as this is typically set to remain visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

  NOTE

  To apply a custom masking pattern that differs from the supported data type patterns above, create a Custom security object as described in Section 2.5: 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 specific digits of a date using a pattern. There are three 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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.
  

• Tokenize the year YYYY in the input date token – mm dd + token or dd mm + token. For example:
  
  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, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.
  

• Tokenize the month (MM) and the day (DD) – token + yyyy. For example:
  
  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, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.
  

  NOTE

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

  Fortanix DSM also allows you to enter a date range as an input token, which should be in MM DD YYYY format. All dates within the specified range, 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, all dates from 02-20-2021 to 10-27-2021 will be tokenized.

  Perform the following steps to specify a date range;

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

  2. Enter the starting date and the ending date in MM DD YYYY format.
     
     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 (SSN), into a random string of characters (called a token) that has no meaningful value if breached. A typical SSN consists of nine digits. In some cases, a token representing an SSN may need to retain the first five real digits, allowing representatives to verify user identities without accessing the full 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 entire token using the toggle button.

  

  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.

  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 four 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. This 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.

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

2.3.2 Passport Number (USA)

A U.S. Passport number consists of six to 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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

• Tokenize all but the last 4 digits of the passport number– token + 4 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the first 4 digits of the passport number – first 4 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except the first four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

  NOTE

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

2.3.3 Driver's License

A Driver’s License in the U.S. is a nine-digit identifier used for tracking purposes. It must contain at least two characters, and any letters must be uppercase.

A Fortanix DSM user can choose to tokenize a driver’s license using the below patterns:

• Fully tokenize the driver’s license – full token. For example:

  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

• Tokenize all but the last 4 digits of the driver’s license – token + 4 digits. For example:
  

  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.
  

• Tokenize all but the first 4 digits of the driver’s license – first 4 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except the first four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.
  

2.3.4 Individual Taxpayer Identification Number (USA)

A Tax Identification Number (TIN) is a nine-digit number used by the U.S. Internal Revenue Service (IRS) for tracking purposes. It is a required piece of 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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.

  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 four digits.

  

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

  NOTE

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

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

2.3.5 Employer Identification Number (USA)

Employer Identification Number (EIN) is a unique nine-digit number 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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

• Tokenize all but the first 2 digits of EIN – first 2 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first two digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the last 4 digits of EIN – token + last four digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except the last four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

  NOTE

  To apply a custom masking pattern that differs from the supported data type patterns above, create a Custom security object as described in Section 2.5: 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)

A U.S. Army and Air Force Service Number is an eight-digit number assigned to personnel in the U.S. Army and Air Force.

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

• Fully tokenize Army and Air Force Service Number – full token. For example:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

• Tokenize all but the first 2 digits of Army and Air Force Service Number – first 2 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first two digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the last 3 digits of Army and Air Force Service Number – token + last 3 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except the last three digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the 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.5: Custom and apply your own masking pattern to it.

2.4.2 Navy Service Number (USA)

A U.S. Navy Service Number is a seven-digit number assigned to personnel in the U.S. Navy.

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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

• Tokenize all but the first 3 digits of Navy Service Number – first 3 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first three digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the last 2 digits of Navy Service Number – token + last 2 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last two digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

  NOTE

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

2.4.3 Coast Guard Service Number (USA)

A U.S. Coast Guard Service Number is a seven-digit number assigned to personnel in the U.S. Coast Guard.

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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

• Tokenize all but the first 4 digits of Coast Guard Service Number – first 4 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the last 3 digits of Coast Guard Service Number – token + last 3 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last three digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

  NOTE

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

2.4.4 Marine Corps Service Number (USA)

A U.S. Marine Corps Service Number is a six-digit number assigned to personnel in the U.S. Marine Corps.

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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.
  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

• Tokenize all but the first 4 digits of Marine Corps Service Number – first 4 digits + token. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the last 4 digits of Marine Corps Service Number – token + last 4 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last four digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

  NOTE

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

2.4.5 Military Officers Service Numbers (USA)

A U.S. Military Officer's Service Number is a five-digit number assigned to military officers in the United States.

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:
  
  Apply dynamic data masking pattern: This is an optional field that can be applied during detokenization, allowing the detokenizing application with the Masked Decrypt permission to view masked data instead of the original plaintext.

  When using the Full Token pattern, a Fortanix DSM user can also choose to mask the entire token using the Apply dynamic data masking pattern option in the UI. This replaces the full token with asterisks (*), providing an additional layer of security by hiding the token’s identity.

  

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

  

  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the first three digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

• Tokenize all but the last 3 digits of Military Corps Service Number – token + last 3 digits. For example:
  
  With this pattern, a Fortanix DSM user can choose to mask the entire token except for the last three digits, which are typically left visible. Masking can be applied using the Apply dynamic data masking pattern option in the UI. This replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

  

  NOTE

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

2.5 Custom

A Fortanix DSM user can use this tokenization method to protect any type of data beyond the available categories. You can choose to tokenize any combination of characters within the data.

• A token can consist of up to five parts.

• Each part can contain a maximum of one character, with no overall maximum length.  

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

• For the suffix or prefix, you can select from the five available delimiter values provided in the UI or create a custom delimiter using the add button .

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

• Numbers

• Alphanumeric

• Characters

• Hexadecimal

Each token can be of any Length, where the minimum (min) length must be at least 1 and the maximum (max) length can be any value up to (2^32) – 1. Tokenization or preserving of characters is based on the min length.

By default, the min length is 12 and the max length is 100. Therefore, you can choose to tokenize or preserve any or all of the first six or last six characters.

• If the min and max lengths are the same and less than or equal to 12, the ellipsis box will not be displayed.
  

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

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

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

  • The arrow below 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 also be even. Clicking this arrow expands the token in increments of 2.
  
  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.
  

• If the min length is greater than 12 and an odd number, the number on the top arrow will also be odd. Click this arrow to expand the token in increments of 2.
  
  To display the last character, select the dotted box on on either side of the ellipsis box, then click the arrow above the ellipsis box to reveal the last character in the selected dotted box.
  
  The last character is now displayed on the selected box. The other dotted box is disabled.
  
  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 has 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", add a delimiter (such as a “space”) between the parts. The delimiter should be a character (or characters) that do not belong to the character sets of either part. This helps 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: Select this option to create a custom token containing only numeric characters.
  
  

  • If you want the token input to fall within a specified minimum and maximum value range, enter the desired values in the min and max Value fields, respectively. For example, if you enter a minimum value of 10 and a maximum value of 100, the input (tokenization value) must fall within that range. There is no limit to the max value.

  • Special characters are printable ASCII characters that are not letters or numbers. To include special characters in the custom token, select the Allow special characters check box. Enabling this option disables the min and Max Value fields, so special characters in a custom token cannot be constrained by minimum or maximum values.

  • To include whitespace characters anywhere in the token, select the Allow white spaces check box.

  • You can also change the output data type to uppercase alphabetic characters from A to J. To enable this, toggle the Use different output datatype option. Note that this feature is disabled if you select either the Allow special characters or Allow white spaces check boxes.
    In the Fortanix DSM UI, for raw input data, this option is only available for the “Number” data type, and the tokenized output data will consist of uppercase “alphabetic characters (A–J)”. However, for all other token types and for generating uppercase, lowercase, or mixed-case tokenized output, 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, ensure that the length of the output and input data types is the same.

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

    

  • A LUHN check is a mathematical formula used to validate various identification numbers. 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: Select this option to create a custom token containing hexadecimal values.

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

  

• Alphanumeric: Select this option to create a custom token containing alphanumeric values.

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

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

  

• Characters: Select this option to create a custom token containing character values.

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

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

  

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

2.5.2 Masking Pattern

The Dynamic Data Masking Pattern is an optional field that can be applied during detokenization so that the detokenizing application, with the Masked Decrypt permission, sees the masked data instead of the original data in plain text.

A Fortanix DSM user can choose to mask part or all of a token with asterisks (*), further securing the token’s identity. Masking can be applied to any combination of characters using the Dynamic Data Masking Pattern option in the UI. You can click on some or all of the characters you want to mask. The remaining characters will be retained, if applicable.

For example, in the case of a custom token, you can mask the first three digits by clicking on them. If you want to mask all the characters, click the first character and drag the mouse to the right until you reach the last digit.

2.5.3 Create Your Own Token

Perform the following steps 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, or Hexadecimal.

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

4. Optionally, enter the Value min to max range.

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

6. Optionally, select the Perform LUHN check check box. This option is unavailable if Value min to max is specified.

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

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

   • To add a suffix, select from the available options 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 selections in the “Token pattern” panel.

10. Click ADD NEXT PART.

11. Repeat steps 2-8 to create the remaining parts and complete your 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 spaces or hyphens.

• The format should be: HR-0619850034761.
  Where,

  • The first two characters represent the state code and must be uppercase letters.

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

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

  • The last seven characters must be digits from 0 to 9.

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

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

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

3. Next, add a suffix/delimiter by selecting the hyphen (‘-‘).

4. Then, click ADD NEXT PART to configure the second part.
   

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

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

7. Then, click ADD NEXT PART to configure the third part.
   

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

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

10. Then, click ADD NEXT PART to configure the fourth and final part.
    

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

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

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 spaces or hyphens.

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

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

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

  • The last four characters represent the serial number and must be digits.

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

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

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

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

4. Then, click ADD NEXT PART to configure the second part.
   

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

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

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

8. Then, click ADD NEXT PART to configure the third part.
   

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

10. Enter Length 4 to 4 to define the length of the third part.
    

The final tokenized SSN number will look like this:

Additionally, you can choose to mask the part or all of the 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:
  

• If you want to mask all the numbers:
  

3.0 Create a Tokenization Security Object

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

Perform the following steps to create a Tokenization security object:

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. In the DSM left navigation panel, click the Security Objects menu item, and then click the + button to create a new security object.

   

3. On the Add new Security Object page, do the following:

   1. Security Object Name: Enter the name of your security object.

   2. Group: Select the group as created in Section 2.2: Creating a Group.

   3. Select GENERATE.

   4. In the Choose a type section, select the Tokenization key type.

      

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

      • General

      • Identification Numbers (USA)

      • Military Service Numbers (USA)

      • Custom

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

      

   6. If you want to mask your token, then select the Appy dynamic data masking pattern check box. Then, move the slider below the token to choose a masking pattern.

      

   7. In the Key operation permitted section, the following key operations are permitted for a Tokenization key:

      • Tokenize (encrypt)

      • Detokenize (decrypt)

      • App Manageable

      • Export

      

4. Click GENERATE to create the new security object.

The new Tokenization security object is now created.

4.0 Tokenization Operations Using REST API

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

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 six digits of the text (credit card number) are identical to the original plain text, while the remaining 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 Operations Using Batch Encryption and Decryption API

4.4.1 Batch Encryption

Post Body:

POST /crypto/v1/keys/batch/encrypt 

Sample request body:

[ 
  { 
    "request": { 
      "alg": "AES", 
      "plain": "6rqc6r6q65C+7Kqd66ym64q36rig67Ow6rmY7ZCs", 
      "mode": "FPE" 
    }, 
    "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62" 
  }, 
  { 
    "request": { 
      "alg": "AES", 
      "plain": "64yV64yV64yV64yV64yV64yV64yV64yV64yV64yV", 
      "mode": "FPE" 
    }, 
    "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62" 
  }, 
  { 
    "request": { 
      "alg": "AES", 
      "plain": "6rqc6r6q65C+7Kqd66ym64q36rig67Ow6rmY7ZCs", 
      "mode": "FPE" 
    }, 
    "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62" 
  } 
] 

Sample response body:

[ 
  { 
    "status": 200, 
    "body": { 
      "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62", 
      "cipher": "6rSO7JWq7Zu57K6M7Ymn67qm67SU7YaP6ryY7YaO" 
    } 
  }, 
  { 
    "status": 200, 
    "body": { 
      "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62", 
      "cipher": "6rqc6r6q65C+7Kqd66ym64q36rig67Ow6rmY7ZCs" 
    } 
  }, 
  { 
    "status": 200, 
    "body": { 
      "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62", 
      "cipher": "6rSO7JWq7Zu57K6M7Ymn67qm67SU7YaP6ryY7YaO" 
    } 
  } 
] 

4.4.2 Batch Decryption

Post Body:

POST /crypto/v1/keys/batch/decrypt 

Sample request body:

[ 
  { 
    "request": { 
      "alg": "AES", 
      "mode": "FPE", 
      "cipher": "6rqc6r6q65C+7Kqd66ym64q36rig67Ow6rmY7ZCs" 
    }, 
    "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62" 
  }, 
  { 
    "request": { 
      "alg": "AES", 
      "mode": "FPE", 
      "cipher": "64yV64yV64yV64yV64yV64yV64yV64yV64yV64yV" 
    }, 
    "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62" 
  }, 
  { 
    "request": { 
      "alg": "AES", 
      "mode": "FPE", 
      "cipher": "6rqc6r6q65C+7Kqd66ym64q36rig67Ow6rmY7ZCs" 
    }, 
    "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62" 
  } 
] 

Sample response body:

[ 
  { 
    "status": 200, 
    "body": { 
      "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62", 
      "plain": "64yV64yV64yV64yV64yV64yV64yV64yV64yV64yV" 
    } 
  }, 
  { 
    "status": 200, 
    "body": { 
      "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62", 
     "plain": "65ut7YiV7L6J7J6C7Yat7Ka27IWs7Iqa7J2H7KyC" 
    } 
  }, 
  { 
    "status": 200, 
    "body": { 
      "kid": "21d23da0-dc9b-492f-8246-e4cc6fe6bc62", 
      "plain": "64yV64yV64yV64yV64yV64yV64yV64yV64yV64yV" 
    } 
  } 
] 

4.5 Masked Detokenization

You can detokenize the cipher text and mask specific characters, as specified in the masking pattern using either of the following methods:

• Fortanix DSM Rest API (One-Time Masked Detokenization)

• Fortanix DSM App Permission Settings (Always Masked Detokenization)

4.5.1 Method 1 - Fortanix DSM REST API

You can detokenize the cipher text and apply the specified masking pattern by setting 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****”.

4.5.2 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 application (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, detokenization (using the REST API) will always apply the masking pattern to certain characters in the output. This eliminates the need to explicitly pass the "masked": true parameter in the request body.

• If you keep the default Decrypt permission, you can still perform a one-time masked detokenization (using the REST API) by explicitly passing the "masked": true parameter in the request body, 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   icon under Groups column. The following dialog box appears on the screen:

   

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 more information on how to use Tokenization API with examples, refer to the Developer's Guide: Tokenization.

5.0 Tweak Handling in Fortanix DSM

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

The tweak is constructed by concatenating 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 them into a UTF-8 string, and uses the resulting bytes as the tweak.

In Fortanix DSM, the tweak is constructed based on the encryption format. During decryption, the same tweak is reconstructed. For a given alphabet, you can define the format by specifying a set of preserved characters when 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. These preserved characters are ignored when generating the tokenized value and are instead passed as a tweak to the FF1 algorithm.

For example, if you want to encrypt the “YYYY” portion of the data in the format “XXXXXX-YYYY-ZZZZ” and preserve the rest—say the original value is “abcdef-1234-9999” and the encrypted value becomes “abcdef-6174-9999”—then the tweak value is “abcdef9999”. If no characters are preserved, Fortanix DSM uses an empty tweak.

6.0 References

• Security Objects Tokenization Quickstart

• Security Objects Tokenization Examples

• Security Objects Tokenization Best Practices