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

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