This website does readability filtering of other pages. All styles, scripts, forms and ads are stripped. If you want your website excluded or have other feedback, use this form.

GitHub - idealista/format-preserving-encryption-java: Format-Preserving Encryption Implementation in Java

Skip to content

Sign in or Sign up


Join GitHub today

GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.

Sign up

Format-Preserving Encryption Implementation in Java java fpe format-preserving-encryption ff1 encryption cryptography
  1. Java 99.2%
  2. Shell 0.8%
Java Shell Clone or download

Clone with HTTPS

Use Git or checkout with SVN using the web URL.

Download ZIP

Launching GitHub Desktop...

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop...

If nothing happens, download GitHub Desktop and try again.

Launching Xcode...

If nothing happens, download Xcode and try again.

Launching Visual Studio...

If nothing happens, download the GitHub extension for Visual Studio and try again.

Find file Switch branches/tags develop master Nothing to show Nothing to show Fetching latest commit… Cannot retrieve the latest commit at this time. Permalink Failed to load latest commit information. .github add .github with contribution guide Sep 29, 2017 build update permissions Sep 29, 2017 src remove explicit round indexes Sep 27, 2017 .gitignore move validation to object creation Sep 27, 2017 .travis.yml update travis ossrh credentials Sep 29, 2017 add empty changelog Sep 26, 2017 LICENSE.txt add license readme and pom Sep 1, 2017 add .github with contribution guide Sep 29, 2017 logo.gif add logo Sep 26, 2017 pom.xml complete distribution management Oct 2, 2017

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 DefaultPseudarandomFunction(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



You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. Press h to open a hovercard with more details.