{% extends "global/layout.html" %} {% block title %}SAM V2 Specification{% endblock %} {% block lastupdated %}July 2014{% endblock %} {% block accuratefor %}0.9.14{% endblock %} {% block content %}
Specified below is a simple client protocol for interacting with I2P.
SAM V2 was introduced in I2P release 0.6.1.31. Significant differences from SAM V1 are marked with "***". Alternatives: SAM V1, SAM V3, BOB.
SAM V2 was introduced in I2P release 0.6.1.31. Compared to version 1, SAM v2 provides a way to manage several sockets on the same I2P destination in parallel, i.e. the client does not have to wait for data being successfully sent on one socket before sending data on another socket. All data transits through the same client<-->SAM socket. For multiple sockets, see SAM V3.
The reported version remains "2.0".
---------------------------------------------------------------------- Simple Anonymous Messaging (SAM version 2.0) Specification ---------------------------------------------------------------------- Client application talks to SAM bridge, which deals with all of the I2P functionality (using the streaming lib for virtual streams, or I2CP directly for async messages). All client<-->SAM bridge communication is unencrypted and unauthenticated over a single TCP socket. Access to the SAM bridge should be protected through firewalls or other means (perhaps the bridge may have ACLs on what IPs it accepts connections from). All of these SAM messages are sent on a single line in plain ASCII, terminated by the newline character (\n). The formatting shown below is merely for readability, and while the first two words in each message must stay in their specific order, the ordering of the key=value pairs can change (e.g. "ONE TWO A=B C=D" or "ONE TWO C=D A=B" are both perfectly valid constructions). In addition, the protocol is case-sensitive. Communication can take three distinct forms: * Virtual streams * Repliable datagrams (messages with a FROM field) * Anonymous datagrams (raw anonymous messages) ---------------------------------------------------------------------- SAM connection handshake ---------------------------------------------------------------------- No SAM communication can occur until after the client and bridge have agreed on a protocol version, which is done by the client sending a HELLO and the bridge sending a HELLO REPLY: HELLO VERSION MIN=$min MAX=$max and *** HELLO REPLY RESULT=$result VERSION=2.0 As of I2P 0.9.14, the MIN parameter is optional. The MAX parameter must be provided and be greater than or equal to "2" and less than "3" to use version 2. The RESULT value may be one of: OK NOVERSION ---------------------------------------------------------------------- SAM sessions ---------------------------------------------------------------------- A SAM session is created by a client opening a socket to the SAM bridge, operating a handshake, and sending a SESSION CREATE message, and the session terminates when the socket is disconnected. Each I2P Destination can only be used for one SAM session at a time, and can only use one of those forms (messages received through other forms are dropped). The SESSION CREATE message sent by the client to the bridge is as follows: SESSION CREATE STYLE={STREAM,DATAGRAM,RAW} DESTINATION={$name,TRANSIENT} [DIRECTION={BOTH,RECEIVE,CREATE}] [option=value]* DESTINATION specifies what destination should be used for sending and receiving messages/streams. If a $name is given, the SAM bridge looks through its own local storage (the sam.keys file) for an associated destination (and private key). If no association exists matching that name, it creates a new one. If the destination is specified as TRANSIENT, it always creates a new one. Note that DESTINATION is an identifier, not Base 64 encoded data. To specify the Destination, you must use Key Certificates. The default is DSA_SHA1. ---------------------------------------------------------------------- RESULT values ---------------------------------------------------------------------- These are the values that can be carried by the RESULT field, with their meaning: OK Operation completed successfully CANT_REACH_PEER The peer exists, but cannot be reached DUPLICATED_DEST The specified Destination is already in use I2P_ERROR A generic I2P error (e.g. I2CP disconnection, etc.) INVALID_KEY The specified key is not valid (bad format, etc.) KEY_NOT_FOUND The naming system can't resolve the given name PEER_NOT_FOUND The peer cannot be found on the network TIMEOUT Timeout while waiting for an event (e.g. peer answer) ---------------------------------------------------------------------- Tunnel, I2CP, and Streaming Options ---------------------------------------------------------------------- These options may be passed in as name=value pairs at the end of a SAM SESSION CREATE line. All sessions may include I2CP options such as tunnel lengths. STREAM sessions may include Streaming lib options. See those references for option names and defaults. ---------------------------------------------------------------------- BASE 64 Notes ---------------------------------------------------------------------- Base 64 encoding must use the I2P standard Base 64 alphabet "A-Z, a-z, 0-9, -, ~". ---------------------------------------------------------------------- Client library implementations: ---------------------------------------------------------------------- Client libraries are available for C, C++, C#, Perl, and Python. These are in the apps/sam/ directory in the I2P Source Package. Some may be older and have not been updated for SAMv2 support. ---------------------------------------------------------------------- Default SAM Setup ---------------------------------------------------------------------- The default SAM port is 7656. SAM is not enabled by default in the I2P Router; it must be started manually, or configured to start automatically, on the configure clients page in the router console, or in the clients.config file.{% endblock %}