Package com.eatthepath.noise

Interface NoiseTransportReader

All Known Subinterfaces:
NoiseTransport
public interface NoiseTransportReader

A Noise transport reader decrypts Noise transport messages. In the terminology of the Noise Protocol Framework specification, a NoiseTransportReader instance encapsulates a "cipher state" produced by "splitting" a NoiseHandshake instance.

Noise transport reader instances are stateful and are not thread-safe.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    getPlaintextLength(int ciphertextLength)
    Returns the length of the plaintext resulting from the decryption of a ciphertext of the given size.
    byte[]
    readMessage(byte[] ciphertext)
    Decrypts a Noise transport message, returning a new byte array sized exactly to contain the resulting plaintext.
    int
    readMessage(byte[] ciphertext, int ciphertextOffset, int ciphertextLength, byte[] plaintext, int plaintextOffset)
    Decrypts a Noise transport message and writes the resulting plaintext into the given byte array.
    ByteBuffer
    readMessage(ByteBuffer ciphertext)
    Decrypts a Noise transport message and verifies its AEAD tag.
    int
    readMessage(ByteBuffer ciphertext, ByteBuffer plaintext)
    Decrypts a Noise transport message and verifies its AEAD tag.
    void
    rekeyReader()
    Sets the decryption key used by this reader to a new pseudo-random key derived from the current key.

  • Method Details

    • getPlaintextLength

      int getPlaintextLength(int ciphertextLength)
      Returns the length of the plaintext resulting from the decryption of a ciphertext of the given size.
      Parameters:
      ciphertextLength - the length of a ciphertext
      Returns:
      the length of the plaintext resulting from the decryption of a ciphertext of the given size
      Throws:
      IllegalArgumentException - if the given ciphertext length is too small to contain a valid AEAD tag

    • readMessage

      ByteBuffer readMessage(ByteBuffer ciphertext) throws AEADBadTagException
      Decrypts a Noise transport message and verifies its AEAD tag. This method returns a new ByteBuffer sized exactly to contain the resulting plaintext. The returned buffer's position will be zero, and its limit and capacity will be equal to the plaintext length.

      All ciphertext.remaining() bytes starting at ciphertext.position() are processed. Upon return, the ciphertext buffer's position will be equal to its limit; its limit will not have changed.

      Parameters:
      ciphertext - the ciphertext of the Noise transport message to decrypt
      Returns:
      a ByteBuffer containing the resulting plaintext
      Throws:
      AEADBadTagException - if the AEAD tag in the given ciphertext does not match the calculated value
      IllegalArgumentException - if the given ciphertext is too short to contain a valid AEAD tag or if it is larger than the maximum allowed Noise transport message size
      See Also:

    • readMessage

      int readMessage(ByteBuffer ciphertext, ByteBuffer plaintext) throws ShortBufferException, AEADBadTagException
      Decrypts a Noise transport message and verifies its AEAD tag. This method writes the resulting plaintext into the given plaintext buffer. Callers are responsible for ensuring that the given plaintext buffer has enough remaining capacity to hold the resulting plaintext.

      All ciphertext.remaining() bytes starting at ciphertext.position() are processed. Upon return, the ciphertext buffer's position will be equal to its limit; its limit will not have changed. The plaintext buffer's position will have advanced by n, where n is the value returned by this method; the plaintext buffer's limit will not have changed.

      Parameters:
      ciphertext - the ciphertext of the Noise transport message to decrypt
      plaintext - the buffer into which to write the resulting plaintext
      Returns:
      the number of bytes written into the plaintext buffer
      Throws:
      AEADBadTagException - if the AEAD tag in the given ciphertext does not match the calculated value
      IllegalArgumentException - if the given ciphertext is too short to contain a valid AEAD tag or if it is larger than the maximum allowed Noise transport message size
      ShortBufferException - if the given plaintext buffer does not have enough remaining capacity to hold the resulting plaintext
      See Also:

    • readMessage

      byte[] readMessage(byte[] ciphertext) throws AEADBadTagException
      Decrypts a Noise transport message, returning a new byte array sized exactly to contain the resulting plaintext.
      Parameters:
      ciphertext - the ciphertext of the Noise transport message to decrypt
      Returns:
      a new byte array containing the resulting plaintext
      Throws:
      AEADBadTagException - if the AEAD tag in the given ciphertext does not match the calculated AEAD tag
      IllegalArgumentException - if the given ciphertext is too short to contain a valid AEAD tag or if it is larger than the maximum allowed Noise transport message size

    • readMessage

      int readMessage(byte[] ciphertext, int ciphertextOffset, int ciphertextLength, byte[] plaintext, int plaintextOffset) throws ShortBufferException, AEADBadTagException
      Decrypts a Noise transport message and writes the resulting plaintext into the given byte array. Note that ciphertext and plaintext may refer to the same byte array, allowing for in-place decryption.
      Parameters:
      ciphertext - the ciphertext of the Noise transport message to decrypt
      ciphertextOffset - the position within ciphertext at which to begin reading the ciphertext and AEAD tag
      ciphertextLength - the length of the ciphertext and AEAD tag within ciphertext
      plaintext - a byte array into which to write the decrypted plaintext
      plaintextOffset - the offset within plaintext where the plaintext begins
      Returns:
      the number of bytes written to plaintext
      Throws:
      AEADBadTagException - if the AEAD tag in the given ciphertext does not match the calculated value
      ShortBufferException - if plaintext is not long enough (after its offset) to contain the resulting plaintext
      IllegalArgumentException - if the given ciphertext is too short to contain a valid AEAD tag or if it is larger than the maximum allowed Noise transport message size

    • rekeyReader

      void rekeyReader()
      Sets the decryption key used by this reader to a new pseudo-random key derived from the current key. This operation must be coordinated with the sending party, otherwise messages from the sending party will be unintelligible and decrypting future messages will fail.