SAMv3Handler

net.i2p.sam.SAMv3Handler

All Implemented Interfaces:: Runnable, Handler, SAMDatagramReceiver, SAMRawReceiver, SAMStreamReceiver

class SAMv3Handlerextends SAMv1Handler

Class able to handle a SAM version 3 client connection.

Field Summary
Modifier and Type
Field
Description
private static final String
AUTH_ERROR
Authentication error message.
(package private) final boolean
sendPorts
Package-visible so SAMHandlerPool can read it.
private Session
session
I2P session.
private boolean
sessionReady
True once the SESSION CREATE has fully initialized; guards against race in execStreamMessage.
static final SessionsDB
sSessionsHash
Global session-id to handler map shared by every SAMv3 bridge.
(package private) boolean
stolenSocket
Stolen socket.
(package private) boolean
streamForwardingSocket
Stream forwarding socket.
Fields inherited from class SAMv1Handler
_id, datagramSession, rawSession, SESSION_ERROR, streamSession
Modifier and Type
Field
Description
protected final long
_id
Identifier of this connection, unique among a router's SAM handlers.
protected SAMMessageSess
datagramSession
The session used for datagram style messages.
protected SAMMessageSess
rawSession
The SAM raw and datagram session, held after a successful HELLO.
protected static final String
SESSION_ERROR
Reply sent to a SESSION CREATE whose stream could not be established.
protected SAMStreamSession
streamSession
The session used for STREAM CONNECT connections.
Fields inherited from class SAMHandler
_log, bridge, i2cpProps, socket, stopHandler, stopLock, thread, verMajor, verMinor
Modifier and Type
Field
Description
protected final Log
_log
Log scoped to this handler's class.
protected final SAMBridge
bridge
Router bridge this handler routes sessions over.
protected final Properties
i2cpProps
I2CP options configuring the I2CP connection (port, host, numHops, etc).
protected final SocketChannel
socket
Client channel this handler reads commands from.
protected boolean
stopHandler
Whether shutdown has been requested for this handler.
protected final Object
stopLock
Monitor guarding the stop flag.
protected I2PAppThread
thread
Thread running the SAM protocol loop for this connection.
final int
verMajor
Major version this handler was negotiated at.
final int
verMinor
Minor version this handler was negotiated at.
Constructor Summary
Constructors
Constructor
Description
SAMv3Handler(SocketChannel s, int verMajor, int verMinor, Properties i2cpProps, SAMBridge parent)
Create a new SAM version 3 handler.
SAMv3Handler(SocketChannel s, int verMajor, int verMinor, SAMBridge parent)
Create a new SAM version 3 handler.
Method Summary
Modifier and Type
Method
Description
private void
die()
Terminate the handler.
private boolean
execAuthMessage(String opcode, Properties props)
Handle the AUTH message.
private boolean
execSessionAddRemove(String opcode, String nick, Properties props)
Execute SESSION ADD or REMOVE for MASTER sessions.
private boolean
execSessionCreate(String nick, Properties props)
Execute SESSION CREATE — generates or validates a destination, registers the nick, builds tunnels, and creates the session object.
protected boolean
execSessionMessage(String opcode, Properties props)
Parse and execute a SESSION message.
private boolean
execStreamAccept(Properties props)
Execute STREAM ACCEPT.
protected boolean
execStreamConnect(Properties props)
Parse and execute a STREAM CONNECT message.
private boolean
execStreamForwardIncoming(Properties props)
Exec stream forward incoming.
protected boolean
execStreamMessage(String opcode, Properties props)
Parse and execute a STREAM message.
(package private) SAMBridge
getBridge()
For SAMv3StreamSession.
String
getClientIP()
Get the IP address of the connected SAM client.
(package private) Session
getSession()
For SAMv3DatagramServer.
void
handle()
Legacy handle() method.
(package private) boolean
hasActiveStream()
Whether a client data stream has been taken over by this handler.
private static String
initDestination(String dest, Properties props)
Resolve TRANSIENT or validate a user-supplied private key.
private void
instantiateSession(String style, String nick, Properties allProps, Properties props)
Create and start the session object for the given style.
(package private) boolean
mayManageAuth()
Determine whether this connection may change the bridge's authentication configuration.
(package private) static boolean
mayManageAuth(boolean fromLoopback, String authUser, boolean authEnabled)
Decide whether an AUTH command may be issued from a connection.
(package private) boolean
mayUseSession(SessionRecord rec)
Determine whether this connection may operate on a session created by another connection.
private static SAMv3StreamSession
newSAMStreamSession(String login)
Create a stream session for a login.
static void
notifyStreamIncomingConnection(SocketChannel client, Destination d)
Notify the SAM client of an incoming stream connection on a static channel.
static void
notifyStreamIncomingConnection(SocketChannel client, Destination d, int fromPort, int toPort)
Notify the SAM client of an incoming stream connection with port information.
void
notifyStreamIncomingConnection(Destination d, int fromPort, int toPort)
Tells the SAM client a new stream connection arrived, naming the ports when requested.
void
notifyStreamResult(boolean verbose, String result, String message)
Send a STREAM STATUS RESULT line to the SAM client, unless verbose is false.
(package private) boolean
processLine(String line)
Process a single complete command line dispatched by the pool or the legacy handle() loop.
(package private) void
setSession(SAMv3DatagramSession sess)
For subsessions created by MasterSession.
(package private) void
setSession(SAMv3RawSession sess)
For subsessions created by MasterSession.
(package private) void
setSession(SAMv3StreamSession sess)
For subsessions created by MasterSession.
void
stealSocket()
For SAMv3StreamSession connect and accept.
void
stopHandling()
Stop the SAM handler, close the socket (unless stolen), unregister from the bridge and the handler pool.
boolean
verifVersion()
Verify the SAM protocol version is supported by this handler.
Methods inherited from class SAMv1Handler
createMessageString, execDatagramMessage, execDestMessage, execNamingMessage, execRawMessage, execStreamClose, execStreamSend, getDatagramSession, getRawSession, getStreamSession, notifyStreamDisconnection, notifyStreamIncomingConnection, notifyStreamOutgoingConnection, notifyStreamSendBufferFree, receiveDatagramBytes, receiveRawBytes, receiveStreamBytes, stopDatagramReceiving, stopRawReceiving, stopStreamReceiving, streamSendAnswer, writeString
Modifier and Type
Method
Description
protected static String
createMessageString(String msg)
Create a string to be appended to a status.
protected boolean
execDatagramMessage(String opcode, Properties props)
Parse and execute a DATAGRAM message.
protected boolean
execDestMessage(String opcode, Properties props)
Parse and execute a DEST message.
protected boolean
execNamingMessage(String opcode, Properties props)
Parse and execute a NAMING message.
protected boolean
execRawMessage(String opcode, Properties props)
Parse and execute a RAW message.
protected boolean
execStreamClose(Properties props)
Parse and execute a STREAM CLOSE message.
protected boolean
execStreamSend(Properties props)
Parse and execute a STREAM SEND message.
protected final SAMMessageSess
getDatagramSession()
Return the datagram session.
protected final SAMMessageSess
getRawSession()
Return the raw session.
protected final SAMStreamSession
getStreamSession()
Return the stream session.
void
notifyStreamDisconnection(int id, String result, String msg)
Notify the SAM client that a stream connection has been disconnected.
void
notifyStreamIncomingConnection(int id, Destination d)
Notify the SAM client of an incoming stream connection.
void
notifyStreamOutgoingConnection(int id, String result, String msg)
Report the result of an outgoing stream connection.
void
notifyStreamSendBufferFree(int id)
Notify the SAM client that the stream send buffer is free for more data.
void
receiveDatagramBytes(Destination sender, byte[] data, int proto, int fromPort, int toPort)
Receive datagram bytes from the network and forward them to the SAM client.
void
receiveRawBytes(byte[] data, int proto, int fromPort, int toPort)
Receive raw bytes from the network and forward them to the SAM client.
void
receiveStreamBytes(int id, ByteBuffer data)
Receive stream bytes from the network and forward them to the SAM client.
void
stopDatagramReceiving()
Stop receiving datagram bytes and close the client socket.
void
stopRawReceiving()
Stop receiving raw bytes and close the client socket.
void
stopStreamReceiving()
Stop receiving stream bytes and close the client socket.
void
streamSendAnswer(int id, String result, String bufferState)
Notify the SAM client of the result of a stream SEND operation.
protected boolean
writeString(String s, String msg)
Write a string and message, escaping the message.
Methods inherited from class SAMHandler
closeClientSocket, getAuthUser, getClientSocket, getRemoteAddrPort, getWriteLock, isLoopbackAddress, logSessionError, run, sameClient, sameClient, setAuthUser, shouldStop, startHandling, toString, writeBytes, writeString, writeString
Modifier and Type
Method
Description
protected final void
closeClientSocket()
Close the socket connected to the SAM client.
(package private) final String
getAuthUser()
Get the username this connection authenticated with, if any.
protected final SocketChannel
getClientSocket()
Get the channel of the socket connected to the SAM client.
(package private) final String
getRemoteAddrPort()
Get the remote address and port of this connection, bracketing IPv6, for rejection and ban logging.
protected Object
getWriteLock()
If you're crazy enough to write to the raw socket, grab the write lock with SAMHandler.getWriteLock(), synchronize against it, and write to the getOut().
(package private) static boolean
isLoopbackAddress(String host)
Determine whether an address is a loopback address, in any of the forms the platform may report it.
protected void
logSessionError(String msg, Exception e)
Log a session startup failure.
final void
run()
Register with the bridge, call SAMHandler.handle(), unregister with the bridge.
(package private) static boolean
sameClient(String myAuthUser, String otherAuthUser, String myHost, String otherHost)
Decide whether two SAM connections belong to the same client.
(package private) final boolean
sameClient(SAMHandler other)
Determine whether two connections belong to the same client, which is what decides whether one of them may use a session nickname owned by the other.
(package private) final void
setAuthUser(String user)
Record the username this connection authenticated with.
protected final boolean
shouldStop()
Should the handler be stopped?
void
startHandling()
Start handling the SAM connection, detaching a handling thread.
final String
toString()
Get a string describing the handler.
protected final void
writeBytes(ByteBuffer data)
Write a byte array on the handler's socket.
protected final boolean
writeString(String str)
Write a string to the handler's socket.
static boolean
writeString(String str, SocketChannel out)
Unsynchronized, use with caution.
Methods inherited from class Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details
- session
  private Session session
  I2P session.
