com.southernstorm.noise.protocol

## Class SymmetricState

- java.lang.Object
- - com.southernstorm.noise.protocol.SymmetricState

- All Implemented Interfaces:
    Destroyable, Cloneable

      class SymmetricState
      extends Object
      implements Destroyable, Cloneable

  Symmetric state for helping manage a Noise handshake.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `SymmetricState(String cipherName, String hashName, String patternId)` Constructs a new symmetric state object.
    `protected` | `SymmetricState(SymmetricState o)` Copy constructor for cloning

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `SymmetricState` | `clone()` I2P
    `int` | `decryptAndHash(byte[] ciphertext, int ciphertextOffset, byte[] plaintext, int plaintextOffset, int length)` Decrypts a block of ciphertext and mixes it into the handshake hash.
    `int` | `decryptOnly(byte[] ciphertext, int ciphertextOffset, byte[] plaintext, int plaintextOffset, int length)` I2P - Same as decryptAndHash() but without the post-mixHash(), for N only.
    `void` | `destroy()` Destroys all sensitive state in the current object.
    `int` | `encryptAndHash(byte[] plaintext, int plaintextOffset, byte[] ciphertext, int ciphertextOffset, int length)` Encrypts a block of plaintext and mixes the ciphertext into the handshake hash.
    `int` | `encryptOnly(byte[] plaintext, int plaintextOffset, byte[] ciphertext, int ciphertextOffset, int length)` I2P - Same as encryptAndHash() but without the post-mixHash(), for N only.
    `byte[]` | `getChainingKey()` I2P for getting chaining key for siphash calculation
    `byte[]` | `getHandshakeHash()` Gets the current value of the handshake hash.
    `int` | `getMACLength()` Gets the length of MAC values in the current state.
    `String` | `getProtocolName()` Gets the name of the Noise protocol.
    `void` | `mixHash(byte[] data, int offset, int length)` Mixes data into the handshake hash.
    `void` | `mixKey(byte[] data, int offset, int length)` Mixes data into the chaining key.
    `void` | `mixPreSharedKey(byte[] key)` Mixes a pre-shared key into the chaining key and handshake hash.
    `void` | `mixPublicKey(DHState dh)` Mixes a pre-supplied public key into the handshake hash.
    `void` | `mixPublicKeyIntoCK(DHState dh)` Mixes a pre-supplied public key into the chaining key.
    `CipherStatePair` | `split()` Splits the symmetric state into two ciphers for session encryption.
    `CipherStatePair` | `split(byte[] secondaryKey, int offset, int length)` Splits the symmetric state into two ciphers for session encryption, and optionally mixes in a secondary symmetric key.
    `String` | `toString()` I2P debug

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### SymmetricState

          public SymmetricState(String cipherName,
                                String hashName,
                                String patternId)
                         throws NoSuchAlgorithmException

      Constructs a new symmetric state object. Noise protocol name is hardcoded.
      Parameters:
        `cipherName` - The name of the cipher within protocolName.
        `hashName` - The name of the hash within protocolName.
      Throws:
        `NoSuchAlgorithmException` - The cipher or hash algorithm in the protocol name is not supported.

    - #### SymmetricState

          protected SymmetricState(SymmetricState o)
                            throws CloneNotSupportedException

      Copy constructor for cloning
      Throws:
        `CloneNotSupportedException`

  - ### Method Detail

    - #### clone

          public SymmetricState clone()
                               throws CloneNotSupportedException

      I2P
      Overrides:
        `clone` in class `Object`
      Throws:
        `CloneNotSupportedException`

    - #### decryptAndHash

          public int decryptAndHash(byte[] ciphertext,
                                    int ciphertextOffset,
                                    byte[] plaintext,
                                    int plaintextOffset,
                                    int length)
                             throws ShortBufferException,
                                    BadPaddingException

      Decrypts a block of ciphertext and mixes it into the handshake hash.
      Parameters:
        `ciphertext` - The buffer containing the ciphertext to decrypt.
        `ciphertextOffset` - The offset within the ciphertext buffer of the first byte of ciphertext data.
        `plaintext` - The buffer to place the plaintext in. This can be the same as the ciphertext buffer.
        `plaintextOffset` - The first offset within the plaintext buffer to place the plaintext.
        `length` - The length of the incoming ciphertext plus the MAC tag.
      Returns:
        The length of the plaintext with the MAC tag stripped off.
      Throws:
        `ShortBufferException` - There is not enough space in the plaintext buffer for the decrypted data.
        `BadPaddingException` - The MAC value failed to verify. The plaintext and ciphertext buffers can be the same for in-place decryption. In that case, ciphertextOffset must be identical to plaintextOffset.

    - #### decryptOnly

          public int decryptOnly(byte[] ciphertext,
                                 int ciphertextOffset,
                                 byte[] plaintext,
                                 int plaintextOffset,
                                 int length)
                          throws ShortBufferException,
                                 BadPaddingException

      I2P - Same as decryptAndHash() but without the post-mixHash(), for N only.
      Throws:
        `ShortBufferException`
        `BadPaddingException`

    - #### destroy

          public void destroy()

      Description copied from interface: `Destroyable`
      Destroys all sensitive state in the current object.
      Specified by:
        `destroy` in interface `Destroyable`

    - #### encryptAndHash

          public int encryptAndHash(byte[] plaintext,
                                    int plaintextOffset,
                                    byte[] ciphertext,
                                    int ciphertextOffset,
                                    int length)
                             throws ShortBufferException

      Encrypts a block of plaintext and mixes the ciphertext into the handshake hash.
      Parameters:
        `plaintext` - The buffer containing the plaintext to encrypt.
        `plaintextOffset` - The offset within the plaintext buffer of the first byte or plaintext data.
        `ciphertext` - The buffer to place the ciphertext in. This can be the same as the plaintext buffer.
        `ciphertextOffset` - The first offset within the ciphertext buffer to place the ciphertext and the MAC tag.
        `length` - The length of the plaintext.
      Returns:
        The length of the ciphertext plus the MAC tag.
      Throws:
        `ShortBufferException` - There is not enough space in the ciphertext buffer for the encrypted data plus MAC value. The plaintext and ciphertext buffers can be the same for in-place encryption. In that case, plaintextOffset must be identical to ciphertextOffset. There must be enough space in the ciphertext buffer to accomodate length + getMACLength() bytes of data starting at ciphertextOffset.

    - #### encryptOnly

          public int encryptOnly(byte[] plaintext,
                                 int plaintextOffset,
                                 byte[] ciphertext,
                                 int ciphertextOffset,
                                 int length)
                          throws ShortBufferException

      I2P - Same as encryptAndHash() but without the post-mixHash(), for N only.
      Throws:
        `ShortBufferException`

    - #### getChainingKey

          public byte[] getChainingKey()

      I2P for getting chaining key for siphash calculation
      Returns:
        a copy

    - #### getHandshakeHash

          public byte[] getHandshakeHash()

      Gets the current value of the handshake hash.
      Returns:
        The handshake hash. This must not be modified by the caller. The handshake hash value is only of use to the application after split() has been called.

    - #### getMACLength

          public int getMACLength()

      Gets the length of MAC values in the current state.
      Returns:
        The length of the MAC value for the underlying cipher or zero if the cipher has not yet been initialized with a key.

    - #### getProtocolName

          public String getProtocolName()

      Gets the name of the Noise protocol.
      Returns:
        The protocol name.

    - #### mixHash

          public void mixHash(byte[] data,
                              int offset,
                              int length)

      Mixes data into the handshake hash.
      Parameters:
        `data` - The buffer containing the data to mix in.
        `offset` - The offset of the first data byte to mix in.
        `length` - The number of bytes to mix in.

    - #### mixKey

          public void mixKey(byte[] data,
                             int offset,
                             int length)

      Mixes data into the chaining key.
      Parameters:
        `data` - The buffer containing the data to mix in.
        `offset` - The offset of the first data byte to mix in.
        `length` - The number of bytes to mix in.

    - #### mixPreSharedKey

          public void mixPreSharedKey(byte[] key)

      Mixes a pre-shared key into the chaining key and handshake hash.
      Parameters:
        `key` - The pre-shared key value.

    - #### mixPublicKey

          public void mixPublicKey(DHState dh)

      Mixes a pre-supplied public key into the handshake hash.
      Parameters:
        `dh` - The object containing the public key.

    - #### mixPublicKeyIntoCK

          public void mixPublicKeyIntoCK(DHState dh)

      Mixes a pre-supplied public key into the chaining key.
      Parameters:
        `dh` - The object containing the public key.

    - #### split

          public CipherStatePair split()

      Splits the symmetric state into two ciphers for session encryption.
      Returns:
        The pair of ciphers for sending and receiving.

    - #### split

          public CipherStatePair split(byte[] secondaryKey,
                                       int offset,
                                       int length)

      Splits the symmetric state into two ciphers for session encryption, and optionally mixes in a secondary symmetric key.
      Parameters:
        `secondaryKey` - The buffer containing the secondary key.
        `offset` - The offset of the first secondary key byte.
        `length` - The length of the secondary key in bytes, which must be either 0 or 32.
      Returns:
        The pair of ciphers for sending and receiving.
      Throws:
        `IllegalArgumentException` - The length is not 0 or 32.

    - #### toString

          public String toString()

      I2P debug
      Overrides:
        `toString` in class `Object`