Package com.macasaet.fernet

Class Token

  • public class Token
extends Object
    A Fernet token.

    Copyright © 2017 Carlos Macasaet.

    Author:
    Carlos Macasaet

    • 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

        protected static Token fromBytes​(byte[] bytes)

      • 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​(Random 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​(Random 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

      • generateInitializationVector

        protected static IvParameterSpec generateInitializationVector​(Random random)

      • generateInitializationVectorBytes

        protected static byte[] generateInitializationVectorBytes​(Random 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

      • 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