- sSessionsHash
  public static final SessionsDB sSessionsHash
  Global session-id to handler map shared by every SAMv3 bridge.
- stolenSocket
  volatile boolean stolenSocket
  Stolen socket.
- streamForwardingSocket
  volatile boolean streamForwardingSocket
  Stream forwarding socket.
- sessionReady
  private volatile boolean sessionReady
  True once the SESSION CREATE has fully initialized; guards against race in execStreamMessage.
- sendPorts
  final boolean sendPorts
  Package-visible so SAMHandlerPool can read it.
- AUTH_ERROR
  private static final String AUTH_ERROR
  Authentication error message.
  See Also:
  Constant Field Values
Constructor Details
- SAMv3Handler
  public SAMv3Handler(SocketChannel s, int verMajor, int verMinor, SAMBridge parent) throws SAMException, IOException
  Create a new SAM version 3 handler. This constructor expects that the SAM HELLO message has been still answered (and stripped) from the socket input stream.
  Parameters:
  s - Socket attached to a SAM client
  verMajor - SAM major version to manage (should be 3)
  verMinor - SAM minor version to manage
  parent - the bridge owning this handler and the handler pool it came from
  Throws:
  SAMException - if the version is not supported
  IOException - if an I/O error occurs
- SAMv3Handler
  public SAMv3Handler(SocketChannel s, int verMajor, int verMinor, Properties i2cpProps, SAMBridge parent) throws SAMException, IOException
  Create a new SAM version 3 handler. This constructor expects that the SAM HELLO message has been still answered (and stripped) from the socket input stream.
  Parameters:
  s - Socket attached to a SAM client
  verMajor - SAM major version to manage (should be 3)
  verMinor - SAM minor version to manage
  i2cpProps - properties to configure the I2CP connection (host, port, etc)
  parent - the bridge owning this handler and the handler pool it came from
  Throws:
  SAMException - if the version is not supported
  IOException - if an I/O error occurs
