net.i2p.router.crypto.ratchet

## Class RatchetTagSet

- java.lang.Object
- - net.i2p.router.crypto.ratchet.RatchetTagSet

- All Implemented Interfaces:
    TagSetHandle
  Direct Known Subclasses:
    SingleTagSet

      class RatchetTagSet
      extends Object
      implements TagSetHandle

  Manages session tags and keys for a single ratchet direction with automatic key generation, supporting both inbound lookahead and on-demand outbound operations For outbound, uses very little memory. Tags and keys are generated on demand. See proposal 144. For inbound, generates tags in advance, maintaining minSize lookahead. Keys are generated as required. Caller must synch on all methods.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected SessionKey` | `_key`
    `(package private) static int` | `DEBUG_IB_NSR`
    `(package private) static int` | `DEBUG_OB_NSR`
    `(package private) static int` | `DEBUG_SINGLE_ES`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `RatchetTagSet(HKDF hkdf, HandshakeState state, SessionKey rootKey, SessionKey data, long date)` Outbound NSR Tagset
    `` | `RatchetTagSet(HKDF hkdf, SessionKey rootKey, SessionKey data, long date, int tagsetid, int keyid)` Outbound ES Tagset
    `` | `RatchetTagSet(HKDF hkdf, SessionTagListener lsnr, HandshakeState state, SessionKey rootKey, SessionKey data, long date, int minSize, int maxSize)` Inbound NSR Tagset
    `` | `RatchetTagSet(HKDF hkdf, SessionTagListener lsnr, PublicKey remoteKey, SessionKey rootKey, SessionKey data, long date, int tagsetid, int keyid, int minSize, int maxSize)` Inbound ES Tagset
    `protected` | `RatchetTagSet(SessionTagListener lsnr, SessionKey rootKey, long date, long timeout)` For SingleTagSet

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()`
    `SessionKeyAndNonce` | `consume(RatchetSessionTag tag)` inbound only
    `RatchetSessionTag` | `consumeNext()` Public for outbound only.
    `SessionKeyAndNonce` | `consumeNextKey()` For outbound, call after consumeNextTag().
    `boolean` | `getAcked()` For inbound, returns true after first consume() call.
    `SessionKey` | `getAssociatedKey()` The root key for the tag set.
    `long` | `getCreated()` For inbound and outbound: creation time, for debugging only
    `long` | `getDate()` For inbound and outbound: last used time Expiration is getDate() + getTimeout().
    `int` | `getDebugID()` A unique ID for debugging only
    `long` | `getExpiration()` For inbound and outbound: Expiration.
    `HandshakeState` | `getHandshakeState()` For inbound/outbound NSR only, else null.
    `int` | `getID()` The TagSet ID, starting at 0.
    `NextSessionKey` | `getNextKey()` Next Forward Key if applicable (outbound ES and we're running low).
    `KeyPair` | `getNextKeys()` Next Forward KeyPair if applicable (we're running low).
    `SessionKey` | `getNextRootKey()` Root key for the next DH ratchet.
    `PublicKey` | `getRemoteKey()` The far-end's public key.
    `long` | `getTimeout()` For inbound and outbound: Idle timeout interval.
    `int` | `remaining()` tags remaining
    `void` | `setDate(long when)` For inbound and outbound: last used time
    `int` | `size()` unused tags generated
    `String` | `toString()`

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

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

- - ### Field Detail

    - #### _key

          protected final SessionKey _key

    - #### DEBUG_IB_NSR

          static final int DEBUG_IB_NSR

      See Also:
        Constant Field Values

    - #### DEBUG_OB_NSR

          static final int DEBUG_OB_NSR

      See Also:
        Constant Field Values

    - #### DEBUG_SINGLE_ES

          static final int DEBUG_SINGLE_ES

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### RatchetTagSet

          public RatchetTagSet(HKDF hkdf,
                               HandshakeState state,
                               SessionKey rootKey,
                               SessionKey data,
                               long date)

      Outbound NSR Tagset
      Parameters:
        `date` - For outbound: creation time

    - #### RatchetTagSet

          public RatchetTagSet(HKDF hkdf,
                               SessionKey rootKey,
                               SessionKey data,
                               long date,
                               int tagsetid,
                               int keyid)

      Outbound ES Tagset
      Parameters:
        `date` - For outbound: creation time

    - #### RatchetTagSet

          public RatchetTagSet(HKDF hkdf,
                               SessionTagListener lsnr,
                               HandshakeState state,
                               SessionKey rootKey,
                               SessionKey data,
                               long date,
                               int minSize,
                               int maxSize)

      Inbound NSR Tagset
      Parameters:
        `date` - For inbound: creation time

    - #### RatchetTagSet

          public RatchetTagSet(HKDF hkdf,
                               SessionTagListener lsnr,
                               PublicKey remoteKey,
                               SessionKey rootKey,
                               SessionKey data,
                               long date,
                               int tagsetid,
                               int keyid,
                               int minSize,
                               int maxSize)

      Inbound ES Tagset
      Parameters:
        `date` - For inbound: creation time

    - #### RatchetTagSet

          protected RatchetTagSet(SessionTagListener lsnr,
                                  SessionKey rootKey,
                                  long date,
                                  long timeout)

      For SingleTagSet

  - ### Method Detail

    - #### clear

          public void clear()

    - #### consume

          public SessionKeyAndNonce consume(RatchetSessionTag tag)

      inbound only
      Returns:
        associated SessionKey or null if not found.

    - #### consumeNext

          public RatchetSessionTag consumeNext()

      Public for outbound only. Used internally for inbound. Call before consumeNextKey();
      Returns:
        a tag or null if we ran out

    - #### consumeNextKey

          public SessionKeyAndNonce consumeNextKey()

      For outbound, call after consumeNextTag(). Also called by consume() to catch up for inbound.
      Returns:
        a key and nonce, non-null

    - #### getAcked

          public boolean getAcked()

      For inbound, returns true after first consume() call. For outbound, returns true after first consumeNextKey() call.

    - #### getAssociatedKey

          public SessionKey getAssociatedKey()

      The root key for the tag set. Used to match the OB and IB ES tagset 0, where both will have the same root key. Not used for cryptographic operations after setup.

    - #### getCreated

          public long getCreated()

      For inbound and outbound: creation time, for debugging only

    - #### getDate

          public long getDate()

      For inbound and outbound: last used time Expiration is getDate() + getTimeout().

    - #### getDebugID

          public int getDebugID()

      A unique ID for debugging only

    - #### getExpiration

          public long getExpiration()

      For inbound and outbound: Expiration. Expiration is getDate() + getTimeout() if acked. May be shorter if not acked.

    - #### getHandshakeState

          public HandshakeState getHandshakeState()

      For inbound/outbound NSR only, else null. MUST be cloned before processing NSR.

    - #### getID

          public int getID()

      The TagSet ID, starting at 0. After that = 1 + my key id + his key id

    - #### getNextKey

          public NextSessionKey getNextKey()

      Next Forward Key if applicable (outbound ES and we're running low). Null if NSR or inbound or remaining is sufficient. Once non-null, will be constant for the remaining life of the tagset.
      Returns:
        key or null

    - #### getNextKeys

          public KeyPair getNextKeys()

      Next Forward KeyPair if applicable (we're running low). Null if remaining is sufficient. Once non-null, will be constant for the remaining life of the tagset.
      Returns:
        keys or null

    - #### getNextRootKey

          public SessionKey getNextRootKey()

      Root key for the next DH ratchet. Should only be needed for ES, but valid for NSR also.
      Returns:
        key

    - #### getRemoteKey

          public PublicKey getRemoteKey()

      The far-end's public key. Valid for NSR and inbound ES tagsets. Returns null for outbound ES tagsets.

    - #### getTimeout

          public long getTimeout()

      For inbound and outbound: Idle timeout interval. Expiration is getDate() + getTimeout().

    - #### remaining

          public int remaining()

      tags remaining
      Returns:
        0 - 65536

    - #### setDate

          public void setDate(long when)

      For inbound and outbound: last used time

    - #### size

          public int size()

      unused tags generated
      Returns:
        0 for outbound

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`