Security Objects Tokenization Quickstart

  • Updated on Jan 16, 2026
  • Published on Jun 20, 2024
  • 19 minute(s) read
Prev Next

1.0 Introduction

This article provides detailed steps on Security-object tokenization in Fortanix-Data-Security-Manager (DSM), covering both API schemas and user interface (UI) steps.

You can tokenize the data either through the Fortanix APIs or Fortanix DSM UI.

2.0 Using Fortanix DSM User Interface

2.1 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

Figure 1: Logging In

2.2 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

  1. In the DSM left navigation panel, click the Groups menu item and then click the + button to create a new group.

    Figure 2: Add groups

  2. On the Adding new group page, do the following:

    1. Title: Enter a name for your group.

    2. Description (optional): Enter a short description of the group.

  3. Click SAVE to create the new group.

The new group is added to the Fortanix DSM successfully.

2.3 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

  1. In the DSM left navigation panel, click the Apps menu item and then click the + button to create new app.

    Figure 3: Add application

  2. On the Adding new app page, do the following:

    1. App name: Enter the name for your application.

    2. Interface (optional): Select REST as the interface type from the drop down menu.

    3. ADD DESCRIPTION (optional): Enter a short description of the application.

    4. Authentication method: Select the default API Key as the authentication method from the drop down menu. For more information on these authentication methods, refer to the User's Guide: Authentication.

    5. Assigning the new app to groups: Select the group created in Section 2.2: Creating a Group from the list.

  3. Click SAVE to add the new application.

The new application is added to the Fortanix DSM successfully.

2.4 Creating a Security Object

In this example, let us understand the tokenization and masking feature using the Social Security Number (SSN) type.

The tokenization of a security object converts sensitive data, such as a Social Security Number, into a random string of characters (called a token) that has no meaningful value if breached. A typical SSN consists of 9 digits. A token representing an SSN may be configured to retain the real first 5 digits. This allows representatives to verify user identities without exposing the entire SSN.

Perform the following steps to create a SSN tokenization security object:

  1. In the DSM left navigation panel, click the Security Objects menu item and then click the + button to create a new security object.

    Figure 4: Add security object

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

    1. Security Object Name: Enter a name for 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.

      Figure 5: Generate tokenization object

    5. Key Size: Enter a key size for the security object in bits. The following key sizes are available:

      • 128 bits

      • 192 bits

      • 256 bits

    6. In the Data type section, select the SSN tokenization type for the tokenization security object.

      Figure 6: Select security object and data type

    7. If you want to mask your token, then select the Apply dynamic data masking pattern check box.
      You can choose to tokenize specific digits of an SSN using a pattern. There are two types of tokenization patterns that can be applied:

      • Fully tokenize the SSN – full token. For example:
        In this pattern, a Fortanix DSM user can also choose to tokenize the complete SSN using the toggle button.


        Apply dynamic data masking pattern: This is an optional field that can be applied when the data is detokenized so that the detokenizing application with Masked Decrypt permission sees the masked data instead of original data in plain text.

        NOTE

        The Apply dynamic data masking pattern option is not applicable for the full token pattern, instead masking can be applied only to the last 4 digits.


        With this pattern, a Fortanix DSM user can choose to mask only the last four digits. Masking can be applied using the Apply dynamic data masking pattern option in the UI. The masking pattern replaces the selected digits of the token with asterisks (*), further securing the token’s identity.

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

        NOTE

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

    8. In the Key operations permitted section, select the required operations to define the actions that can be performed with the cryptographic keys.

      • Tokenize (encrypt)

      • Detokenize (decrypt)

      • App Manageable

      • Export

      NOTE

      To convert a Tokenization key into an Irreversible Tokenization key, remove the Detokenize and Export operations.

      Figure 7: Select key operations

  3. Click GENERATE to generate a tokenization security object.

The new tokenization security object for SSN is created.

You can proceed with Section 4.0: Masked Detokenization to use this newly created key, or follow the steps mentioned in Section 3.0: Through API Schema to create a key using the Fortanix REST API.

3.0 Using API Schema

3.1 Format Definition

When creating a security object for format-preserving encryption (FPE), the request includes an fpe field. The value of this field defines how the token is structured and how tokenization and detokenization are performed.

Fortanix DSM describes the structure of a token using a format-based definition. This definition specifies which parts of the token are encrypted, which parts are fixed literals, and how these parts are combined.

The following code block illustrates the structure of the fpe field in a security object request:

 "fpe": {
    "format": <JSON object containing datatype format goes here!>,
    "description": "An optional string describing this data format"
  }

