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.
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>
- 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)
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 .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);
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.
- 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
- Every input data error throws an
- Implement FF3
Read LICENSE.txt attached to the project