User's Guide: Tokenization

  • Last updated:
  • access_time Reading time:

The SDKMS tokenization feature eliminates the link to sensitive data and is used in credit card processing to reduce or eliminate breaches. This is a highly secure method of protecting payment credentials which includes substituting sensitive data such as credit card/ account numbers with a one-time number known as token that has no relationship to a person or their account. The 16-digit account number is replaced with a randomly generated alphanumeric ID.

SDKMS Tokenizer Security Object Data Types

Tokenizer Data Types

A security object token can be of the following data types:

  • Credit card
  • SSN
  • Custom token

Depending on the type of data the users want to protect, they can create security objects belonging to any of the three tokenizer data types. Tokenization replaces a customer’s credit card number, SSN or a custom token with a randomly generated code or token eliminating them from commerce systems, only storing a “token” that represents them.

Credit Card Tokenization

A typical credit card number comes with a 16-digit personal account number (PAN) which can be tokenised. When a merchant swipes a customer’s credit card, the PAN is automatically replaced with a format-preserving alphanumeric ID (“token”).

In SDKMS, a user can choose to tokenize certain digits of a credit card number using a pattern. There are 4 types of tokenization pattern that can be applied:

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

    In this method, a user can also choose to mask the complete token using the Add 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 ex:
    3.png
    In this method, a user can choose to mask the complete token except the last four since these digits of the credit card number are set to be visible by the user. Masking can be applied using the Add 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 1st six digits of the credit card number – 6 digits + token. For ex:
    5.png
    In this method, a user can choose to mask the complete token except the 1st six digits since these digits of the credit card number are set to be visible by the user. Masking can be applied using the Add 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 1st six digits and last four digits of the credit card number – 6 digits + token + 4 digits. For ex:
    7.png
    In this method, a user can choose to mask the complete token except the 1st six digits and 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 Add 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

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 have 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 last 4 digits. This enables representatives to verify user identities without access to the rest of the SSN.

In SDKMS, a user can choose to tokenize an SSN using the below two patterns.

  • Fully tokenize the SSN – full token. For ex:
    9.png
    In this method, a user can also choose to mask the complete token using the Add masking pattern option in the UI. The masking pattern replaces the complete token with asterisks (*), further securing the token’s identity.
    10.png
  • Tokenize all but the last four digits of the SSN – token + 4 digits. For ex:
    11.png
    In this method, a user can choose to mask the complete token except the last four digits since these digits of the SSN are set to be visible by the user. Masking can be applied using the Add masking pattern option in the UI. The masking pattern replaces the selected digits of the token with asterisks (*), further securing the token’s identity.
    12.png

Custom Tokens

A user can use this method of tokenization to protect any kind of data other than a credit card or SSN. This data type must have a minimum size of 13 which can either be numbers, hexadecimals or alphanumeric values. In this method, a user can choose to tokenize any combination of the 1st six and the last six digits in the data. For ex:

  • 1 symbol + token + 1 symbol
    13.png
  • 6 symbols + token + 6 symbols
    14.png
  • 3 symbols + token + 2 symbols
    15.png
    A user can choose to mask the corresponding tokenized values with asterisks (*), further securing the token’s identity. Masking can be applied on any combination of digits that are tokenized using the Add masking pattern option in the UI. For example, following can be the masking patterns for the custom token above.
    16.png
    17.png
    A custom token type can be:
    1. Numbers only: If your data is of type ‘number’, then use this option to create a custom token containing only numbers.
      18.png
    2. Hexadecimal only: If your data is of type ‘hexadecimal’, then use this option to create a custom token containing hexadecimal values.
      19.png
    3. Alphanumeric only: If your data is of type ‘alphanumeric’, then use this option to create a custom token containing alphanumeric values.
      20.png

Create a Tokenizer Security Object

To create a tokenizer security object, follow the steps below:

  1. Log in to your SDKMS account using the URL: https://sdkms.fortanix.com.
  2. On the SDKMS UI left panel, click the Security Objects tab, and then click the CREATE SECURITY OBJECT button in the Security Objects page.
    F1.png
                                             Figure 1: Create Tokenizer Security Object
  3. In the Add New Security Object page, enter a name for your new security object, and then select the GENERATE option, to generate a security object.
    F2.png
                                             Figure 2: Generate Tokenizer Object
  4. Select the type of security object as Tokenization.
  5. In the Data type list, select the tokenization type for the tokenizer security object. There are three data types to select from, namely:
      1. Credit Card
      2. SSN
      3. Custom Token
    F4.png
                                             Figure 4: Tokenizer Data Type
    Refer to the previous section for more details about these data types.
  6. If you want to mask your token, then select Add masking pattern. 
    F5.png
                                             Figure 5: Add Masking Pattern
  7. Move the slider below the token to choose a masking pattern.
    F6.png
                                             Figure 6: Apply Masking Pattern
  8. Enter a key size for the security object. The allowed values are, 128 bits, 192 bits and 256 bits.
    F7.png
                                             Figure 7: Select Key Size
  9. Select the permitted key operations on this security object.
    F8.png
                                             Figure 8: Select Key Operations
  10. Assign the security object to a group.
    F9.png
                                             Figure 9: Assign Security Object to Group
  11. Lastly, click GENERATE to generate a tokenizer security object.
    F10.png
                                             Figure 10: Generate Security Object
  12. The new tokenizer security object is created.
    F11.png
                                             Figure 11: Tokenizer Security Object Created

Tokenization Operations Using 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:

F12.png
                                  Figure 12: Create New Token

Generating a Token

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

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

 Request body:

{
 "alg": "AES",
 "mode": "Ff1",
 "plain": "MDEyMzQ1Njc4OTEyMzQ1Ng=="
}

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

The request response is:

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

 The base64 decoding of the returned "cipher" is “0123459120651682”. 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.

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": "Ff1",
 "cipher": "MDEyMzQ1OTEyMDY1MTY4Mg=="
}

The "cipher" field is the base64 encoded 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",
 "cipher": "MDEyMzQ1OTEyMDY1MTY4Mg=="
}

The request response is:

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

 The "plain" field is the base64 encoding of the original data. The result of decoding the "plain" field is “0123456789123456”, the original data provided.