java.lang.Object
net.i2p.crypto.SessionKeyManager
Direct Known Subclasses:
MuxedPQSKM, MuxedSKM, RatchetSKM, TransientSessionKeyManager
public class SessionKeyManagerextends Object
Manage the session keys and session tags used for encryption and decryption. This base implementation simply ignores sessions and acts as if everything is unknown (and hence always forces a full ElGamal encryption for each message). See TransientSessionKeyManager subclass which manages and persists keys and tags.

  • Constructor Details

  • Method Details

    • getCurrentKey

      public 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.

      Warning - don't generate a new session if this returns null, it's racy, use getCurrentOrNewKey(PublicKey).

      Parameters:
      target - the destination whose current session key is wanted
      Returns:
      the current key

    • getCurrentOrNewKey

      public SessionKey getCurrentOrNewKey(PublicKey target)
      Retrieve the session key currently associated with encryption to the target. Generates a new session and session key if not previously existing.
      Parameters:
      target - the destination to start or continue a session with
      Returns:
      non-null

    • createSession

      public void createSession(PublicKey target, SessionKey key)
      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(PublicKey) to check for a current session; use getCurrentOrNewKey() in that case.

      Parameters:
      target - the destination the session is established with
      key - the session key to associate, whose expiry metrics start at this call

    • createSession

      public SessionKey createSession(PublicKey target)
      Generate a new session key and associate it with the specified target.

      Racy if called after getCurrentKey() to check for a current session; use getCurrentOrNewKey() in that case.

      Parameters:
      target - the destination to establish a freshly generated session with
      Returns:
      the session key

    • consumeNextAvailableTag

      public 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. If this returns null, no tags are available so ElG should be used with the given key (a new sessionKey should NOT be used).
      Parameters:
      target - the destination the tag was sent to
      key - the session key whose use the tag identifies
      Returns:
      the next available tag, or null

    • getTagsToSend

      public int getTagsToSend()
      The number of session tags to send.
      Returns:
      The number of tags to send, or 0 if not implemented.

    • getLowThreshold

      public int getLowThreshold()
      The low threshold for sending tags.
      Returns:
      The low threshold, or 0 if not implemented.

    • shouldSendTags

      public boolean shouldSendTags(PublicKey target, SessionKey key)
      Determine if tags should be sent to the target.
      Parameters:
      target - the destination whose tags are being considered
      key - the session key
      Returns:
      true if we have less than the threshold or what we have is about to expire

    • shouldSendTags

      public boolean shouldSendTags(PublicKey target, SessionKey key, int lowThreshold)
      Determine if tags should be sent to the target with the specified threshold.
      Parameters:
      target - the destination whose tags are being considered
      key - the session key
      lowThreshold - the low threshold
      Returns:
      true if we have less than the threshold or what we have is about to expire

    • 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.
      Parameters:
      target - the destination the tags were sent to
      key - the session key those tags were issued under
      Returns:
      the available tags

    • getAvailableTimeLeft

      public long getAvailableTimeLeft(PublicKey target, SessionKey key)
      Determine how long the available tags will be available for before expiring, in milliseconds.
      Parameters:
      target - the destination the tags were sent to
      key - the session key those tags were issued under
      Returns:
      the available time left

    • tagsDelivered

      public 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).
      Parameters:
      target - the destination that acknowledged the tags
      key - the session key the acknowledged tags were issued under
      sessionTags - modifiable; NOT copied
      Returns:
      the tag set handle

    • failTags

      public void failTags(PublicKey target)
      Mark all of the tags delivered to the target up to this point as invalid, since the peer has failed to respond when they should have. This call essentially lets the system recover from corrupted tag sets and crashes.
      Parameters:
      target - the destination whose delivered tags are being invalidated

    • tagsReceived

      public void tagsReceived(SessionKey key, Set<SessionTag> sessionTags)
      Accept the given tags and associate them with the given key for decryption, with the default expiration.
      Parameters:
      key - the session key the tags were received for
      sessionTags - modifiable; NOT copied

    • tagsReceived

      public 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.
      Parameters:
      key - the session key the tags were received for
      sessionTags - modifiable; NOT copied
      expire - time from now

    • consumeTag

      public 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(...)). returns null if no session key matches.
      Parameters:
      tag - the session tag whose delivered key is consumed
      Returns:
      the session key, or null

    • shutdown

      public void shutdown()
      Called when the system is closing down, instructing the session key manager to take whatever precautions are necessary (saving state, etc).

    • renderStatusHTML

      public void renderStatusHTML(Writer out) throws IOException
      Render status HTML.
      Parameters:
      out - the writer to render to
      Throws:
      IOException - if an I/O error occurs

    • getDebugStats

      public long[] getDebugStats()
      Debug overview stats as {inbound tags, outbound sessions, sessions created, sessions replaced, inbound sets completed, inbound tag misses}. Null for managers that do not track them.
      Returns:
      the stats, or null

    • failTags

      public void failTags(PublicKey target, SessionKey key, TagSetHandle ts)
      Fail tags for the given target, key, and tag set handle.
      Parameters:
      target - the destination whose tags are being considered
      key - the session key
      ts - the tag set handle

    • tagsAcked

      public void tagsAcked(PublicKey target, SessionKey key, TagSetHandle ts)
      Acknowledge tags for the given target, key, and tag set handle.
      Parameters:
      target - the destination whose tags are being considered
      key - the session key
      ts - the tag set handle