The format field defines the structure of the token. Its definition is expressed as a tree of format parts, where each part represents a portion of the token and can be one of the following:

  • Encrypted: It represents a homogeneous sequence of characters that is tokenized (encrypted). It is defined by constraints such as length, character set, and optional numeric  constraints.

    NOTE

    An encrypted part is represented implicitly in the JSON schema by a leaf object that specifies fields such as min_length, max_length, char_set , and constraints . There is no explicit field named encrypted in the JSON schema.
    Where,

    • min_length: The minimum number of characters in the encrypted sequence.

    • max_length: The maximum number of characters in the encrypted sequence.

    • char_set: The set of characters allowed in the encrypted sequence. Each element of the array specifies a closed range of characters, represented as a two-element array [start, end]. All characters between start and end (inclusive) are allowed.

    • constraints (Optional): Additional restrictions that apply only to encrypted parts, further limiting the set of valid values after length and character validation. Constraints operate on either the numeric or semantic interpretation of the encrypted sequence. Numeric constraints apply only to encrypted parts whose character set consists exclusively of digits (0–9).

      The following constraint parameters are supported:

      • luhn_check: Specifies whether the token part must satisfy the Luhn checksum formula. This constraint can only be applied to numeric encrypted parts. An encrypted part may be subject to at most one Luhn check constraint.

        The value of luhn_check is a boolean:

        • true indicates that the encrypted numeric value must satisfy the Luhn checksum.

        • false indicates that no Luhn validation is applied.

      • num_lt: Specifies that the numeric value of the encrypted sequence must be strictly less than the given value.

      • num_gt: Specifies that the numeric value of the encrypted sequence must be strictly greater than the given value.

      • num_ne: Specifies a list of numeric values that the encrypted sequence must not equal. This field accepts an array to allow excluding multiple disallowed values. For example, "num_ne": [0, 3, 8] ensures that the encrypted value is not equal to any of the listed numbers.

      • date: Specifies date-related validation constraints for a portion of a token. Date constraints ensure that encrypted values represent valid dates and optionally restrict them to a range. Date constraints are expressed using one of the following supported date variants:

        • dmy_date (Day–Month–Year): Represents a full calendar date consisting of a day, month, and year. The expected string format of the encrypted value is DD-MM-YYYY (for example, 15-01-2026).

          You can optionally specify:

          • before: The latest allowed date. The encrypted date must be strictly earlier than this value.

          • after: The earliest allowed date. The encrypted date must be strictly later than this value.

            Each date is specified using the following fields:

          • year: Integer less than 100000.

          • month: Integer from 1 to 12.

          • day: Integer from 1 to 28, 29, 30, or 31, depending on the month and year.

        • month_day_date (Month–Day): Represents a date consisting of a month and day, without a year. The expected string format of the encrypted value is MM-DD (for example, 02-29).

          You can optionally specify:

          • before: The latest allowed month or day. The encrypted value must be strictly earlier than this value.

          • after: The earliest allowed month or day. The encrypted value must be strictly later than this value.

            Each date is specified using the following fields:

          • month: Integer from 1 to 12.

          • day: Integer from 1 to 29, 30, or 31, depending on the month.

        • month_year_date (Month–Year): Represents a date consisting of a month and year, without a day. The expected string format of the encrypted value is MM-YYYY (for example, 06-2025).

          You can optionally specify:

          • before: The latest allowed month or year. The encrypted value must be strictly earlier than this value.

          • after: The earliest allowed month or year. The encrypted value must be strictly later than this value.

            Each date is specified using the following fields:

          • year: Integer less than 100000.

          • month: Integer from 1 to 12.

      • applies_to: Specifies which subparts of a compound token format a given set of constraints should apply to. This field is primarily used with compound structures (such as concat, or, or multiple) to indicate whether constraints apply to:

        • "all": All descendant encrypted parts within the structure.

          Example:

          "constraints": {
  "luhn_check": true,
  "applies_to": "all"
}

          Here, the Luhn check applies to all descendant encrypted parts that represent numeric values.

        • A specific subset of subparts (represented as an object, depending on the compound structure).

          Example,

          "constraints": {
  "luhn_check": true,
  "applies_to": {
    "account_number": true
  }
}

          Here, the Luhn check applies only to account_number. Other encrypted parts in the same compound structure are unaffected.

  • Literal: It represents a section of the token that is not encrypted. For example, separators (spaces or dashes) for tokens like credit card numbers or IDs. A Literal section is represented by a leaf JSON object that contains a single field, literal.

  • Compound: It combines multiple subparts (Encrypted or Literal) into a larger structure. Compound sections are one of the following types:

    • Concat: Represents a concatenation of heterogeneous token sections, each with its own format. For example, a token can consist of five letters followed by six digits. A Concat section is represented by a JSON object containing a single field, concat, whose value is an array of subparts.

    • Or: Represents a token section that can match any one of the formats specified by the subparts of the Or part. For example, a section of the token can be either ten digits or ten letters. An Or section is represented by a JSON object containing a single field, or, whose value is an array of alternative subparts.

    • Multiple: Repeats a given subpart multiple times in sequence. For example, there are multiple subsections of the token, occurring one after the other, that each match a specified format. A multiple-section is represented by a JSON object containing a single field, multiple, which defines the repeated subpart and its repetition parameters.

