Package com.macasaet.fernet

Class Token

java.lang.Object
com.macasaet.fernet.Token
public class Token
extends java.lang.Object
A Fernet token.

Copyright © 2017 Carlos Macasaet.

Author:
Carlos Macasaet

  • Constructor Summary

    Constructors 
    Modifier Constructor Description
    protected Token​(byte version, java.time.Instant timestamp, javax.crypto.spec.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​(java.lang.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, java.lang.String plainText)
    Convenience method to generate a new Fernet token with a string payload.
    static Token generate​(java.security.SecureRandom random, Key key, byte[] payload)
    Generate a new Fernet token.
    static Token generate​(java.security.SecureRandom random, Key key, java.lang.String plainText)
    Convenience method to generate a new Fernet token with a string payload.
    protected static javax.crypto.spec.IvParameterSpec generateInitializationVector​(java.security.SecureRandom random)  
    protected static byte[] generateInitializationVectorBytes​(java.security.SecureRandom random)  
    protected byte[] getCipherText()
    Warning: modifications to the returned array will write through to this object.
    protected java.util.Base64.Encoder getEncoder()  
    protected byte[] getHmac()
    Warning: modifications to the returned array will write through to this object.
    javax.crypto.spec.IvParameterSpec getInitializationVector()  
    java.time.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​(java.io.DataInputStream stream, int numBytes)  
    java.lang.String serialise()  
    java.lang.String toString()  
    <T> T validateAndDecrypt​(Key key, Validator<T> validator)
    Check the validity of this token.
    protected byte[] validateAndDecrypt​(Key key, java.time.Instant earliestValidInstant, java.time.Instant latestValidInstant)  
    <T> T validateAndDecrypt​(java.util.Collection<? extends Key> keys, Validator<T> validator)
    Check the validity of this token against a collection of keys.
    void writeTo​(java.io.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 Details

    • Token

      protected Token​(byte version, java.time.Instant timestamp, javax.crypto.spec.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 Details

    • 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​(java.io.DataInputStream stream, int numBytes) throws java.io.IOException
      Throws:
      java.io.IOException

    • fromString

      public static Token fromString​(java.lang.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, java.lang.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​(java.security.SecureRandom random, Key key, java.lang.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​(java.security.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​(java.util.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, java.time.Instant earliestValidInstant, java.time.Instant latestValidInstant)

    • serialise

      public java.lang.String serialise()
      Returns:
      the Base 64 URL encoding of this token in the form Version | Timestamp | IV | Ciphertext | HMAC

    • writeTo

      public void writeTo​(java.io.OutputStream outputStream) throws java.io.IOException
      Write the raw bytes of this token to the specified output stream.
      Parameters:
      outputStream - the target
      Throws:
      java.io.IOException - if data cannot be written to the underlying stream

    • getVersion

      public byte getVersion()
      Returns:
      the Fernet specification version of this token

    • getTimestamp

      public java.time.Instant getTimestamp()
      Returns:
      the time that this token was generated

    • getInitializationVector

      public javax.crypto.spec.IvParameterSpec getInitializationVector()
      Returns:
      the initialisation vector used to encrypt the token contents

    • toString

      public java.lang.String toString()
      Overrides:
      toString in class java.lang.Object

    • generateInitializationVector

      protected static javax.crypto.spec.IvParameterSpec generateInitializationVector​(java.security.SecureRandom random)

    • generateInitializationVectorBytes

      protected static byte[] generateInitializationVectorBytes​(java.security.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 java.util.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