public interface I2PSession
Define the standard means of sending and receiving messages on the
I2P network by using the I2CP (the client protocol). This is done over a
bidirectional TCP socket.
End to end encryption in I2PSession was disabled in release 0.6.
Periodically the router will ask the client to authorize a new set of
tunnels to be allocated to the client, which the client can accept by sending a
LeaseSet
signed by the Destination
.
In addition, the router may on occasion provide the client with an updated
clock offset so that the client can stay in sync with the network (even if
the host computer's clock is off).
Modifier and Type | Field and Description |
---|---|
static int |
PORT_ANY |
static int |
PORT_UNSPECIFIED |
static int |
PROTO_ANY |
static int |
PROTO_DATAGRAM
Generally a signed datagram, but could
also be a raw datagram, depending on the application
|
static int |
PROTO_DATAGRAM_RAW
A raw (unsigned) datagram
|
static int |
PROTO_STREAMING |
static int |
PROTO_UNSPECIFIED |
Modifier and Type | Method and Description |
---|---|
void |
addMuxedSessionListener(I2PSessionMuxedListener l,
int proto,
int port)
Listen on specified protocol and port, and receive notification
of proto, fromPort, and toPort for every message.
|
void |
addSessionListener(I2PSessionListener lsnr,
int proto,
int port)
Listen on specified protocol and port.
|
I2PSession |
addSubsession(InputStream privateKeyStream,
Properties opts) |
int[] |
bandwidthLimits()
Get the current bandwidth limits.
|
void |
connect()
Actually connect the session and start receiving/sending messages
|
void |
destroySession()
Tear down the session and release any resources.
|
PrivateKey |
getDecryptionKey()
Retrieve the decryption PrivateKey associated with the Destination
|
Destination |
getMyDestination()
Retrieve the Destination this session serves as the endpoint for.
|
SigningPrivateKey |
getPrivateKey()
Retrieve the signing SigningPrivateKey associated with the Destination
|
List<I2PSession> |
getSubsessions() |
boolean |
isClosed()
Have we closed the session?
|
Destination |
lookupDest(Hash h)
Lookup a Destination by Hash.
|
Destination |
lookupDest(Hash h,
long maxWait)
Lookup a Destination by Hash.
|
Destination |
lookupDest(String name)
Ask the router to lookup a Destination by host name.
|
Destination |
lookupDest(String name,
long maxWait)
Ask the router to lookup a Destination by host name.
|
byte[] |
receiveMessage(int msgId)
Receive a message that the router has notified the client about, returning
the payload.
|
void |
removeListener(int proto,
int port)
removes the specified listener (only)
|
void |
removeSubsession(I2PSession session) |
void |
reportAbuse(int msgId,
int severity)
Instruct the router that the message received was abusive (including how
abusive on a 1-100 scale) in the hopes the router can do something to
minimize receiving abusive messages like that in the future.
|
boolean |
sendMessage(Destination dest,
byte[] payload)
Send a new message to the given destination, containing the specified
payload, returning true if the router feels confident that the message
was delivered.
|
boolean |
sendMessage(Destination dest,
byte[] payload,
int offset,
int size)
Send a new message to the given destination, containing the specified
payload, returning true if the router feels confident that the message
was delivered.
|
boolean |
sendMessage(Destination dest,
byte[] payload,
int proto,
int fromport,
int toport)
See I2PSessionMuxedImpl for proto/port details.
|
boolean |
sendMessage(Destination dest,
byte[] payload,
int offset,
int size,
int proto,
int fromPort,
int toPort,
SendMessageOptions options)
See I2PSessionMuxedImpl for proto/port details.
|
long |
sendMessage(Destination dest,
byte[] payload,
int offset,
int size,
int proto,
int fromPort,
int toPort,
SendMessageOptions options,
SendMessageStatusListener listener)
Send a message and request an asynchronous notification of delivery status.
|
boolean |
sendMessage(Destination dest,
byte[] payload,
int offset,
int size,
SessionKey keyUsed,
Set<SessionTag> tagsSent)
End-to-End Crypto is disabled, tags and keys are ignored.
|
boolean |
sendMessage(Destination dest,
byte[] payload,
int offset,
int size,
SessionKey keyUsed,
Set<SessionTag> tagsSent,
int proto,
int fromPort,
int toPort)
See I2PSessionMuxedImpl for proto/port details.
|
boolean |
sendMessage(Destination dest,
byte[] payload,
int offset,
int size,
SessionKey keyUsed,
Set<SessionTag> tagsSent,
long expire)
End-to-End Crypto is disabled, tags and keys are ignored.
|
boolean |
sendMessage(Destination dest,
byte[] payload,
int offset,
int size,
SessionKey keyUsed,
Set<SessionTag> tagsSent,
long expire,
int proto,
int fromPort,
int toPort)
See I2PSessionMuxedImpl for proto/port details.
|
boolean |
sendMessage(Destination dest,
byte[] payload,
int offset,
int size,
SessionKey keyUsed,
Set<SessionTag> tagsSent,
long expire,
int proto,
int fromPort,
int toPort,
int flags)
See I2PSessionMuxedImpl for proto/port details.
|
boolean |
sendMessage(Destination dest,
byte[] payload,
SessionKey keyUsed,
Set<SessionTag> tagsSent)
End-to-End Crypto is disabled, tags and keys are ignored!
Like sendMessage above, except the key used and the tags sent are exposed to the
application.
|
void |
setSessionListener(I2PSessionListener lsnr)
Instruct the I2PSession where it should send event notifications
WARNING: It is recommended that you use a method that specifies the protocol and ports.
|
void |
updateOptions(Properties options)
Pass updated options to the router.
|
static final int PORT_ANY
static final int PORT_UNSPECIFIED
static final int PROTO_ANY
static final int PROTO_UNSPECIFIED
static final int PROTO_STREAMING
static final int PROTO_DATAGRAM
static final int PROTO_DATAGRAM_RAW
boolean sendMessage(Destination dest, byte[] payload) throws I2PSessionException
dest
- location to send the messagepayload
- body of the message to be sent (unencrypted)I2PSessionException
boolean sendMessage(Destination dest, byte[] payload, int offset, int size) throws I2PSessionException
dest
- location to send the messagepayload
- body of the message to be sent (unencrypted)I2PSessionException
boolean sendMessage(Destination dest, byte[] payload, int proto, int fromport, int toport) throws I2PSessionException
I2PSessionException
boolean sendMessage(Destination dest, byte[] payload, SessionKey keyUsed, Set<SessionTag> tagsSent) throws I2PSessionException
If some application layer message delivery confirmation is used, rather than i2p's (slow) built in confirmation via guaranteed delivery mode, the application can update the SessionKeyManager, ala:
SessionKeyManager.getInstance().tagsDelivered(dest.getPublicKey(), keyUsed, tagsSent);If an application is using guaranteed delivery mode, this is not useful, but for applications using best effort delivery mode, if they can know with certainty that a message was delivered and can update the SessionKeyManager appropriately, a significant performance boost will occur (subsequent message encryption and decryption will be done via AES and a SessionTag, rather than ElGamal+AES, which is 1000x slower).
dest
- location to send the messagepayload
- body of the message to be sent (unencrypted)keyUsed
- UNUSED, IGNORED. Session key delivered to the destination for association with the tags sent. This is essentially
an output parameter - keyUsed.getData() is ignored during this call, but after the call completes,
it will be filled with the bytes of the session key delivered. Typically the key delivered is the
same one as the key encrypted with, but not always. If this is null then the key data will not be
exposed.tagsSent
- UNUSED, IGNORED. Set of tags delivered to the peer and associated with the keyUsed. This is also an output parameter -
the contents of the set is ignored during the call, but afterwards it contains a set of SessionTag
objects that were sent along side the given keyUsed.I2PSessionException
boolean sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, Set<SessionTag> tagsSent) throws I2PSessionException
keyUsed
- UNUSED, IGNORED.tagsSent
- UNUSED, IGNORED.I2PSessionException
boolean sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, Set<SessionTag> tagsSent, long expire) throws I2PSessionException
keyUsed
- UNUSED, IGNORED.tagsSent
- UNUSED, IGNORED.expire
- absolute expiration timestamp, NOT interval from nowI2PSessionException
boolean sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, Set<SessionTag> tagsSent, int proto, int fromPort, int toPort) throws I2PSessionException
keyUsed
- UNUSED, IGNORED.tagsSent
- UNUSED, IGNORED.proto
- 1-254 or 0 for unset; recommended:
I2PSession.PROTO_UNSPECIFIED
I2PSession.PROTO_STREAMING
I2PSession.PROTO_DATAGRAM
255 disallowedfromPort
- 1-65535 or 0 for unsettoPort
- 1-65535 or 0 for unsetI2PSessionException
boolean sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, Set<SessionTag> tagsSent, long expire, int proto, int fromPort, int toPort) throws I2PSessionException
keyUsed
- UNUSED, IGNORED.tagsSent
- UNUSED, IGNORED.expire
- absolute expiration timestamp, NOT interval from nowproto
- 1-254 or 0 for unset; recommended:
I2PSession.PROTO_UNSPECIFIED
I2PSession.PROTO_STREAMING
I2PSession.PROTO_DATAGRAM
255 disallowedfromPort
- 1-65535 or 0 for unsettoPort
- 1-65535 or 0 for unsetI2PSessionException
boolean sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, Set<SessionTag> tagsSent, long expire, int proto, int fromPort, int toPort, int flags) throws I2PSessionException
keyUsed
- UNUSED, IGNORED.tagsSent
- UNUSED, IGNORED.expire
- absolute expiration timestamp, NOT interval from nowproto
- 1-254 or 0 for unset; recommended:
I2PSession.PROTO_UNSPECIFIED
I2PSession.PROTO_STREAMING
I2PSession.PROTO_DATAGRAM
255 disallowedfromPort
- 1-65535 or 0 for unsettoPort
- 1-65535 or 0 for unsetI2PSessionException
boolean sendMessage(Destination dest, byte[] payload, int offset, int size, int proto, int fromPort, int toPort, SendMessageOptions options) throws I2PSessionException
proto
- 1-254 or 0 for unset; recommended:
I2PSession.PROTO_UNSPECIFIED
I2PSession.PROTO_STREAMING
I2PSession.PROTO_DATAGRAM
255 disallowedfromPort
- 1-65535 or 0 for unsettoPort
- 1-65535 or 0 for unsetoptions
- to be passed to the routerI2PSessionException
long sendMessage(Destination dest, byte[] payload, int offset, int size, int proto, int fromPort, int toPort, SendMessageOptions options, SendMessageStatusListener listener) throws I2PSessionException
proto
- 1-254 or 0 for unset; recommended:
I2PSession.PROTO_UNSPECIFIED
I2PSession.PROTO_STREAMING
I2PSession.PROTO_DATAGRAM
255 disallowedfromPort
- 1-65535 or 0 for unsettoPort
- 1-65535 or 0 for unsetoptions
- to be passed to the routerI2PSessionException
- on all errorsbyte[] receiveMessage(int msgId) throws I2PSessionException
msgId
- message to fetchI2PSessionException
void reportAbuse(int msgId, int severity) throws I2PSessionException
msgId
- message that was abusive (or -1 for not message related)severity
- how abusiveI2PSessionException
void setSessionListener(I2PSessionListener lsnr)
lsnr
- listener to retrieve eventsvoid destroySession() throws I2PSessionException
I2PSessionException
I2PSession addSubsession(InputStream privateKeyStream, Properties opts) throws I2PSessionException
privateKeyStream
- null for transient, if non-null must have same encryption keys as primary session
and different signing keysopts
- subsession options if any, may be nullI2PSessionException
void removeSubsession(I2PSession session)
List<I2PSession> getSubsessions()
void connect() throws I2PSessionException
I2PSessionException
boolean isClosed()
Destination getMyDestination()
PrivateKey getDecryptionKey()
SigningPrivateKey getPrivateKey()
Destination lookupDest(Hash h) throws I2PSessionException
I2PSessionException
Destination lookupDest(Hash h, long maxWait) throws I2PSessionException
maxWait
- msI2PSessionException
Destination lookupDest(String name) throws I2PSessionException
if (name.length() == 60 && name.toLowerCase(Locale.US).endsWith(".b32.i2p")) { if (session != null) return session.lookup(Hash.create(Base32.decode(name.toLowerCase(Locale.US).substring(0, 52)))); else return ctx.namingService().lookup(name); // simple session for xxx.b32.i2p handled by naming service (optional if you need lookup w/o an existing session) } else if (ctx.isRouterContext()) { return ctx.namingService().lookup(name); // hostname from router's naming service } else { Destination d = ctx.namingService().lookup(name); // local naming svc, optional if (d != null) return d; if (session != null) return session.lookup(name); // simple session (optional if you need lookup w/o an existing session) Destination rv = null; I2PClient client = new I2PSimpleClient(); Properties opts = new Properties(); opts.put(I2PClient.PROP_TCP_HOST, host); opts.put(I2PClient.PROP_TCP_PORT, port); I2PSession session = null; try { session = client.createSession(null, opts); session.connect(); rv = session.lookupDest(name); } finally { if (session != null) session.destroySession(); } return rv; }Requires router side to be 0.9.11 or higher. If the router is older, this will return null immediately.
I2PSessionException
Destination lookupDest(String name, long maxWait) throws I2PSessionException
maxWait
- msI2PSessionException
void updateOptions(Properties options)
options
- non-nullint[] bandwidthLimits() throws I2PSessionException
I2PSessionException
void addSessionListener(I2PSessionListener lsnr, int proto, int port)
proto
- 1-254 or PROTO_ANY (0) for all; recommended:
I2PSession.PROTO_STREAMING
I2PSession.PROTO_DATAGRAM
255 disallowedport
- 1-65535 or PORT_ANY (0) for allvoid addMuxedSessionListener(I2PSessionMuxedListener l, int proto, int port)
proto
- 1-254 or PROTO_ANY (0) for all; 255 disallowedport
- 1-65535 or PORT_ANY (0) for allvoid removeListener(int proto, int port)