RatchetSKM (Javadocs [I2P+ 2.13.0+]

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` The router 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` S e s s i o n p e n d i n g d u r a t i o n m s
`(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)` Process an ACK request
`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)` Fail tags for the given target, key, and tag set handle.
`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)` Get the far-end destination for a public key
`int`	`getLowThreshold()` Get the low threshold for tag sending.
`int`	`getTagsToSend()` How many to send, IF we need to.
`EncType`	`getType()` Get the encryption type for this session key manager
`(package private) boolean`	`isDuplicate(PublicKey pk)` Check if a public key is a duplicate
`(package private) void`	`nextKeyReceived(PublicKey target, NextSessionKey key)` Process a received next key
`(package private) void`	`receivedACK(PublicKey target, int id, int n)` Process a received ACK
`(package private) void`	`registerCallback(PublicKey target, int id, int n, ReplyCallback callback)` Register a callback for an ACK
`(package private) boolean`	`registerTimer(PublicKey target, Destination d, SimpleTimer2.TimedEvent timer)` Side effect - binds this session to the supplied destination.
`void`	`renderStatusHTML(Writer out)` renderStatusHTML.
`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)` Acknowledge tags for the given target, key, and tag set handle.
`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
```
    The router 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
```
    S e s s i o n p e n d i n g d u r a t i o n m s
    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.
    Parameters:
    context - the router context
  - RatchetSKM
```
public RatchetSKM(RouterContext context,
                  Destination dest)
```
    ECIES only.
    Parameters:
    context - the router context
    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:
    context - the router context
    dest - null for router's SKM only
    type - the encryption type
- Method Detail
  - ackRequested
```
void ackRequested(PublicKey target,
                  int id,
                  int n)
```
    Process an ACK request
    Parameters:
    target - the target public key
    id - the ACK ID
    n - the ACK count
  - addTag
```
public boolean addTag(RatchetSessionTag tag,
                      RatchetTagSet ts)
```
    Map the tag to this tagset.
    Specified by:
    addTag in interface SessionTagListener
    Parameters:
    tag - the session tag
    ts - the tag set
    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.
    Parameters:
    target - the target
    Returns:
    the next available tag, or null
  - 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
    Returns:
    the next available tag, or null
    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.
    Parameters:
    tag - the ratchet session tag to consume
    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
    Returns:
    the session key, or null
    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:
    target - the target public key
    d - null if unknown
    state - the handshake state
    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
    Parameters:
    tag - the session tag
    ts - the tag set
  - failTags
```
public void failTags(PublicKey target,
                     SessionKey key,
                     TagSetHandle ts)
```
    Description copied from class: SessionKeyManager
    Fail tags for the given target, key, and tag set handle.
    Overrides:
    failTags in class SessionKeyManager
    Parameters:
    target - the target
    key - the session key
    ts - the tag set handle
    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
    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
    Overrides:
    getAvailableTimeLeft in class SessionKeyManager
    Returns:
    the available time left
  - 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
    Returns:
    the current key
    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:
    the current or new key
    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)
```
    Get the far-end destination for a public key
    Parameters:
    target - the target public key
    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()
```
    Get the encryption type for this session key manager
    Returns:
    the encryption type
  - isDuplicate
```
boolean isDuplicate(PublicKey pk)
```
    Check if a public key is a duplicate
    Parameters:
    pk - the public key to check
    Returns:
    true if a dup
  - nextKeyReceived
```
void nextKeyReceived(PublicKey target,
                     NextSessionKey key)
```
    Process a received next key
    Parameters:
    target - the target public key
    key - the next session key
  - receivedACK
```
void receivedACK(PublicKey target,
                 int id,
                 int n)
```
    Process a received ACK
    Parameters:
    target - the target public key
    id - the ACK ID
    n - the ACK count
  - registerCallback
```
void registerCallback(PublicKey target,
                      int id,
                      int n,
                      ReplyCallback callback)
```
    Register a callback for an ACK
    Parameters:
    target - the target public key
    id - the callback ID
    n - the callback count
    callback - the reply callback
  - registerTimer
```
boolean registerTimer(PublicKey target,
                      Destination d,
                      SimpleTimer2.TimedEvent timer)
```
    Side effect - binds this session to the supplied destination.
    Parameters:
    target - the target public key
    d - the far-end Destination for this PublicKey if known, or null
    timer - the timer event
    Returns:
    true if registered
  - renderStatusHTML
```
public void renderStatusHTML(Writer out)
                      throws IOException
```
    renderStatusHTML.
    Overrides:
    renderStatusHTML in class SessionKeyManager
    Parameters:
    out - the writer to render to
    Throws:
    IOException - if an I/O error occurs
  - 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
    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)
```
    Description copied from class: SessionKeyManager
    Acknowledge tags for the given target, key, and tag set handle.
    Overrides:
    tagsAcked in class SessionKeyManager
    Parameters:
    target - the target
    key - the session key
    ts - the tag set handle
    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
    Returns:
    the tag set handle
    Throws:
    UnsupportedOperationException - always
  - tagsReceived
```
public void tagsReceived(SessionKey key,
                         RatchetSessionTag tag,
                         long expire)
```
    One time session
    Parameters:
    key - the session key
    tag - the ratchet session tag
    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:
    target - the target public key
    oldState - null for inbound, pre-clone for outbound
    state - the handshake state
    callback - the reply callback
    split - the split keys
    Returns:
    true if this was the first NSR received

Class RatchetSKM

Field Summary

Constructor Summary

Method Summary

Methods inherited from class net.i2p.crypto.SessionKeyManager

Methods inherited from class java.lang.Object

Field Detail

_context

SESSION_LIFETIME_MAX_MS

SESSION_PENDING_DURATION_MS

SESSION_TAG_DURATION_MS

Constructor Detail

RatchetSKM

RatchetSKM

RatchetSKM

Method Detail

ackRequested

addTag

consumeNextAvailableTag

consumeNextAvailableTag

consumeTag

consumeTag

createSession

createSession

expireTag

failTags

getAvailableTags

getAvailableTimeLeft

getCurrentKey

getCurrentOrNewKey

getDestination

getDestination

getLowThreshold

getTagsToSend

getType

isDuplicate

nextKeyReceived

receivedACK

registerCallback

registerTimer

renderStatusHTML

shouldSendTags

shutdown

tagsAcked

tagsDelivered

tagsReceived

tagsReceived

tagsReceived

updateSession