Method Details
- verifVersion
  public boolean verifVersion()
  Verify the SAM protocol version is supported by this handler.
  Overrides:
  verifVersion in class SAMv1Handler
  Returns:
  true if the major version matches this handler's version
- getClientIP
  public String getClientIP()
  Get the IP address of the connected SAM client.
  Returns:
  the client's IP address as a string
- hasActiveStream
  boolean hasActiveStream()
  Whether a client data stream has been taken over by this handler.
  Returns:
  true if the handler has an active data stream (stolen or forwarding)
- stealSocket
  public void stealSocket()
  For SAMv3StreamSession connect and accept.
- getBridge
  SAMBridge getBridge()
  For SAMv3StreamSession.
  Returns:
  the bridge owning this handler
- getSession
  Session getSession()
  For SAMv3DatagramServer.
  Returns:
  may be null
- setSession
  void setSession(SAMv3RawSession sess)
  For subsessions created by MasterSession.
  Parameters:
  sess - the raw session to route reply traffic to
- setSession
  void setSession(SAMv3DatagramSession sess)
  For subsessions created by MasterSession.
  Parameters:
  sess - the datagram session to route reply traffic to
- setSession
  void setSession(SAMv3StreamSession sess)
  For subsessions created by MasterSession.
  Parameters:
  sess - the stream session to route reply traffic to; setting it also marks the session ready
