Package org.cryptacular

Class CiphertextHeaderV2

java.lang.Object
org.cryptacular.CiphertextHeader
org.cryptacular.CiphertextHeaderV2
public class CiphertextHeaderV2 extends CiphertextHeader
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

    • CiphertextHeaderV2

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

  • Method Details

    • setKeyLookup

      public void setKeyLookup(Function<String,SecretKey> keyLookup)
      Sets the function to resolve keys from CiphertextHeader.keyName.
      Parameters:
      keyLookup - Key lookup function.

    • encode

      public byte[] encode()
      Description copied from class: CiphertextHeader
      Encodes the header into bytes.
      Overrides:
      encode in class CiphertextHeader
      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()
      Overrides:
      computeLength in class CiphertextHeader
      Returns:
      Length of this header encoded as bytes.

    • decode

      public static CiphertextHeaderV2 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 CiphertextHeaderV2 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.