The following code block illustrates the structure of the fpe field using an example:

 "fpe": {
    "format": {
      "concat": [
        {
          "min_length": 3,
          "max_length": 3,
          "char_set": [
            [
              "0",
              "9"
            ]
          ],
          "constraints": {
            "num_lt": 900
          }
        },
        {
          "literal": [
            "-"
          ]
        },
        {
          "min_length": 2,
          "max_length": 2,
          "char_set": [
            [
              "0",
              "9"
            ]
          ],
          "constraints": {
            "num_ne": [
              0
            ]
          }
        }
      ]
    }
  }

Credit Card

The format field consists of a tree-like structure, where a data type may be divided into subparts, which in turn can be composed of further subparts. For instance, if we have a 16-digit credit card number with every 4 digits separated by spaces, we can represent this as a concatenation of 7 subparts – 4 subparts for every 4 digits, and space delimiters between the digit groups. Additionally, we can specify heterogeneous token types, such as a sequence of 4 letters (from A to Z) followed by 5 digits (from 0 to 9).

In addition to specifying the general format of a particular part, it is useful to be able to specify additional constraints that must apply to that part. For example, you may want to restrict numerical part values to a maximum of 256.

Some of the constraints are listed as follows:

  • The number must be greater than, less than, or not equal to some value.

  • The number must satisfy the Luhn checksum.

  • The token section must have a valid date.

American Social Security Number

The Social Security Number (SSN) is a nine-digit number assigned to each of the American citizens, permanent residents, and eligible non-immigrant workers in the country. This number is used to report wages to the government, track Social Security benefits and for other identification purposes.

Some of the constraints are listed as follows:

  • The format of this number is AAA-GG-SSSS.

    • The first part (AAA) must be less than 900 and cannot be 0 or 666.

    • The second part (GG) cannot be 0.

    • The third part (SSS) cannot be 0.

  • It is a hyphen-separated nine-digit number.

  • The number consists of multiple token subparts. Each group of digits (AAA, GG, SSSS) is one encrypted subpart, and the hyphen delimiters are literal subparts.

  • Each encrypted subpart specifies a minimum and maximum length, along with a character set that indicates the types of characters present.

  • Only digits are used, so the character set is from 0 to 9.

{
  "concat": [
    {
      "min_length": 3,
      "max_length": 3,
      "char_set": [["0", "9"]],
      "constraints": {
        "num_lt": 900,
        "num_ne": [0, 666]
      }
    },
    {
      "literal": ["-"]
    },
    {
      "min_length": 2,
      "max_length": 2,
      "char_set": [["0", "9"]],
      "constraints": {
        "num_ne": [0]
      }
    },
    {
      "literal": ["-"]
    },
    {
      "min_length": 4,
      "max_length": 4,
      "char_set": [["0", "9"]],
      "constraints": {
        "num_ne": [0]
      }
    }
  ]
}

3.2 Create AES Security Object with FPE Field

Perform the following steps to create a tokenization key:

  1. Send a request to the Fortanix DSM endpoint with the fpe field in the security object request. The fpe field contains a JSON object that defines the token format and the behavior used for tokenization and detokenization.

    In the example below, the token format is defined using a hierarchical structure composed of encrypted parts, literal parts, and compound parts. This structure specifies which portions of the token are encrypted and which are preserved as literals.

    The request JSON for creating a key to tokenize the SSN:

    {
  "name": "<sobject name>",
  "description": "",
  "obj_type": "AES",
  "key_ops": [
    "ENCRYPT",
    "DECRYPT",
    "APPMANAGEABLE"
  ],
  "key_size": 256,
  "fpe": {
    "format": {
      "concat": [
        {
          "min_length": 3,
          "max_length": 3,
          "char_set": [
            [
              "0",
              "9"
            ]
          ],
          "constraints": {
            "num_lt": 900,
            "num_ne": [
              0,
              666
            ]
          }
        },
        {
          "literal": [
            "-"
          ]
        },
        {
          "min_length": 2,
          "max_length": 2,
          "char_set": [
            [
              "0",
              "9"
            ]
          ],
          "constraints": {
            "num_ne": [
              0
            ]
          }
        },
        {
          "literal": [
            "-"
          ]
        },
        {
          "min_length": 4,
          "max_length": 4,
          "char_set": [
            [
              "0",
              "9"
            ]
          ],
          "constraints": {
            "num_ne": [
              0
            ]
          },
          "preserve": []
        }
      ]
    },
    "description": "<sobject description>"
  },
  "expirationDate": null,
  "enabled": true,
  "group_id": "<sobject group id>"
}

    NOTE

    For an Irreversible Tokenization key type, the key_ops list does not include the DECRYPT operation.

  2. The security object must be an AES security object. FPE cannot be used with any other security object type.