- processLine
  boolean processLine(String line)
  Process a single complete command line dispatched by the pool or the legacy handle() loop. Returns false to signal the caller that the handler should stop.
  Parameters:
  line - the complete command line (without trailing newline)
  Returns:
  true if the handler should continue processing commands
- handle
  public void handle()
  Legacy handle() method. Not used when the handler is managed by SAMHandlerPool, which dispatches via processLine(). Retained to fulfill the abstract contract in SAMHandler.
  Overrides:
  handle in class SAMv1Handler
- stopHandling
  public void stopHandling()
  Stop the SAM handler, close the socket (unless stolen), unregister from the bridge and the handler pool.
  Specified by:
  stopHandling in interface Handler
  Overrides:
  stopHandling in class SAMHandler
- die
  private void die()
  Terminate the handler.
- execSessionMessage
  protected boolean execSessionMessage(String opcode, Properties props)
  Parse and execute a SESSION message.
  Overrides:
  execSessionMessage in class SAMv1Handler
  Parameters:
  opcode - the SESSION sub-command (e.g. CREATE, ADD, REMOVE)
  props - the parsed message properties
  Returns:
  true if the handler should continue processing commands
- execSessionCreate
  private boolean execSessionCreate(String nick, Properties props)
  Execute SESSION CREATE — generates or validates a destination, registers the nick, builds tunnels, and creates the session object.
  Parameters:
  nick - validated session ID
  props - parsed message properties
  Returns:
  true if the handler should continue processing
