Package com.macasaet.fernet

Class Key

java.lang.Object
com.macasaet.fernet.Key
public class Key
extends java.lang.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​(java.lang.String string)  

  • Method Summary

    Modifier and Type Method Description
    protected byte[] decrypt​(byte[] cipherText, javax.crypto.spec.IvParameterSpec initializationVector)
    Decrypt the payload of a Fernet token.
    byte[] encrypt​(byte[] payload, javax.crypto.spec.IvParameterSpec initializationVector)
    Encrypt a payload to embed in a Fernet token
    boolean equals​(java.lang.Object obj)  
    static Key generateKey()
    Generate a random key
    static Key generateKey​(java.security.SecureRandom random)
    Generate a random key
    protected java.lang.String getCipherTransformation()  
    protected java.util.Base64.Encoder getEncoder()  
    protected java.lang.String getEncryptionAlgorithm()  
    protected byte[] getEncryptionKey()
    Warning: Modifying the returned byte array will write through to this object.
    protected javax.crypto.spec.SecretKeySpec getEncryptionKeySpec()  
    protected java.lang.String getSigningAlgorithm()  
    protected byte[] getSigningKey()
    Warning: Modifying the returned byte array will write through to this object.
    protected java.security.Key getSigningKeySpec()  
    protected int getTokenPrefixBytes()  
    int hashCode()  
    java.lang.String serialise()  
    byte[] sign​(byte version, java.time.Instant timestamp, javax.crypto.spec.IvParameterSpec initializationVector, byte[] cipherText)
    Generate an HMAC SHA-256 signature from the components of a Fernet token.
    protected byte[] sign​(byte version, java.time.Instant timestamp, javax.crypto.spec.IvParameterSpec initializationVector, byte[] cipherText, java.io.ByteArrayOutputStream byteStream)  
    void writeTo​(java.io.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 Details

    • 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​(java.lang.String string)
      Parameters:
      string - a Base 64 URL string in the format Signing-key (128 bits) || Encryption-key (128 bits)

  • Method Details

    • generateKey

      public static Key generateKey()
      Generate a random key
      Returns:
      a new shared secret key

    • generateKey

      public static Key generateKey​(java.security.SecureRandom random)
      Generate a random key
      Parameters:
      random - source of entropy
      Returns:
      a new shared secret key

    • sign

      public byte[] sign​(byte version, java.time.Instant timestamp, javax.crypto.spec.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, javax.crypto.spec.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, javax.crypto.spec.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 java.lang.String serialise()
      Returns:
      the Base 64 URL representation of this Fernet key

    • writeTo

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class java.lang.Object

    • equals

      public boolean equals​(java.lang.Object obj)
      Overrides:
      equals in class java.lang.Object

    • sign

      protected byte[] sign​(byte version, java.time.Instant timestamp, javax.crypto.spec.IvParameterSpec initializationVector, byte[] cipherText, java.io.ByteArrayOutputStream byteStream) throws java.io.IOException
      Throws:
      java.io.IOException

    • getSigningKeySpec

      protected java.security.Key getSigningKeySpec()
      Returns:
      an HMAC SHA-256 key for signing the token

    • getEncryptionKeySpec

      protected javax.crypto.spec.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 java.lang.String getSigningAlgorithm()

    • getEncryptionAlgorithm

      protected java.lang.String getEncryptionAlgorithm()

    • getEncoder

      protected java.util.Base64.Encoder getEncoder()

    • getCipherTransformation

      protected java.lang.String getCipherTransformation()