3.3 Tokenize by Calling Encrypt API

When the security object is created, the response contains the "kid" field. This field is required for calling the encrypt or decrypt APIs. The following example illustrates how to tokenize the number 123-12-1234.

The API to tokenize is /crypto/v1/encrypt.

JSON Request:

{
  "alg": "AES",
  "plain": "MTIzLTEyLTEyMzQ=",
  "mode": "FPE",
  "key": {
    "name": "17-May-Key"
  }
}

Where, the value of the plain field is base64 encoded SSN. The result of decoding the "plain" field is “123-12-1234”, the original data provided.

Response:

{
  "kid": "<tokenization sobject kid>",
  "cipher": "NDU2LTU2LTQ1Njc="
}

The “cipher” is a base64 encoded value of the token. The result of decoding the"cipher" field is “456-45-4567”.

3.4 Detokenize by Calling Decrypt API

The API to de-tokenize is /crypto/v1/keys/{kid}/decrypt.

JSON Request:

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

Response:

{
  "kid": "<tokenization sobject kid>",
  "plain": "MTIzLTEyLTEyMzQ="
}

The "plain" field is the base64 encoded value of the original data. The result of decoding the "plain" field is “123-12-1234”, the original data provided.

NOTE

The /crypto/v1/keys/{kid}/decrypt API is not supported for Irreversible Tokenization key type.

3.5 Masking Using API

When detokenizing, it is recommended to mask part of the token such as replacing it with asterisks. For example, if an application only needs to display the last four digits of a detokenized identifier, there is no need to reveal the entire value. This can be achieved by specifying a mask field that defines which characters should be masked during detokenization.

Consider the following encrypted part used to define masking behavior:

{
  "min_length": 10,
  "max_length": 10,
  "char_set": [
    [
      "0",
      "9"
    ]
  ],
  "mask": [
    0,
    -1
  ]
}

This definition represents a datatype consisting of 10 numeric digits, where the first and last characters are masked during detokenization.

It is also possible to mask entire parts at a time. For instance, masking the first group of digits:

{
  "concat": [
    {
      "min_length": 3,
      "max_length": 3,
      "char_set": [
        [
          "0",
          "9"
        ]
      ],
      "constraints": {
        "num_lt": 900,
        "num_ne": [
          0,
          666
        ]
      }
    },
    {
      "literal": [
        "-"
      ]
    },
    {
      "min_length": 2,
      "max_length": 2,
      "char_set": [
        [
          "0",
          "9"
        ]
      ],
      "constraints": {
        "num_ne": [
          0
        ]
      }
    },
    {
      "literal": [
        "-"
      ]
    },
    {
      "min_length": 4,
      "max_length": 4,
      "char_set": [
        [
          "0",
          "9"
        ]
      ],
      "constraints": {
        "num_ne": [
          0
        ]
      },
      "mask": "all"
    }
  ]
}

To mask a Compound subpart, specify true instead of "all".

4.0 Masked Detokenization

4.1 Using Fortanix DSM User Interface

You can also generate a masked detokenization key by updating the configuration in the App permissions settings in the detailed view of a Fortanix DSM app created in Section 2.3: Creating an Application.

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

  1. Navigate to the Apps menu item in the DSM left navigation panel.

  2. Select the application created in Section 2.3: Creating an Application.

  3. Click the icon under Groups column. The following dialog box appears on the screen:

    Figure 8: 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.

4.2 Using API Schema

You can detokenize the cipher text and mask specific characters specified in the masking pattern using the Fortanix DSM REST API (One-Time Masked Detokenization).

You can detokenize the cipher text and mask specific characters specified in the masking pattern by passing the masked parameter as true in the request body.

Request body:

{
  "alg": "AES",
  "mode": "FPE",
  "cipher": "NDU2LTU2LTQ1Njc=",
  "masked": true
}

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

Response:

{
  "kid": "<tokenization sobject kid>",
  "plain": "MTIzLTEyLSoqKio="
}

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

For more information about Fortanix API, refer to Fortanix DSM REST API.

5.0 References

Related articles