- initDestination
  private static String initDestination(String dest, Properties props) throws DataFormatException
  Resolve TRANSIENT or validate a user-supplied private key.
  Parameters:
  dest - DESTINATION value, may be "TRANSIENT"
  props - properties (SIGNATURE_TYPE consumed if TRANSIENT)
  Returns:
  Base64-encoded private key
  Throws:
  DataFormatException - if SIGNATURE_TYPE names an unsupported type, or the supplied DESTINATION is not a valid private destination
- instantiateSession
  private void instantiateSession(String style, String nick, Properties allProps, Properties props) throws DataFormatException, I2PSessionException, IOException, SAMException
  Create and start the session object for the given style. Blocks in the session constructors while tunnels are built.
  Parameters:
  style - session style: RAW, DATAGRAM, STREAM, MASTER or PRIMARY
  nick - session nickname, used as the session ID
  allProps - all message properties, handed to a MASTER session
  props - message properties, used to build the datagram server
  Throws:
  DataFormatException - if stored destination or key data is malformed
  I2PSessionException - if the underlying I2P session cannot be created
  IOException - if the datagram server cannot bind its host and port, or the session constructors hit an I/O error
  SAMException - if the style is not one of the recognized values, or the I2P session cannot be created
- execSessionAddRemove
  private boolean execSessionAddRemove(String opcode, String nick, Properties props)
  Execute SESSION ADD or REMOVE for MASTER sessions.
  Parameters:
  opcode - the sub-command, ADD or REMOVE
  nick - session ID of the sub-session to add or remove
  props - message properties, STYLE consumed when adding
  Returns:
  true if the handler should continue processing commands
- newSAMStreamSession
  private static SAMv3StreamSession newSAMStreamSession(String login) throws IOException, DataFormatException, SAMException
  Create a stream session for a login.
  Parameters:
  login - nickname of the registered session to reuse
  Returns:
  the new, not yet started, stream session
  Throws:
  NullPointerException - if login nickname is not registered
  IOException - if the stored key stream cannot be read or the I2CP connection fails
  DataFormatException - if the stored destination or key data is malformed
  SAMException - if the I2CP port property is not a number, or the I2P session cannot be created
- execStreamMessage
  protected boolean execStreamMessage(String opcode, Properties props)
  Parse and execute a STREAM message.
  Overrides:
  execStreamMessage in class SAMv1Handler
  Parameters:
  opcode - the STREAM sub-command (e.g. CONNECT, ACCEPT, FORWARD)
  props - the parsed message properties
  Returns:
  true if the handler should continue processing commands
- execStreamConnect
  protected boolean execStreamConnect(Properties props)
  Parse and execute a STREAM CONNECT message. Dispatches the blocking I2P socket connect to a shared connector pool so the caller's worker thread is never blocked. Error responses (CONNECTION_REFUSED, CANT_REACH_PEER, TIMEOUT, etc.) are sent asynchronously by the ConnectTask.
  Supports SILENT mode to suppress status messages.
  Overrides:
  execStreamConnect in class SAMv1Handler
  Parameters:
  props - the parsed message properties
  Returns:
  true if the handler should continue processing commands
- execStreamForwardIncoming
  private boolean execStreamForwardIncoming(Properties props)
  Exec stream forward incoming.
  Parameters:
  props - the parsed message properties, including the receiver PORT and SILENT flag
  Returns:
  true if forwarding was started, false when it failed
- execStreamAccept
  private boolean execStreamAccept(Properties props)
  Execute STREAM ACCEPT. Sends "OK" synchronously and starts the blocking accept in a background thread. Result (TIMEOUT, I2P_ERROR, or the actual streaming data) arrives asynchronously.
  Parameters:
  props - the parsed message properties, SILENT flag read
  Returns:
  true if accept was launched, false on immediate error
