Package com.macasaet.fernet

Class Token

java.lang.Object

com.macasaet.fernet.Token

public class Token
extends Object

A Fernet token.

Copyright © 2017 Carlos Macasaet.

Author:

Carlos Macasaet

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Token(byte version, Instant timestamp, IvParameterSpec initializationVector, byte[] cipherText, byte[] hmac)	Initialise a new Token from raw components.

Method Summary

Modifier and Type	Method	Description
static Token	fromBytes(byte[] bytes)	Read a Token from bytes.
static Token	fromString(String string)	Deserialise a Base64 URL Fernet token string.
static Token	generate(Key key, byte[] payload)	Convenience method to generate a new Fernet token.
static Token	generate(Key key, String plainText)	Convenience method to generate a new Fernet token with a string payload.
static Token	generate(SecureRandom random, Key key, byte[] payload)	Generate a new Fernet token.
static Token	generate(SecureRandom random, Key key, String plainText)	Convenience method to generate a new Fernet token with a string payload.
protected static IvParameterSpec	generateInitializationVector(SecureRandom random)
protected static byte[]	generateInitializationVectorBytes(SecureRandom random)
protected byte[]	getCipherText()	Warning: modifications to the returned array will write through to this object.
protected Base64.Encoder	getEncoder()
protected byte[]	getHmac()	Warning: modifications to the returned array will write through to this object.
IvParameterSpec	getInitializationVector()
Instant	getTimestamp()
byte	getVersion()
boolean	isValidSignature(Key key)	Recompute the HMAC signature of the token with the stored shared secret key.
protected static byte[]	read(DataInputStream stream, int numBytes)
String	serialise()
String	toString()
<T> T	validateAndDecrypt(Key key, Validator<T> validator)	Check the validity of this token.
protected byte[]	validateAndDecrypt(Key key, Instant earliestValidInstant, Instant latestValidInstant)
<T> T	validateAndDecrypt(Collection<? extends Key> keys, Validator<T> validator)	Check the validity of this token against a collection of keys.
void	writeTo(OutputStream outputStream)	Write the raw bytes of this token to the specified output stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Token

protected Token(byte version,
                Instant timestamp,
                IvParameterSpec initializationVector,
                byte[] cipherText,
                byte[] hmac)

Initialise a new Token from raw components. No validation of the signature is performed. However, the other fields are validated to ensure they conform to the Fernet specification.

Warning: Subsequent modifications to the input arrays will write through to this object.

Parameters:

version - The version of the Fernet token specification. Currently, only 0x80 is supported.

timestamp - the time the token was generated

initializationVector - the randomly-generated bytes used to initialise the encryption cipher

cipherText - the encrypted the encrypted payload

hmac - the signature of the token

Method Detail

fromBytes

public static Token fromBytes(byte[] bytes)

Read a Token from bytes. This does NOT validate that the token was generated using a valid Key.

Parameters:

bytes - a Fernet token in the form Version | Timestamp | IV | Ciphertext | HMAC

Returns:

a new Token

Throws:

IllegalTokenException - if the input string cannot be a valid token irrespective of key or timestamp.

read

protected static byte[] read(DataInputStream stream,
                             int numBytes)
                      throws IOException

Throws:

IOException

fromString

public static Token fromString(String string)

Deserialise a Base64 URL Fernet token string. This does NOT validate that the token was generated using a valid Key.

Parameters:

string - the Base 64 URL encoding of a token in the form Version | Timestamp | IV | Ciphertext | HMAC

Returns:

a new Token

Throws:

IllegalTokenException - if the input string cannot be a valid token irrespective of key or timestamp

generate

public static Token generate(Key key,
                             String plainText)

Convenience method to generate a new Fernet token with a string payload.

Parameters:

key - the secret key for encrypting plainText and signing the token

plainText - the payload to embed in the token

Returns:

a unique Fernet token

generate

public static Token generate(SecureRandom random,
                             Key key,
                             String plainText)

Convenience method to generate a new Fernet token with a string payload.

Parameters:

random - a source of entropy for your application

key - the secret key for encrypting plainText and signing the token

plainText - the payload to embed in the token

Returns:

a unique Fernet token

generate

public static Token generate(Key key,
                             byte[] payload)

Convenience method to generate a new Fernet token.

Parameters:

key - the secret key for encrypting payload and signing the token

payload - the unencrypted data to embed in the token

Returns:

a unique Fernet token

generate

public static Token generate(SecureRandom random,
                             Key key,
                             byte[] payload)

Generate a new Fernet token.

Parameters:

random - a source of entropy for your application

key - the secret key for encrypting payload and signing the token

payload - the unencrypted data to embed in the token

Returns:

a unique Fernet token

validateAndDecrypt

public <T> T validateAndDecrypt(Key key,
                                Validator<T> validator)

Check the validity of this token.

Parameters:

key - the secret key against which to validate the token

validator - an object that encapsulates the validation parameters (e.g. TTL)

Returns:

the decrypted, deserialised payload of this token

Throws:

TokenValidationException - if key was NOT used to generate this token

validateAndDecrypt

public <T> T validateAndDecrypt(Collection<? extends Key> keys,
                                Validator<T> validator)

Check the validity of this token against a collection of keys. Use this if you have implemented key rotation.

Parameters:

keys - the active keys which may have been used to generate token

validator - an object that encapsulates the validation parameters (e.g. TTL)

Returns:

the decrypted, deserialised payload of this token

Throws:

TokenValidationException - if none of the keys were used to generate this token

validateAndDecrypt

protected byte[] validateAndDecrypt(Key key,
                                    Instant earliestValidInstant,
                                    Instant latestValidInstant)

serialise

public String serialise()

Returns:

the Base 64 URL encoding of this token in the form Version | Timestamp | IV | Ciphertext | HMAC

writeTo

public void writeTo(OutputStream outputStream)
             throws IOException

Write the raw bytes of this token to the specified output stream.

Parameters:

outputStream - the target

Throws:

IOException - if data cannot be written to the underlying stream

getVersion

public byte getVersion()

Returns:

the Fernet specification version of this token

getTimestamp

public Instant getTimestamp()

Returns:

the time that this token was generated

getInitializationVector

public IvParameterSpec getInitializationVector()

Returns:

the initialisation vector used to encrypt the token contents

toString

public String toString()

Overrides:

toString in class Object

generateInitializationVector

protected static IvParameterSpec generateInitializationVector(SecureRandom random)

generateInitializationVectorBytes

protected static byte[] generateInitializationVectorBytes(SecureRandom random)

isValidSignature

public boolean isValidSignature(Key key)

Recompute the HMAC signature of the token with the stored shared secret key.

Parameters:

key - the shared secret key against which to validate the token

Returns:

true if and only if the signature on the token was generated using the supplied key

getEncoder

protected Base64.Encoder getEncoder()

getCipherText

protected byte[] getCipherText()

Warning: modifications to the returned array will write through to this object.

Returns:

the raw encrypted payload bytes

getHmac

protected byte[] getHmac()

Warning: modifications to the returned array will write through to this object.

Returns:

the HMAC 256 signature of this token