Giter Club home page Giter Club logo

format-preserving-encryption-java's Introduction

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

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

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

format-preserving-encryption-java's People

Contributors

dependabot[bot] avatar hf-kklein avatar jmonterrubio avatar rfrail3 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

format-preserving-encryption-java's Issues

minLenght < maxLength issue

Hi,
the NIST Recommendation SP 800-38G document specify that the parameters minLenght and maxLength can be equals, but in your implementation it's required to be 2 distinct values.
Am i wrong?

[FEATURE]

Description

[Make check method in FormatPreservingEncryption protected]

Why is this needed?

[If the check method was protected I could extend the class and add some additional checks for example maybe based on regular expressions on a need basis]

Additional Information

[Since the class is not marked as final I assume there is no harm in allowing this. Do pls note new to this project. In case there is another way to achieve this please advise. Thanks]

Generate same cypher for any length string

Prerequisites

Description

I have successfully used the library to Encrypt and Decrypt values. See below;

Raw Value=1234567890123456, Encrypted=5959499404198841, Decrypted=1234567890123456
Raw Value=MNEMONIC, Encrypted= XXZI9ob, Decrypted=MNEMONIC
Raw Value=SOMEVALU, Encrypted=TC6WQj21, Decrypted=SOMEVALU
Raw Value=SOM, Encrypted=qVI, Decrypted=SOM
Raw Value=SOME, Encrypted=mJry, Decrypted=SOME
Raw Value=SOMEV, Encrypted=j4b4f, Decrypted=SOMEV

As you can see my requirement is that user would be storing the encrypted values in thier database and they would want to search on these encrypted values using LIKE '%' but this won't work because it generates different value depending on the length of the string. Is there anyway I can restrict the library to generate the value to be as follows;

Raw Value=SOMEVALU, Encrypted=TC6WQj21, Decrypted=SOMEVALU
Raw Value=SOM, Encrypted=TC6, Decrypted=SOM
Raw Value=SOME, Encrypted=TC6W, Decrypted=SOME
Raw Value=SOMEV, Encrypted=TC6WQ, Decrypted=SOMEV

Or am I missing the whole point?

Versions

1.0.0

Add Maven Wrapper

Prerequisites

Description

Add Maven Wrapper (https://github.com/takari/maven-wrapper) to integrate Maven and avoid the need to have and specific version of Maven installed

Expected behavior:

Execute Maven goals using the embedded Maven Wrapper:

$ ./mvnw test

Actual behavior:

Actually requires an external installation of Maven with a specific version (Maven 3.3.3 or higher).

Null pointer exception when sample usage testing

Prerequisites

Description

I got a null pointer exception when sample usage testing

Steps to Reproduce

  1. Add this project library to maven dependency
  2. Ran the below code
    // with default values
    FormatPreservingEncryption formatPreservingEncryption = FormatPreservingEncryptionBuilder
    .ff1Implementation()
    .withDefaultDomain()
    .withDefaultPseudoRandomFunction("laki".getBytes())
    .withDefaultLengthRange()
    .build();

//usage
String cipherText = formatPreservingEncryption.encrypt("12121", "mytweak".getBytes());
String plainText = formatPreservingEncryption.decrypt(cipherText, "mytweak".getBytes());

    System.out.println(cipherText);
    System.out.println(plainText);

Expected behavior:
Should print cipher text and plain text
Actual behavior:

got a null pointer exception

Exception in thread "main" java.lang.NullPointerException
at com.idealista.fpe.config.GenericTransformations.transform(GenericTransformations.java:37)
at com.idealista.fpe.config.GenericDomain.transform(GenericDomain.java:25)
at com.idealista.fpe.FormatPreservingEncryption.encrypt(FormatPreservingEncryption.java:28)
at experiment.EncryptionTest.main(EncryptionTest.java:81)

Reproduces how often:
100%

Versions

1.0.0

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.