Format Preserving Encryption

The Format Preserving Encryption (FPE) algorithm allows the user to perform crypto operations on data while preserving the format of the input data.

Important Notes

Before using FPE feature, the user must be aware of the following:

• If any outside cardinality characters are present in the input data then the user must calculate effective input data length and provide IV accordingly.

• If user has mixed cardinality in any particular data, then user must tokenize the data for each cardinality, and provide respective data chunk for each cardinality separately.

• FPE requires minimum two bytes/characters to perform encryption.

• Duplicate characters are not allowed in FPE Unicode file.

• The unicode file cannot be updated at the run time; that is, the file cannot be dynamic in nature. For example, if a user has encrypted some data using a particular file then at the time of decryption same file should be used with no addition or modification of data.

• For Hebrew or Arabic, it is recommended that the entire file should be based on one language. Otherwise, decrypted text may not meet plaintext.

• No spaces and numbers are allowed in the unicode file, except the following cases:

  • For FPE/FF1/ASCII, use of numbers are allowed.

  • For FPE/FF1v2/ASCII, use of numbers are allowed.

  • For FPE/FF3/ASCII, use of numbers are allowed.

• For Windows, the unicode file should be saved in the ANSI format and not in the UTF-8 format.

• While using CLI commands for encrypting using FPE/FF1, FPE/FF1v2, and FPE/FF3 algorithms, the value of RADIX specified by user is equal to the character count in the provided Charset.

For 8.12.1 and older releases, if the data is encrypted using CARD62, use any of the following configuration to decrypt them:

• Set Environment Variable "FPE_CARD62_Charset_Order" to 0 (False).
  For example: FPE_CARD62_Charset_Order = 0.

• Set charset order to 0 in userSpec structure using ENUM "I_T_USPEC_CARD62_CHARSET_ORDER".
  For example:
  

  I_C_SetUserSpec(I_T_USPEC_CARD62_CHARSET_ORDER, "0" , 1 , &Userspec)
  

The Userspec setting has the precedence over Environment Variable.

FPE Algorithms

FPE/AES

The algorithm supports different cardinalities for different kind of data.

• CARD10 for digits in range (0 - 9).

• CARD26 for lower case alphabets (a-z).

• CARD62 for digits (0 - 9), lower case alphabets (a - z), and upper case alphabets (A - Z).

• UNICODE for various languages. The characters to be encrypted/decrypted can be specified in File or through API.

• The location of this file is passed in the NAE session when performing encryption for the data derived from such character set. The number of characters provided in the character set file will be treated as cardinality for the input data. If the input data to be encrypted contains characters other than the ones available in the character set than it is retained as it is after encryption/decryption.

FPE is supported both in local and remote mode; however, in remote mode, only cardinality 10 is supported.

On performing Crypto operations with FPE, characters other than the supported cardinality set characters (if any) in the input data remains preserved and does not get encrypted.

Supported Functions

The following functions are supported by the FPE feature:

• I_C_Crypt_Enhanced

• I_C_CryptBulk_Enhanced

• I_C_Crypt_Enhanced_FpeFormat

How it Works

To use FPE feature, the user needs to call the Crypto API with the following arguments:

• Algorithm

• Input data based on cardinality

• IV as per input data cardinality and input data length.

• Userspec (that is, tweakalgo, tweakdata and other user-defined parameters set via setUserSpec)

User provides algorithm with configured cardinality set name.

For example:

I_C_Crypt_Enhanced(session,cipherspec,operation,iv,ivlen,indata,indatalen,outdata,outdatalen,userspec)

While using FPE in Local mode the sequence of operations performed internally is as follows:

1. Based on the algoname, cardinality is retrieved.

2. Outside cardinality characters are trimmed and preserved as they remain as is.

3. The input data (without outside cardinality characters) is translated into s-integers.

4. FPE Crypto operation is performed in s-integers.

5. The s-integers ciphertext is translated to cardinality set.

6. Outside cardinality characters are placed at their original position.

While using FPE in Remote mode (only CARD10 supported) the sequence of operations performed internally is as follows:

1. Based on algoname, the cardinality is retrieved

2. XML request is sent for Crypto

3. For XML request, the CipherTrust Manager:

   • Translates the input data into s-integers

   • Performs FPE Crypto operation in s-integers

   • Translates s-integers ciphertext to cardinality set

     Note

     • The characters out of charset in the plaintext will be preserved.
     • Special characters preservation is not supported in the remote mode.

FPE/FF1 and FPE/FF1v2

Before using the FPE/FF1 or FPE/FF1v2 feature, the user must be aware of the following:

• FPE/FF1 and FPE/FF1v2 require minimum two characters to perform encryption.

• IV is not supported in FF1 and FF1v2.

