Format Preserving Encryption for PKCS#11

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 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 algorithm requires minimum two bytes/characters to perform encryption.

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

• Version keys with internal header are supported for symmetric encryption algorithms in local mode only.

Supported Functions

The following functions are supported by the FPE feature:

• C_EncryptInit

• C_Encrypt

• C_DecryptInit

• C_Decrypt

How it Works

To use FPE feature, the user needs to call the Crypto API C_EncryptInit/ C_DecryptInit to set the following:

• Algorithm

• Tweak algorithm

• Tweak data

• Charset

• Cardinality

• Unicode

For example:

CK_FPE_GENERIC_PARAMETER ff31params;
char * char_sets = "0123456789ABCDEabcde";
char * tweak_algo = “SHA256”;
ff31params.mode = CS_UTF8; // Cardinality/UTF modes
ff31params->charsetlen = strlen(char_sets); // Charset
memcpy(ff31params->charset, char_sets , ff31params->charsetlen);
ff31params->radix = ff31params->charsetlen; // Radix
ff31params->tweakAlgolen = strlen(tweak_algo);
memcpy(ff31params->tweakAlgo, tweak_algo, ff31params->tweakAlgolen);
CK_MECHANISM mechEncryptionFF31 = { CKM_THALES_FF3_1, &ff31params, sizeof(ff31params) };
C_EncryptInit(hSession, &mechEncryptionFF31, hKey);

Then call the Crypto API C_Encrypt/ C_Decrypt with data to be encrypted/decrypted respectively.

For example:

C_Encrypt(hSession, pPlainText, plainTextLen, pCipherTextBuffer, &cipherTextLen);

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

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

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

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

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

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

While using FF3-1 in Remote mode, the sequence of operations performed internally is as follows:

1. XML request is sent for Crypto

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

Supported Algorithms

FPE

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

• Two charsets ASCII and UNICODE (UTF 8, UTF 16, and UTF 32) are supported in local mode only.

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

• Tweak data is optional but highly recommended.

• Supported UTF modes are:

  • UTF8

  • UTF16

  • UTF32

• FPE algorithm supports Tweak data with 8 bytes of maximum length.

FF1

Before using the FF1 algorithm, the user must be aware of the following:

• IV is not supported in FF1.

• Two cardinalities ASCII and UNICODE are supported in local mode only.

• Tweak data is optional but highly recommended.

• Supported UTF modes are:

  • UTF8

  • UTF16

  • UTF32

• (optional) FF1 algorithm supports Tweak data with 8 bytes of maximum length.

FF3-1

Before using FF3-1 feature, the user must be aware of the following:

• IV is not supported in FF3-1.

• Cardinality CARD10 is supported in both modes remote and local mode.

• Cardinality CARD26, 62, ASCII and UNICODE supported in local mode only.

• Supported UTF modes are:

  • UTF8

  • UTF16

  • UTF32

• For cardinalities (CARD10, 26, and 62), you can skip providing the charset, charset length, and radix.

• For ASCII, the charset length must be between 2 to 255, and radix is calculated based on the charset length.

• Tweak data is mandatory. If tweak algorithm is NONE, the tweak data must be of 7 bytes for FF3-1.

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

Cardinalities

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

Note

CARD10, 26 and 62 are only supported with FF3-1.

Charset

• ASCII - for ascii characters

• UNICODE - for various languages

The Character set (Charset) for UNICODE and ASCII can be provided with Radix as below example:

• Charset: abcdefghijklmnopqrstuvwxyz

• Radix: 26 (total count of characters)

Note

The plaintext must be in the HEX format if the charset range uses UTF32 mode.

Use Cases

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