Package org.cryptacular

Class CiphertextHeader

java.lang.Object
org.cryptacular.CiphertextHeader
public class CiphertextHeader extends Object
Cleartext header prepended to ciphertext providing data required for decryption.

Data format:

     +---------+---------+---+----------+-------+------+
     | Version | KeyName | 0 | NonceLen | Nonce | HMAC |
     +---------+---------+---+----------+-------+------+
     |                                                 |
     +--- 4 ---+--- x ---+ 1 +--- 1 ----+-- y --+- 32 -+

Where fields are defined as follows:

  • Version - Header version format as a negative number (4-byte integer). Current version is -2.
  • KeyName - Symbolic key name encoded as UTF-8 bytes (variable length)
  • 0 - Null byte signifying the end of the symbolic key name
  • NonceLen - Nonce length in bytes (1-byte unsigned integer)
  • Nonce - Nonce bytes (variable length)
  • HMAC - HMAC-256 over preceding fields (32 bytes)

The last two fields provide support for multiple keys at the encryption provider. A common case for multiple keys is key rotation; by tagging encrypted data with a key name, an old key may be retrieved by name to decrypt outstanding data which will be subsequently re-encrypted with a new key.

Author:
Middleware Services

  • Constructor Details

    • CiphertextHeader

      public CiphertextHeader(byte[] nonce, String keyName)
      Creates a new instance with a nonce and named key.
      Parameters:
      nonce - Nonce bytes.
      keyName - Key name.

    • CiphertextHeader

      public CiphertextHeader(byte[] nonce, String keyName, Function<String,SecretKey> keyLookup)
      Creates a new instance with a nonce, named key and key lookup.
      Parameters:
      nonce - Nonce bytes.
      keyName - Key name.
      keyLookup - Key lookup function.

  • Method Details

    • getLength

      public int getLength()
      Gets the header length in bytes.
      Returns:
      Header length in bytes.

    • getNonce

      public byte[] getNonce()
      Gets the bytes of the nonce/IV.
      Returns:
      Nonce bytes.

    • getKeyName

      public String getKeyName()
      Gets the encryption key name stored in the header.
      Returns:
      Encryption key name.

    • encode

      public byte[] encode()
      Encodes the header into bytes.
      Returns:
      Byte representation of header.

    • encode

      public byte[] encode(SecretKey hmacKey)
      Encodes the header into bytes.
      Parameters:
      hmacKey - Key used to generate header HMAC.
      Returns:
      Byte representation of header.

    • computeLength

      protected int computeLength()
      Returns:
      Length of this header encoded as bytes.

    • decode

      public static CiphertextHeader decode(byte[] data, Function<String,SecretKey> keyLookup) throws EncodingException
      Creates a header from encrypted data containing a cleartext header prepended to the start.
      Parameters:
      data - Encrypted data with prepended header data.
      keyLookup - Function used to look up the secret key from the symbolic key name in the header.
      Returns:
      Decoded header.
      Throws:
      EncodingException - when ciphertext header cannot be decoded.

    • decode

      public static CiphertextHeader decode(InputStream input, Function<String,SecretKey> keyLookup) throws EncodingException, StreamException
      Creates a header from encrypted data containing a cleartext header prepended to the start.
      Parameters:
      input - Input stream that is positioned at the start of ciphertext header data.
      keyLookup - Function used to look up the secret key from the symbolic key name in the header.
      Returns:
      Decoded header.
      Throws:
      EncodingException - when ciphertext header cannot be decoded.
      StreamException - on stream IO errors.