Package com.macasaet.fernet

Class Key

java.lang.Object

com.macasaet.fernet.Key

public class Key
extends Object

A Fernet shared secret key.

Copyright © 2017 Carlos Macasaet.

Author:

Carlos Macasaet

Constructor Summary

Constructors

Constructor	Description
Key(byte[] concatenatedKeys)	Create a Key from a payload containing the signing and encryption key.
Key(byte[] signingKey, byte[] encryptionKey)	Create a Key from individual components.
Key(String string)

Method Summary

Modifier and Type	Method	Description
protected byte[]	decrypt(byte[] cipherText, IvParameterSpec initializationVector)	Decrypt the payload of a Fernet token.
byte[]	encrypt(byte[] payload, IvParameterSpec initializationVector)	Encrypt a payload to embed in a Fernet token
boolean	equals(Object obj)
static Key	generateKey()	Generate a random key
static Key	generateKey(SecureRandom random)	Generate a random key
protected String	getCipherTransformation()
protected Base64.Encoder	getEncoder()
protected String	getEncryptionAlgorithm()
protected byte[]	getEncryptionKey()	Warning: Modifying the returned byte array will write through to this object.
protected SecretKeySpec	getEncryptionKeySpec()
protected String	getSigningAlgorithm()
protected byte[]	getSigningKey()	Warning: Modifying the returned byte array will write through to this object.
protected Key	getSigningKeySpec()
protected int	getTokenPrefixBytes()
int	hashCode()
String	serialise()
byte[]	sign(byte version, Instant timestamp, IvParameterSpec initializationVector, byte[] cipherText)	Generate an HMAC SHA-256 signature from the components of a Fernet token.
protected byte[]	sign(byte version, Instant timestamp, IvParameterSpec initializationVector, byte[] cipherText, ByteArrayOutputStream byteStream)
void	writeTo(OutputStream outputStream)	Write the raw bytes of this key to the specified output stream.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Key

public Key(byte[] signingKey,
           byte[] encryptionKey)

Create a Key from individual components.

Parameters:

signingKey - a 128-bit (16 byte) key for signing tokens.

encryptionKey - a 128-bit (16 byte) key for encrypting and decrypting token contents.

Key

public Key(byte[] concatenatedKeys)

Create a Key from a payload containing the signing and encryption key.

Parameters:

concatenatedKeys - an array of 32 bytes of which the first 16 is the signing key and the last 16 is the encryption/decryption key

Key

public Key(String string)

Parameters:

string - a Base 64 URL string in the format Signing-key (128 bits) || Encryption-key (128 bits)

Method Detail

generateKey

public static Key generateKey()

Generate a random key

Returns:

a new shared secret key

generateKey

public static Key generateKey(SecureRandom random)

Generate a random key

Parameters:

random - source of entropy

Returns:

a new shared secret key

sign

public byte[] sign(byte version,
                   Instant timestamp,
                   IvParameterSpec initializationVector,
                   byte[] cipherText)

Generate an HMAC SHA-256 signature from the components of a Fernet token.

Parameters:

version - the Fernet version number

timestamp - the seconds after the epoch that the token was generated

initializationVector - the encryption and decryption initialization vector

cipherText - the encrypted content of the token

Returns:

the HMAC signature

encrypt

public byte[] encrypt(byte[] payload,
                      IvParameterSpec initializationVector)

Encrypt a payload to embed in a Fernet token

Parameters:

payload - the raw bytes of the data to store in a token

initializationVector - random bytes from a high-entropy source to initialise the AES cipher

Returns:

the AES-encrypted payload. The length will always be a multiple of 16 (128 bits).

See Also:

decrypt(byte[], IvParameterSpec)

decrypt

protected byte[] decrypt(byte[] cipherText,
                         IvParameterSpec initializationVector)

Decrypt the payload of a Fernet token.

Warning: Do not call this unless the cipher text has first been verified. Attempting to decrypt a cipher text that has been tampered with will leak whether or not the padding is correct and this can be used to decrypt stolen cipher text.

Parameters:

cipherText - the verified padded encrypted payload of a token. The length must be a multiple of 16 (128 bits).

initializationVector - the random bytes used in the AES encryption of the token

Returns:

the decrypted payload

See Also:

encrypt(byte[], IvParameterSpec)

serialise

public String serialise()

Returns:

the Base 64 URL representation of this Fernet key

writeTo

public void writeTo(OutputStream outputStream)
             throws IOException

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

Parameters:

outputStream - the target

Throws:

IOException - if the underlying I/O device cannot be written to

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

sign

protected byte[] sign(byte version,
                      Instant timestamp,
                      IvParameterSpec initializationVector,
                      byte[] cipherText,
                      ByteArrayOutputStream byteStream)
               throws IOException

Throws:

IOException

getSigningKeySpec

protected Key getSigningKeySpec()

Returns:

an HMAC SHA-256 key for signing the token

getEncryptionKeySpec

protected SecretKeySpec getEncryptionKeySpec()

Returns:

the AES key for encrypting and decrypting the token payload

getSigningKey

protected byte[] getSigningKey()

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

Returns:

the raw underlying signing key bytes

getEncryptionKey

protected byte[] getEncryptionKey()

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

Returns:

the raw underlying encryption key bytes

getTokenPrefixBytes

protected int getTokenPrefixBytes()

getSigningAlgorithm

protected String getSigningAlgorithm()

getEncryptionAlgorithm

protected String getEncryptionAlgorithm()

getEncoder

protected Base64.Encoder getEncoder()

getCipherTransformation

protected String getCipherTransformation()