JarCastingFernet Java
This is an 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>1.4.2</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();
or
final Key key = Key.generateKey(customRandom);
Deserialise an existing key:
final Key key = new Key("cw_0x689RpI-jtRR7oE8h_eQsKImvJapLeSbXpwF4e4=");
Create a token:
final Token token = Token.generate(key, "secret message");
or
final Token token = Token.generate(customRandom, 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.
Use a custom time-to-live:
final Validator<String> validator = new StringValidator() {
public TemporalAmount getTimeToLive() {
return Duration.ofHours(4);
}
};
The default time-to-live is 60 seconds, but in this example, it's overridden to 4 hours.
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 / JSR 311
For details on how to use Fernet tokens to secure JAX-RS endpoints, see the fernet-jersey-auth submodule. If you're using the Jersey implementation of JAX-RS, you can use that module directly. TokenInjectionIT contains an example of injecting a Fernet token into an endpoint parameter. SecretInjectionIT contains an example of injecting a Fernet token payload into an endpoint parameter.
AWS Secrets Manager
For details on how to store Fernet keys using AWS Secrets Manager, see the submodule fernet-aws-secrets-manager-rotator. It includes a Lambda Function to enable key rotation.
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:
./mvnw clean install site
Releasing to The Central Repository
./mvnw --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.
License
Copyright 2017 Carlos Macasaet
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.