iF2007 / format-preserving-encryption-java

Format-Preserving Encryption Implementation in Java

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Logo Build Status

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


Check requirements section before installation

You can pull it from the central Maven repositories:



  • 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 .. 216 ]
  • radixminlen= 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


// with default values
FormatPreservingEncryption formatPreservingEncryption = FormatPreservingEncryptionBuilder
//with custom inputs
FormatPreservingEncryption formatPreservingEncryption = FormatPreservingEncryptionBuilder
        .withDomain(new BasicAlphabetDomain())
        .withPseudoRandomFunction(new DefaultPseudoRandomFunction(anyKey))
        .withLengthRange(new LengthRange(2, 20))

String cipherText = formatPreservingEncryption.encrypt(aText, aTweak);
String plainText = formatPreservingEncryption.decrypt(aText, aTweak);

Custom Inputs


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.


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


  • Implement FF3


Read LICENSE.txt attached to the project




Format-Preserving Encryption Implementation in Java

License:Apache License 2.0


Language:Java 99.2%Language:Shell 0.8%