fpe - Format Preserving Encryption Implementation in Java

Format-preserving encryption (FPE) is designed for data that is not necessarily binary. In particular, given any finite set of symbols, like the decimal numerals, a method for FPE transforms data that is formatted as a sequence of the symbols in such a way that the encrypted form of the data has the same format, including the length, as the original data. Thus, an FPE-encrypted SSN would be a sequence of nine decimal digits.

An implementation of the NIST approved Format Preserving Encryption (FPE) in Java.

NIST Recommendation SP 800-38G

Installation

Check requirements section before installation

You can pull it from the central Maven repositories:

<dependency>
  <groupId>com.idealista</groupId>
  <artifactId>format-preserving-encryption</artifactId>
  <version>1.0.0</version>
</dependency>

Features

• Out of the box working algorithm with an easy API
• Custom Domain (any subset of character could be used)
• Custom Pseudo Random Function (cipher algorithm)

Example Usage

Input data

During Format Preserving Encryption object creation, input data shall meet the following requirements:

• radix ∈ [ 2 .. 2¹⁶ ]
• radix^minlen= 100
• 2 <= minlen < maxlen <= 2^32
• key is an AES Key, must be 16, 24 or 32 bytes length

If default tweak option is used:

• tweak length should be lower that tweakMaxLength

Code

// with default values
FormatPreservingEncryption formatPreservingEncryption = FormatPreservingEncryptionBuilder
        .ff1Implementation()
        .withDefaultDomain()
        .withDefaultPseudoRandomFunction(anyKey)
        .withDefaultLengthRange()
        .build();
//with custom inputs
FormatPreservingEncryption formatPreservingEncryption = FormatPreservingEncryptionBuilder
        .ff1Implementation()
        .withDomain(new BasicAlphabetDomain())
        .withPseudoRandomFunction(new DefaultPseudoRandomFunction(anyKey))
        .withLengthRange(new LengthRange(2, 20))
        .build();
//usage
String cipherText = formatPreservingEncryption.encrypt(aText, aTweak);
String plainText = formatPreservingEncryption.decrypt(aText, aTweak);

Custom Inputs

Domain

GenericDomain represents the easiest implementation of a domain. A valid domain should be able to transform text input to numeral string and numeral string to text.

The domain of an instance has two elements:

• Alphabet: A subset of characters that are valid to create a text input for an instance.
• Transformers: Functions (Class) that are able to transform text to numeral string or numeral string to text.

The default domain includes the lower case letters of the English alphabet

Pseudo Random Function (PRF)

A given designated cipher function. By default AES-CBC with 128, 192 or 256 based on the input key is used.

Input text length

The minimum length of a text for a given domain is defined using the rules at the start of this section. Although the maximum length is not defined, you must be aware of performance issues when using a very large text.

Requirements

The library has been tested with Apache Maven 3.3.3 and JDK 1.6-1.7. Newer versions of Apache Maven/JDK should work but could also present issues.

Usage of Java Cryptography Extension (JCE) requires to download an install Policy Files for target java distribution: 1.6, 1.7, 1.8

Design choices

• FF1Algorithm is a pure implementation without checking, input data is checked during object creation or before invoke the algorithm. Be awere of this when using the library and use the FormatPreservingEncryptionBuilder class.
• Every input data error throws an IllegalArgumentException

TODO

• Implement FF3

License

Read LICENSE.txt attached to the project

Contribution

Read CONTRIBUTION.md