fernet-java8

This is a work-in-progress implementation of the Fernet Spec using Java 8. The goal is to use only native Java constructs to avoid pulling in any dependencies so the library would be more generally usable. It also takes advantage of the Java 8 time objects to add type-safety.

I am actively soliciting feedback on this library. If you have any thoughts, please submit an issue.

Features

• fully-validated against the scenarios in the Fernet Spec
• type-safety by using Java 8 time objects (no confusing milliseconds vs seconds after the epoch)
• no dependencies!
• pluggable mechanism so you can specify your own:
  • Clock
  • TTL / max clock skew
  • payload validator
  • payload transformation (i.e. to POJO)

Adding this to your project

This library is available in The Central Repository. If you use Maven, you can add it to your project object model using:

<dependency>
  <groupId>com.macasaet.fernet</groupId>
  <artifactId>fernet-java8</artifactId>
  <version>0.5.1</version>
</dependency>

For more details, see: The Central Repository

If you use a dependency manager system or build system other than Maven, see Dependency Information.

Alternatively, you can just download the latest jar and add it to your classpath. It does not have any dependencies.

Note that this library requires Java 8 or higher.

Examples

Create a new key:

final Key key = Key.generateKey(random);

Deserialise an existing key:

final Key key = new Key("cw_0x689RpI-jtRR7oE8h_eQsKImvJapLeSbXpwF4e4=");

Create a token:

final Token token = Token.generate(random, key, "secret message");

Deserialise an existing token:

final Token token = Token.fromString("gAAAAAAdwJ6wAAECAwQFBgcICQoLDA0ODy021cpGVWKZ_eEwCGM4BLLF_5CV9dOPmrhuVUPgJobwOz7JcbmrR64jVmpU4IwqDA==");

Validate the token:

final Validator<String> validator = new StringValidator() {
};
final String payload = token.validateAndDecrypt(key, validator);

When validating, an exception is thrown if the token is not valid. In this example, the payload is just the decrypted cipher text portion of the token. If you choose to store structured data in the token (e.g. JSON), or a pointer to a domain object (e.g. a username), you can implement your own Validator<T> that returns the type of POJO your application expects.

Storing Sensitive Data on the Client

For an example of how to securely store sensitive data on the client (e.g. browser cookie), see the classes in src/test/java. The class AutofillExample shows a full end-to-end example.

JAX-RS

For an example of how to use Fernet Tokens to secure a REST API implemented using JAX-RS or Jersey, see the classes in src/test/java. The test class JaxRsTest shows a full end-to-end example. It includes an example of integrating with external storage.

Why Fernet, Why not JWT?

Valid concerns have been raised about the JWT specification:

• No Way, JOSE! Javascript Object Signing and Encryption is a Bad Standard That Everyone Should Avoid
• JSON Web Tokens should be avoided

In addition, Fernet has been available in Python's cryptography package for some time. It is also used by Keystone, the OpenStack identity service.

Open Issues

The core functionality is complete and unit-tested. In addition, several examples have been implemented to ensure the API works with common use cases. I plan to release version 1.0.0 soon.

Development

Mutation Testing and Test Coverage

This project uses PITest to evaluate test coverage and test effectiveness. The latest report is available here. To generate a report for a local build, run:

mvn clean install site

Releasing to The Central Repository

mvn --batch-mode -Prelease clean release:clean release:prepare release:perform

Prior Art

There is a library called fernet-java, which as of version 0.0.1-SNAPSHOT, uses Guava and commons-codec.