Treehash (Bouncy Castle Library 1.52 API Specification)
Date: 2015-03-01

org.bouncycastle.pqc.crypto.gmss

## Class Treehash

- java.lang.Object
- - org.bouncycastle.pqc.crypto.gmss.Treehash

-     public class Treehash
      extends java.lang.Object

  This class implements a treehash instance for the Merkle tree traversal algorithm. The first node of the stack is stored in this instance itself, additional tail nodes are stored on a tailstack.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Treehash(Digest name, byte[][] statByte, int[] statInt)` This constructor regenerates a prior treehash object
    `Treehash(java.util.Vector tailStack, int maxHeight, Digest digest)` Constructor

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` Destroys a treehash instance after the top node was taken for authentication path.
    `byte[]` | `getFirstNode()` returns the first node stored in treehash instance itself
    `int` | `getFirstNodeHeight()` Returns the top node height
    `int` | `getLowestNodeHeight()` Returns the height of the lowest node stored either in treehash or on the stack.
    `byte[]` | `getSeedActive()` returns the active seed
    `byte[][]` | `getStatByte()` Returns the status byte array used by the GMSSPrivateKeyASN.1 class
    `int[]` | `getStatInt()` Returns the status int array used by the GMSSPrivateKeyASN.1 class
    `java.util.Vector` | `getTailStack()` Returns the tailstack
    `void` | `initialize()` initializes the treehash instance.
    `void` | `initializeSeed(byte[] seedIn)` Method to initialize the seeds needed for the precomputation of right nodes.
    `void` | `setFirstNode(byte[] hash)` This method sets the first node stored in the treehash instance itself
    `java.lang.String` | `toString()` returns a String representation of the treehash instance
    `void` | `update(GMSSRandom gmssRandom, byte[] leaf)` Calculates one update of the treehash instance, i.e. creates a new leaf and hashes if possible
    `void` | `updateNextSeed(GMSSRandom gmssRandom)` updates the nextSeed of this treehash instance one step needed for the schedulng of the seeds
    `boolean` | `wasFinished()` Method to check whether the instance has been finished or not
    `boolean` | `wasInitialized()` Method to check whether the instance has been initialized or not

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

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

- - ### Constructor Detail

    - #### Treehash

          public Treehash(Digest name,
                  byte[][] statByte,
                  int[] statInt)

      This constructor regenerates a prior treehash object
      Parameters:
        `name` - an array of strings, containing the name of the used hash function and PRNG and the name of the corresponding provider
        `statByte` - status bytes
        `statInt` - status ints

    - #### Treehash

          public Treehash(java.util.Vector tailStack,
                  int maxHeight,
                  Digest digest)

      Constructor
      Parameters:
        `tailStack` - a vector element where the stack nodes are stored
        `maxHeight` - maximal height of the treehash instance
        `digest` - an array of strings, containing the name of the used hash function and PRNG and the name of the corresponding provider

  - ### Method Detail

    - #### initializeSeed

          public void initializeSeed(byte[] seedIn)

      Method to initialize the seeds needed for the precomputation of right nodes. Should be initialized with index 3*2^i for treehash_i
      Parameters:
        `seedIn` -

    - #### initialize

          public void initialize()

      initializes the treehash instance. The seeds must already have been initialized to work correctly.

    - #### update

          public void update(GMSSRandom gmssRandom,
                    byte[] leaf)

      Calculates one update of the treehash instance, i.e. creates a new leaf and hashes if possible
      Parameters:
        `gmssRandom` - an instance of the PRNG
        `leaf` - The byte value of the leaf needed for the update

    - #### destroy

          public void destroy()

      Destroys a treehash instance after the top node was taken for authentication path.

    - #### getLowestNodeHeight

          public int getLowestNodeHeight()

      Returns the height of the lowest node stored either in treehash or on the stack. It must not be set to infinity (as mentioned in the paper) because this cases are considered in the computeAuthPaths method of JDKGMSSPrivateKey
      Returns:
        Height of the lowest node

    - #### getFirstNodeHeight

          public int getFirstNodeHeight()

      Returns the top node height
      Returns:
        Height of the first node, the top node

    - #### wasInitialized

          public boolean wasInitialized()

      Method to check whether the instance has been initialized or not
      Returns:
        true if treehash was already initialized

    - #### wasFinished

          public boolean wasFinished()

      Method to check whether the instance has been finished or not
      Returns:
        true if treehash has reached its maximum height

    - #### getFirstNode

          public byte[] getFirstNode()

      returns the first node stored in treehash instance itself
      Returns:
        the first node stored in treehash instance itself

    - #### getSeedActive

          public byte[] getSeedActive()

      returns the active seed
      Returns:
        the active seed

    - #### setFirstNode

          public void setFirstNode(byte[] hash)

      This method sets the first node stored in the treehash instance itself
      Parameters:
        `hash` -

    - #### updateNextSeed

          public void updateNextSeed(GMSSRandom gmssRandom)

      updates the nextSeed of this treehash instance one step needed for the schedulng of the seeds
      Parameters:
        `gmssRandom` - the prng used for the seeds

    - #### getTailStack

          public java.util.Vector getTailStack()

      Returns the tailstack
      Returns:
        the tailstack

    - #### getStatByte

          public byte[][] getStatByte()

      Returns the status byte array used by the GMSSPrivateKeyASN.1 class
      Returns:
        The status bytes

    - #### getStatInt

          public int[] getStatInt()

      Returns the status int array used by the GMSSPrivateKeyASN.1 class
      Returns:
        The status ints

    - #### toString

          public java.lang.String toString()

      returns a String representation of the treehash instance
      Overrides:
        `toString` in class `java.lang.Object`