Package com.eatthepath.noise.component

Interface NoiseCipher

public interface NoiseCipher
A Noise cipher is a stateless object that encrypts and decrypts data for use in a Noise protocol. Noise cipher implementations must operate in AEAD mode, produce a 16-byte AEAD tag when encrypting data, and verify a 16-byte AEAD tag when decrypting data.

  • Method Summary

    Modifier and Type
    Method
    Description
    Key
    buildKey(byte[] keyBytes)
    Converts an array of bytes into a Key instance suitable for use with this cipher.
    default byte[]
    decrypt(Key key, long nonce, byte[] associatedData, byte[] ciphertext)
    Decrypts the given ciphertext and verifies its AEAD tag using the given key, nonce, and associated data.
    int
    decrypt(Key key, long nonce, byte[] associatedData, int aadOffset, int aadLength, byte[] ciphertext, int ciphertextOffset, int ciphertextLength, byte[] plaintext, int plaintextOffset)
    Decrypts the given ciphertext and verifies its AEAD tag.
    default ByteBuffer
    decrypt(Key key, long nonce, ByteBuffer associatedData, ByteBuffer ciphertext)
    Decrypts the given ciphertext and verifies its AEAD tag using the given key, nonce, and associated data.
    int
    decrypt(Key key, long nonce, ByteBuffer associatedData, ByteBuffer ciphertext, ByteBuffer plaintext)
    Decrypts the given ciphertext and verifies its AEAD tag using the given key, nonce, and associated data.
    default byte[]
    encrypt(Key key, long nonce, byte[] associatedData, byte[] plaintext)
    Encrypts the given plaintext using the given key, nonce, and associated data.
    int
    encrypt(Key key, long nonce, byte[] associatedData, int aadOffset, int aadLength, byte[] plaintext, int plaintextOffset, int plaintextLength, byte[] ciphertext, int ciphertextOffset)
    Encrypts the given plaintext using the given key, nonce, and associated data.
    default ByteBuffer
    encrypt(Key key, long nonce, ByteBuffer associatedData, ByteBuffer plaintext)
    Encrypts the given plaintext using the given key, nonce, and associated data.
    int
    encrypt(Key key, long nonce, ByteBuffer associatedData, ByteBuffer plaintext, ByteBuffer ciphertext)
    Encrypts the given plaintext using the given key, nonce, and associated data.
    default int
    getCiphertextLength(int plaintextLength)
    Returns the size of a buffer needed to hold the ciphertext produced by encrypting a plaintext of the given length (the length of the plaintext plus the length of an AEAD tag).
    static NoiseCipher
    getInstance(String noiseCipherName)
    Returns a NoiseCipher instance that implements the named cipher algorithm.
    String
    getName()
    Returns the name of this Noise cipher as it would appear in a full Noise protocol name.
    default int
    getPlaintextLength(int ciphertextLength)
    Returns the size of a buffer needed to hold the plaintext produced by decrypting a ciphertext of the given length (the length of the ciphertext minus the length of the AEAD tag).
    default Key
    rekey(Key key)
    Generates a new pseudo-random key as a function of the given key.

  • Method Details

    • getInstance

      static NoiseCipher getInstance(String noiseCipherName) throws NoSuchAlgorithmException

      Returns a NoiseCipher instance that implements the named cipher algorithm. This method recognizes the following cipher names:

      ChaChaPoly
      Returns a Noise cipher implementation backed by the Cipher returned by the most preferred security provider that supports the "ChaCha20-Poly1305" cipher transformation
      AESGCM
      Returns a Noise cipher implementation backed by the Cipher returned by the most preferred security provider that supports the "AES/GCM/NoPadding" cipher transformation

      Every implementation of the Java platform is required to support the "AES/GCM/NoPadding" cipher transformation, which underpins the "AESGCM" Noise cipher.

      Parameters:
      noiseCipherName - the name of the Noise cipher algorithm for which to return a concrete NoiseCipher implementation
      Returns:
      a concrete NoiseCipher implementation for the given algorithm name
      Throws:
      NoSuchAlgorithmException - if the given name is "ChaChaPoly" and the "ChaCha20-Poly1305" cipher transformation is not supported by any security provider in the current JVM
      IllegalArgumentException - if the given name is not a known Noise cipher name
      See Also:

    • getName

      String getName()
      Returns the name of this Noise cipher as it would appear in a full Noise protocol name.
      Returns:
      the name of this Noise cipher as it would appear in a full Noise protocol name

    • encrypt

      default ByteBuffer encrypt(Key key, long nonce, @Nullable ByteBuffer associatedData, ByteBuffer plaintext)

      Encrypts the given plaintext using the given key, nonce, and associated data. This method returns a new byte buffer sized exactly to contain the resulting ciphertext and AEAD tag.

      All plaintext.remaining() bytes starting at plaintext.position() are processed. Upon return, the plaintext buffer's position will be equal to its limit; its limit will not have changed. If associated data is provided, the same is true of the associated data buffer. The returned ciphertext buffer's position will be zero, and its limit will be equal to its capacity.

      Parameters:
      key - the key with which to encrypt the given plaintext
      nonce - a nonce, which must be unique for the given key
      associatedData - the associated data to use when calculating an AEAD tag
      plaintext - the plaintext to encrypt
      Returns:
      a new byte buffer containing the resulting ciphertext and AEAD tag
      See Also:

    • encrypt

      int encrypt(Key key, long nonce, @Nullable ByteBuffer associatedData, ByteBuffer plaintext, ByteBuffer ciphertext) throws ShortBufferException

      Encrypts the given plaintext using the given key, nonce, and associated data. Callers are responsible for ensuring that the given ciphertext buffer has enough remaining capacity to hold the resulting ciphertext and AEAD tag.

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

      Note that the ciphertext and plaintext buffers must be different, but may refer to the same underlying byte array to facilitate in-place encryption.

      Parameters:
      key - the key with which to encrypt the given plaintext
      nonce - a nonce, which must be unique for the given key
      associatedData - the associated data to use when calculating an AEAD tag
      plaintext - the plaintext to encrypt
      ciphertext - the buffer into which to write the resulting ciphertext and AEAD tag
      Returns:
      the number of bytes written into the ciphertext buffer
      Throws:
      ShortBufferException - if the given ciphertext buffer does not have enough remaining capacity to hold the resulting ciphertext and AEAD tag
      See Also:

    • encrypt

      default byte[] encrypt(Key key, long nonce, @Nullable byte[] associatedData, byte[] plaintext)
      Encrypts the given plaintext using the given key, nonce, and associated data. This method returns a new byte array sized exactly to contain the resulting ciphertext and AEAD tag.
      Parameters:
      key - the key with which to encrypt the given plaintext
      nonce - a nonce, which must be unique for the given key
      associatedData - the associated data to use when calculating an AEAD tag
      plaintext - the plaintext to encrypt
      Returns:
      a new byte array containing the resulting ciphertext and AEAD tag
      See Also:

    • encrypt

      int encrypt(Key key, long nonce, @Nullable byte[] associatedData, int aadOffset, int aadLength, byte[] plaintext, int plaintextOffset, int plaintextLength, byte[] ciphertext, int ciphertextOffset) throws ShortBufferException

      Encrypts the given plaintext using the given key, nonce, and associated data. Callers are responsible for ensuring that the given ciphertext array is large enough to hold the resulting ciphertext and AEAD tag.

      Note that the ciphertext and plaintext arrays may refer to the same array, allowing for in-place encryption.

      Parameters:
      key - the key with which to encrypt the given plaintext
      nonce - a nonce, which must be unique for the given key
      associatedData - a byte array containing the associated data (if any) to be used when encrypting the given plaintext; may be null
      aadOffset - the position within associatedData where the associated data starts; ignored if associatedData is null
      aadLength - the length of the associated data within associatedData; ignored if associatedData is null
      plaintext - a byte array containing the plaintext to encrypt
      plaintextOffset - the offset within plaintext where the plaintext begins
      plaintextLength - the length of the plaintext within plaintext
      ciphertext - a byte array into which to write the ciphertext and AEAD tag from this encryption operation
      ciphertextOffset - the position within ciphertext at which to begin writing the ciphertext and AEAD tag
      Returns:
      the number of bytes written into the ciphertext array
      Throws:
      ShortBufferException - if the ciphertext array (after its offset) is too small to hold the resulting ciphertext and AEAD tag
      IndexOutOfBoundsException - if the given plaintext length exceeds the length of the plaintext array after its offset
      See Also:

    • decrypt

      default ByteBuffer decrypt(Key key, long nonce, @Nullable ByteBuffer associatedData, ByteBuffer ciphertext) throws AEADBadTagException

      Decrypts the given ciphertext and verifies its AEAD tag using the given key, nonce, and associated data. 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. If associated data is provided, the same will be true of the associated data buffer.

      Parameters:
      key - the key with which to decrypt the given ciphertext
      nonce - a nonce, which must be unique for the given key
      associatedData - the associated data to use when verifying the AEAD tag; may be null
      ciphertext - the ciphertext 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
      See Also:

    • decrypt

      int decrypt(Key key, long nonce, @Nullable ByteBuffer associatedData, ByteBuffer ciphertext, ByteBuffer plaintext) throws AEADBadTagException, ShortBufferException

      Decrypts the given ciphertext and verifies its AEAD tag using the given key, nonce, and associated data. 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. If associated data is provided, the same will be true of the associated data buffer. 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:
      key - the key with which to decrypt the given ciphertext
      nonce - a nonce, which must be unique for the given key
      associatedData - the associated data to use when verifying the AEAD tag; may be null
      ciphertext - the ciphertext 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
      ShortBufferException - if the given plaintext buffer does not have enough remaining capacity to hold the resulting plaintext
      See Also:

    • decrypt

      default byte[] decrypt(Key key, long nonce, @Nullable byte[] associatedData, byte[] ciphertext) throws AEADBadTagException
      Decrypts the given ciphertext and verifies its AEAD tag using the given key, nonce, and associated data. This method returns a new byte array sized exactly to contain the resulting plaintext.
      Parameters:
      key - the key with which to decrypt the given ciphertext
      nonce - a nonce, which must be unique for the given key
      associatedData - the associated data to use when verifying the AEAD tag; may be null
      ciphertext - the ciphertext to decrypt
      Returns:
      a byte array 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
      See Also:

    • decrypt

      int decrypt(Key key, long nonce, @Nullable byte[] associatedData, int aadOffset, int aadLength, byte[] ciphertext, int ciphertextOffset, int ciphertextLength, byte[] plaintext, int plaintextOffset) throws AEADBadTagException, ShortBufferException

      Decrypts the given ciphertext and verifies its AEAD tag. This writes the resulting plaintext into a provided byte array.

      Note that ciphertext and plaintext may refer to the same byte array, allowing for in-place decryption.

      Parameters:
      key - the key with which to decrypt the given plaintext
      nonce - a nonce, which must be unique for the given key
      associatedData - a byte array containing the associated data (if any) to be used when verifying the AEAD tag for the given ciphertext; may be null
      aadOffset - the position within associatedData where the associated data starts; ignored if associatedData is null
      aadLength - the length of the associated data within associatedData; ignored if associatedData is null
      ciphertext - a byte array containing the ciphertext and AEAD tag to be decrypted and verified
      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
      See Also:

    • getCiphertextLength

      default int getCiphertextLength(int plaintextLength)
      Returns the size of a buffer needed to hold the ciphertext produced by encrypting a plaintext of the given length (the length of the plaintext plus the length of an AEAD tag).
      Parameters:
      plaintextLength - the length of a plaintext
      Returns:
      the length of the ciphertext that would be produced by encrypting a plaintext of the given length

    • getPlaintextLength

      default int getPlaintextLength(int ciphertextLength)
      Returns the size of a buffer needed to hold the plaintext produced by decrypting a ciphertext of the given length (the length of the ciphertext minus the length of the AEAD tag).
      Parameters:
      ciphertextLength - the length of a ciphertext
      Returns:
      the length of the plaintext that would be produced by decrypting a ciphertext of the given length

    • buildKey

      Key buildKey(byte[] keyBytes)
      Converts an array of bytes into a Key instance suitable for use with this cipher.
      Parameters:
      keyBytes - the raw bytes of the key
      Returns:
      a Key suitable for use with this cipher

    • rekey

      default Key rekey(Key key)
      Generates a new pseudo-random key as a function of the given key.
      Parameters:
      key - the key from which to derive a new key
      Returns:
      a new pseudo-random key derived from the given key