• These algorithms support FPE formats. For more information, refer to FPE Formats.

• In the case of CARD10, 26, and 62 the user-provided Charset and Radix will be ignored.

• If both Charset and UNICODE file are provided, then Charset is prioritized.

This algorithm supports different cardinalities for different types of data.

• CARD10 for digits in range 0 - 9

• CARD26 for lower case alphabets (a-z)

• CARD62 for digits (0 - 9), upper case alphabets (A - Z), and lower case alphabets (a - z)

• ASCII characters

• UNICODE for various languages. The characters to be encrypted/decrypted can be specified in File or through API.

FPE/FF3

Before using FPE/FF3 feature, the user must be aware of the following:

• FPE/FF3 requires minimum two characters to perform encryption.

• IV is not supported in FF3.

• FPE/FF3 algorithms support FPE formats. For more information, refer to FPE Formats.

• Tweak data is mandatory. If tweak algorithm is NONE, the tweak data must be of 8 bytes.

• For tweak algorithms SHA1 and SHA256, the tweak data length should be ≤ 256 characters.

This algorithm supports different cardinalities for different types of data.

• CARD10 for digits in range 0 - 9

• CARD26 for lower case alphabets (a-z)

• CARD62 for digits (0 - 9), lower case alphabets (a - z), and upper case alphabets (A - Z)

• ASCII characters

• UNICODE for various languages. The characters to be encrypted/decrypted can be specified in File or through API.

Modes of FPE Version Key

You can pass any of the following key version header modes in the FPE samples:

• 0 (NONE) - no header. This is the default value.

• 1 (External)- key version header is saved in the userspec structure. User can get version header using getUserSpec after encryption.

  Example

  CryptoSinglePart_FPE CADP_CAPI.properties j_aes_v FPE/AES/CARD10 12345 null null Username
  Password null null null null null 1
  Plain Text (Hex):31 32 33 34 35
  Encrypted Text:0 7 0 3 9
  Encrypted Text (Hex):30 37 30 33 39
  Version Header (Hex):10 00 20
  Decrypted PlainText:1 2 3 4 5
  Decrypted Text (Hex):31 32 33 34 35
  

• 2 (Internal) - key version header is in HEX format. It is saved in the first six bytes of the ciphertext.

  Example

  CryptoSinglePart_FPE CADP_CAPI.properties j_aes_v FPE/AES/CARD10 12345 null null Username
  Password null null null null null 2
  Plain Text (Hex):31 32 33 34 35
  Encrypted Text:1 0 0 0 2 0 0 7 0 3 9
  Encrypted Text (Hex):31 30 30 30 32 30 30 37 30 33 39
  Decrypted PlainText:1 2 3 4 5
  Decrypted Text (Hex):31 32 33 34 35
  

FPE Formats

Supported FPE Formats

Charset

The Character set (Charset) for UNICODE and ASCII can be provided using:

• API (using I_C_SetUserSpec)

• UNICODE file (using CADP_CAPI.properties)

Charset using API (Charset and Radix)

The Charset can be provided in the two ways:

• Complete Charset with Radix

  Example:

  Charset: abcdefghijklmnopqrstuvwxyz

  Radix: 26 (total count of characters)

• Charset range

  Example:

  Charset: 61-7A

  Radix: Not required for Charset range

You can also provide multiple Charset ranges and they must be separated by comma.
Example
0030-0039,0041-005A

Charset using UNICODE File

The number of characters provided in the character set file will be treated as cardinality for the input data.

If Charset is provided through the UNICODE file, then Radix is calculated automatically.

FPE Unicode

FPE Unicode enables you to support various languages such as German, Spanish, and Arabic.

A parameter, FPE_Unicode_File, is added in the CADP_CAPI.properties file. This parameter contains path including file name of the FPE unicode file. This FPE unicode file contains all the characters supported in this cardinality. Cardinality is calculated on the basis of number of characters present in the FPE unicode file. It differs for FPE/AES, and FPE/FF1, FPE/FF1v2, and FPE/FF3.

For FPE/AES, the FPE unicode file contains only UTF8 characters, and the number of characters in this file should be greater than 10 and less than 256.

For FPE/FF1, FPE/FF1v2, and FPE/FF3, the FPE unicode file can contain either UTF8, or UTF16, or UTF32 character types. The number of characters in this file should be greater than 10.

IV should be as per input data cardinality and input data length.

Sample FPE Unicode File

The content of the sample FPE unicode file shown below includes all the supported Spanish characters. So all characters other than these will be considered as special characters and will be preserved.

á
é
í
ó
ú
ñ
Ñ
ü
Ü
¿
¡
Á
É
Í
Ó
Ú)

Use Cases

Below are a few use cases to explain the usage of FPE/AES/UNICODE.