- notifyStreamResult
  public void notifyStreamResult(boolean verbose, String result, String message) throws IOException
  Send a STREAM STATUS RESULT line to the SAM client, unless verbose is false.
  Parameters:
  verbose - if false, does nothing
  result - non-null
  message - may be null
  Throws:
  IOException - if writing the status line to the SAM client socket fails
- notifyStreamIncomingConnection
  public void notifyStreamIncomingConnection(Destination d, int fromPort, int toPort) throws IOException
  Tells the SAM client a new stream connection arrived, naming the ports when requested.
  Parameters:
  d - the destination of the incoming connection
  fromPort - the remote port the connection arrived on
  toPort - the local port the connection was accepted on
  Throws:
  IOException - if writing to the SAM client socket fails
- notifyStreamIncomingConnection
  public static void notifyStreamIncomingConnection(SocketChannel client, Destination d) throws IOException
  Notify the SAM client of an incoming stream connection on a static channel.
  Parameters:
  client - the channel to the SAM client the notification is written to
  d - the destination of the remote peer
  Throws:
  IOException - if writing to the client socket fails
- notifyStreamIncomingConnection
  public static void notifyStreamIncomingConnection(SocketChannel client, Destination d, int fromPort, int toPort) throws IOException
  Notify the SAM client of an incoming stream connection with port information.
  Parameters:
  client - the channel to the SAM client the notification is written to
  d - the destination of the remote peer
  fromPort - the source port
  toPort - the destination port
  Throws:
  IOException - if writing to the client socket fails
- mayManageAuth
  boolean mayManageAuth()
  Determine whether this connection may change the bridge's authentication configuration. AUTH commands rewrite the credentials every future connection must present and are persisted to disk, so they are accepted only from the local host, or from a connection that authenticated when it connected.
  Returns:
  true if AUTH commands from this connection are accepted
- mayManageAuth
  static boolean mayManageAuth(boolean fromLoopback, String authUser, boolean authEnabled)
  Decide whether an AUTH command may be issued from a connection.
  Parameters:
  fromLoopback - whether the connection is from the local host
  authUser - the user the connection authenticated as, may be null
  authEnabled - whether bridge authentication is currently enabled
  Returns:
  true if AUTH commands from such a connection are accepted
- mayUseSession
  boolean mayUseSession(SessionRecord rec)
  Determine whether this connection may operate on a session created by another connection. STREAM commands are issued from a connection other than the one that created the session, and nicknames are shared by the whole bridge, so access is allowed to the owning connection itself and to connections belonging to the same client: the same authenticated user, or the same address when authentication is disabled.
  Parameters:
  rec - the looked-up session record, may be null
  Returns:
  true if this connection may use that session
- execAuthMessage
  private boolean execAuthMessage(String opcode, Properties props)
  Handle the AUTH message.
  Parameters:
  opcode - the AUTH sub-command: ENABLE, DISABLE, ADD or REMOVE
  props - the parsed message properties, USER and PASSWORD read for ADD and REMOVE
  Returns:
  true if the handler should continue processing commands

Field Summary

Fields inherited from class SAMv1Handler

Fields inherited from class SAMHandler

Constructor Summary

Method Summary

Methods inherited from class SAMv1Handler

Methods inherited from class SAMHandler

Methods inherited from class Object

Field Details

session

sSessionsHash

stolenSocket

streamForwardingSocket

sessionReady

sendPorts

AUTH_ERROR

Constructor Details

SAMv3Handler

Method Details

verifVersion

getClientIP

hasActiveStream

stealSocket

getBridge

getSession

setSession

setSession

setSession

processLine

handle

stopHandling

die

execSessionMessage

execSessionCreate

initDestination

instantiateSession

execSessionAddRemove

newSAMStreamSession

execStreamMessage

execStreamConnect

execStreamForwardIncoming

execStreamAccept

notifyStreamResult

notifyStreamIncomingConnection

notifyStreamIncomingConnection

notifyStreamIncomingConnection

mayManageAuth

mayManageAuth

mayUseSession

execAuthMessage