net.i2p.router.crypto.ratchet

## Class RatchetSKM

- java.lang.Object
- - net.i2p.crypto.SessionKeyManager
  - - net.i2p.router.crypto.ratchet.RatchetSKM

- All Implemented Interfaces:
    SessionTagListener

      public class RatchetSKM
      extends SessionKeyManager
      implements SessionTagListener

  Session key manager for ratchet encryption.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected RouterContext` | `_context`
    `(package private) static long` | `SESSION_LIFETIME_MAX_MS` Keep unused inbound session tags around for this long (a few minutes longer than session tags are used on the outbound side so that no reasonable network lag can cause failed decrypts) This is also the max idle time for an outbound session.
    `(package private) static long` | `SESSION_PENDING_DURATION_MS`
    `(package private) static long` | `SESSION_TAG_DURATION_MS` Let outbound session tags sit around for this long before expiring them.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RatchetSKM(RouterContext context)` For the router SKM only.
    `RatchetSKM(RouterContext context, Destination dest)` ECIES only.
    `RatchetSKM(RouterContext context, Destination dest, EncType type)` The session key manager is constructed and accessed through the client manager.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) void` | `ackRequested(PublicKey target, int id, int n)`
    `boolean` | `addTag(RatchetSessionTag tag, RatchetTagSet ts)` Map the tag to this tagset.
    `RatchetEntry` | `consumeNextAvailableTag(PublicKey target)` Outbound.
    `SessionTag` | `consumeNextAvailableTag(PublicKey target, SessionKey key)` Retrieve the next available session tag for identifying the use of the given key when communicating with the target.
    `SessionKeyAndNonce` | `consumeTag(RatchetSessionTag tag)` Inbound.
    `SessionKey` | `consumeTag(SessionTag tag)` Determine if we have received a session key associated with the given session tag, and if so, discard it (but keep track for frequent dups) and return the decryption key it was received with (via tagsReceived(...)).
    `(package private) boolean` | `createSession(PublicKey target, Destination d, HandshakeState state, ReplyCallback callback)` Inbound or outbound.
    `void` | `createSession(PublicKey target, SessionKey key)` Associate a new session key with the specified target.
    `void` | `expireTag(RatchetSessionTag tag, RatchetTagSet ts)` Remove the tag associated with this tagset.
    `void` | `failTags(PublicKey target, SessionKey key, TagSetHandle ts)`
    `int` | `getAvailableTags(PublicKey target, SessionKey key)` Determine (approximately) how many available session tags for the current target have been confirmed and are available
    `long` | `getAvailableTimeLeft(PublicKey target, SessionKey key)` Determine how long the available tags will be available for before expiring, in milliseconds
    `SessionKey` | `getCurrentKey(PublicKey target)` Retrieve the session key currently associated with encryption to the target, or null if a new session key should be generated.
    `SessionKey` | `getCurrentOrNewKey(PublicKey target)` Retrieve the session key currently associated with encryption to the target.
    `Destination` | `getDestination()` The local destination for this SKM
    `(package private) Destination` | `getDestination(PublicKey target)`
    `int` | `getLowThreshold()` Get the low threshold for tag sending.
    `int` | `getTagsToSend()` How many to send, IF we need to.
    `EncType` | `getType()` Session key manager for ratchet encryption that handles outbound sessions, inbound tag sets, next key exchanges, and acknowledgment processing for ECIES+AEAD communications
    `(package private) boolean` | `isDuplicate(PublicKey pk)`
    `(package private) void` | `nextKeyReceived(PublicKey target, NextSessionKey key)`
    `(package private) void` | `receivedACK(PublicKey target, int id, int n)`
    `(package private) void` | `registerCallback(PublicKey target, int id, int n, ReplyCallback callback)`
    `(package private) boolean` | `registerTimer(PublicKey target, Destination d, SimpleTimer2.TimedEvent timer)` Side effect - binds this session to the supplied destination.
    `void` | `renderStatusHTML(Writer out)`
    `boolean` | `shouldSendTags(PublicKey target, SessionKey key, int lowThreshold)` Determine if tags should be sent to the target with the specified threshold.
    `void` | `shutdown()` Cannot be restarted
    `void` | `tagsAcked(PublicKey target, SessionKey key, TagSetHandle ts)`
    `TagSetHandle` | `tagsDelivered(PublicKey target, SessionKey key, Set<SessionTag> sessionTags)` Take note of the fact that the given sessionTags associated with the key for encryption to the target have definitely been received at the target (aka call this method after receiving an ack to a message delivering them)
    `void` | `tagsReceived(SessionKey key, RatchetSessionTag tag, long expire)` One time session
    `void` | `tagsReceived(SessionKey key, Set<SessionTag> sessionTags)` Accept the given tags and associate them with the given key for decryption, with the default expiration.
    `void` | `tagsReceived(SessionKey key, Set<SessionTag> sessionTags, long expire)` Accept the given tags and associate them with the given key for decryption, with specified expiration.
    `(package private) boolean` | `updateSession(PublicKey target, HandshakeState oldState, HandshakeState state, ReplyCallback callback, SplitKeys split)` Inbound or outbound.

    - ### Methods inherited from class net.i2p.crypto.SessionKeyManager

      `createSession, failTags, shouldSendTags`

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

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

- - ### Field Detail

    - #### _context

          protected final RouterContext _context

    - #### SESSION_LIFETIME_MAX_MS

          static final long SESSION_LIFETIME_MAX_MS

      Keep unused inbound session tags around for this long (a few minutes longer than session tags are used on the outbound side so that no reasonable network lag can cause failed decrypts) This is also the max idle time for an outbound session.
      See Also:
        Constant Field Values

    - #### SESSION_PENDING_DURATION_MS

          static final long SESSION_PENDING_DURATION_MS

      See Also:
        Constant Field Values

    - #### SESSION_TAG_DURATION_MS

          static final long SESSION_TAG_DURATION_MS

      Let outbound session tags sit around for this long before expiring them. Inbound tag expiration is set by SESSION_LIFETIME_MAX_MS
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### RatchetSKM

          public RatchetSKM(RouterContext context)

      For the router SKM only.

    - #### RatchetSKM

          public RatchetSKM(RouterContext context,
                            Destination dest)

      ECIES only.
      Parameters:
        `dest` - null for router's SKM only

    - #### RatchetSKM

          public RatchetSKM(RouterContext context,
                            Destination dest,
                            EncType type)

      The session key manager is constructed and accessed through the client manager.
      Parameters:
        `dest` - null for router's SKM only
        `type` - the encryption type

  - ### Method Detail

    - #### ackRequested

          void ackRequested(PublicKey target,
                            int id,
                            int n)

    - #### addTag

          public boolean addTag(RatchetSessionTag tag,
                                RatchetTagSet ts)

      Map the tag to this tagset.
      Specified by:
        `addTag` in interface `SessionTagListener`
      Returns:
        true if added, false if dup

    - #### consumeNextAvailableTag

          public RatchetEntry consumeNextAvailableTag(PublicKey target)

      Outbound. Retrieve the next available session tag and key for sending a message to the target. If this returns null, no session is set up yet, and a New Session message should be sent. If this returns non-null, the tag in the RatchetEntry will be non-null. If the SessionKeyAndNonce contains a HandshakeState, then the session setup is in progress, and a New Session Reply message should be sent. Otherwise, an Existing Session message should be sent.

    - #### consumeNextAvailableTag

          public SessionTag consumeNextAvailableTag(PublicKey target,
                                                    SessionKey key)

      Description copied from class: `SessionKeyManager`
      Retrieve the next available session tag for identifying the use of the given key when communicating with the target. If this returns null, no tags are available so ElG should be used with the given key (a new sessionKey should NOT be used)
      Overrides:
        `consumeNextAvailableTag` in class `SessionKeyManager`
      Throws:
        `UnsupportedOperationException` - always

    - #### consumeTag

          public SessionKeyAndNonce consumeTag(RatchetSessionTag tag)

      Inbound. Determine if we have received a session key associated with the given session tag, and if so, discard it and return the decryption key it was received with (via tagsReceived(...)). returns null if no session key matches If the return value has null data, it will have a non-null HandshakeState.
      Returns:
        a SessionKeyAndNonce or null

    - #### consumeTag

          public SessionKey consumeTag(SessionTag tag)

      Description copied from class: `SessionKeyManager`
      Determine if we have received a session key associated with the given session tag, and if so, discard it (but keep track for frequent dups) and return the decryption key it was received with (via tagsReceived(...)). returns null if no session key matches
      Overrides:
        `consumeTag` in class `SessionKeyManager`
      Throws:
        `UnsupportedOperationException` - always

    - #### createSession

          boolean createSession(PublicKey target,
                                Destination d,
                                HandshakeState state,
                                ReplyCallback callback)

      Inbound or outbound. Checks state.getRole() to determine. For outbound (NS sent), adds to list of pending inbound sessions and returns true. For inbound (NS rcvd), if no other pending outbound sessions, creates one and returns true, or false if one already exists.
      Parameters:
        `d` - null if unknown
        `callback` - null for inbound, may be null for outbound

    - #### createSession

          public void createSession(PublicKey target,
                                    SessionKey key)

      Description copied from class: `SessionKeyManager`
      Associate a new session key with the specified target. Metrics to determine when to expire that key begin with this call. Racy if called after getCurrentKey() to check for a current session; use getCurrentOrNewKey() in that case.
      Overrides:
        `createSession` in class `SessionKeyManager`
      Throws:
        `UnsupportedOperationException` - always

    - #### expireTag

          public void expireTag(RatchetSessionTag tag,
                                RatchetTagSet ts)

      Remove the tag associated with this tagset.
      Specified by:
        `expireTag` in interface `SessionTagListener`

    - #### failTags

          public void failTags(PublicKey target,
                               SessionKey key,
                               TagSetHandle ts)

      Overrides:
        `failTags` in class `SessionKeyManager`
      Throws:
        `UnsupportedOperationException` - always

    - #### getAvailableTags

          public int getAvailableTags(PublicKey target,
                                      SessionKey key)

      Determine (approximately) how many available session tags for the current target have been confirmed and are available
      Overrides:
        `getAvailableTags` in class `SessionKeyManager`

    - #### getAvailableTimeLeft

          public long getAvailableTimeLeft(PublicKey target,
                                           SessionKey key)

      Determine how long the available tags will be available for before expiring, in milliseconds
      Overrides:
        `getAvailableTimeLeft` in class `SessionKeyManager`

    - #### getCurrentKey

          public SessionKey getCurrentKey(PublicKey target)

      Description copied from class: `SessionKeyManager`
      Retrieve the session key currently associated with encryption to the target, or null if a new session key should be generated. Warning - don't generate a new session if this returns null, it's racy, use getCurrentOrNewKey()
      Overrides:
        `getCurrentKey` in class `SessionKeyManager`
      Throws:
        `UnsupportedOperationException` - always

    - #### getCurrentOrNewKey

          public SessionKey getCurrentOrNewKey(PublicKey target)

      Description copied from class: `SessionKeyManager`
      Retrieve the session key currently associated with encryption to the target. Generates a new session and session key if not previously exising.
      Overrides:
        `getCurrentOrNewKey` in class `SessionKeyManager`
      Returns:
        non-null
      Throws:
        `UnsupportedOperationException` - always

    - #### getDestination

          public Destination getDestination()

      The local destination for this SKM
      Returns:
        our destination or null for the router SKM

    - #### getDestination

          Destination getDestination(PublicKey target)

      Returns:
        the far-end Destination for this PublicKey, or null

    - #### getLowThreshold

          public int getLowThreshold()

      Description copied from class: `SessionKeyManager`
      Get the low threshold for tag sending.
      Overrides:
        `getLowThreshold` in class `SessionKeyManager`
      Returns:
        the configured value

    - #### getTagsToSend

          public int getTagsToSend()

      How many to send, IF we need to.
      Overrides:
        `getTagsToSend` in class `SessionKeyManager`
      Returns:
        the configured value (not adjusted for current available)

    - #### getType

          public EncType getType()

      Session key manager for ratchet encryption that handles outbound sessions, inbound tag sets, next key exchanges, and acknowledgment processing for ECIES+AEAD communications

    - #### isDuplicate

          boolean isDuplicate(PublicKey pk)

      Returns:
        true if a dup

    - #### nextKeyReceived

          void nextKeyReceived(PublicKey target,
                               NextSessionKey key)

    - #### receivedACK

          void receivedACK(PublicKey target,
                           int id,
                           int n)

    - #### registerCallback

          void registerCallback(PublicKey target,
                                int id,
                                int n,
                                ReplyCallback callback)

    - #### registerTimer

          boolean registerTimer(PublicKey target,
                                Destination d,
                                SimpleTimer2.TimedEvent timer)

      Side effect - binds this session to the supplied destination.
      Parameters:
        `d` - the far-end Destination for this PublicKey if known, or null
      Returns:
        true if registered

    - #### renderStatusHTML

          public void renderStatusHTML(Writer out)
                                throws IOException

      Overrides:
        `renderStatusHTML` in class `SessionKeyManager`
      Throws:
        `IOException`

    - #### shouldSendTags

          public boolean shouldSendTags(PublicKey target,
                                        SessionKey key,
                                        int lowThreshold)

      Description copied from class: `SessionKeyManager`
      Determine if tags should be sent to the target with the specified threshold.
      Overrides:
        `shouldSendTags` in class `SessionKeyManager`
      Parameters:
        `target` - the target public key
        `key` - the session key
        `lowThreshold` - the low threshold
      Returns:
        false always

    - #### shutdown

          public void shutdown()

      Cannot be restarted
      Overrides:
        `shutdown` in class `SessionKeyManager`

    - #### tagsAcked

          public void tagsAcked(PublicKey target,
                                SessionKey key,
                                TagSetHandle ts)

      Overrides:
        `tagsAcked` in class `SessionKeyManager`
      Throws:
        `UnsupportedOperationException` - always

    - #### tagsDelivered

          public TagSetHandle tagsDelivered(PublicKey target,
                                            SessionKey key,
                                            Set<SessionTag> sessionTags)

      Description copied from class: `SessionKeyManager`
      Take note of the fact that the given sessionTags associated with the key for encryption to the target have definitely been received at the target (aka call this method after receiving an ack to a message delivering them)
      Overrides:
        `tagsDelivered` in class `SessionKeyManager`
      Throws:
        `UnsupportedOperationException` - always

    - #### tagsReceived

          public void tagsReceived(SessionKey key,
                                   RatchetSessionTag tag,
                                   long expire)

      One time session
      Parameters:
        `expire` - time from now

    - #### tagsReceived

          public void tagsReceived(SessionKey key,
                                   Set<SessionTag> sessionTags)

      Description copied from class: `SessionKeyManager`
      Accept the given tags and associate them with the given key for decryption, with the default expiration.
      Overrides:
        `tagsReceived` in class `SessionKeyManager`
      Throws:
        `UnsupportedOperationException` - always

    - #### tagsReceived

          public void tagsReceived(SessionKey key,
                                   Set<SessionTag> sessionTags,
                                   long expire)

      Description copied from class: `SessionKeyManager`
      Accept the given tags and associate them with the given key for decryption, with specified expiration.
      Overrides:
        `tagsReceived` in class `SessionKeyManager`
        `sessionTags` - modifiable; NOT copied
        `expire` - time from now
      Throws:
        `UnsupportedOperationException` - always

    - #### updateSession

          boolean updateSession(PublicKey target,
                                HandshakeState oldState,
                                HandshakeState state,
                                ReplyCallback callback,
                                SplitKeys split)

      Inbound or outbound. Checks state.getRole() to determine. For outbound (NSR rcvd by Alice), sets session to transition to ES mode outbound. For inbound (NSR sent by Bob), sets up inbound ES tagset.
      Parameters:
        `oldState` - null for inbound, pre-clone for outbound
      Returns:
        true if this was the first NSR received