Specified below is version 1 of a simple client protocol for interacting with I2P. Newer alternatives: SAM V2, SAM V3, BOB.
The reported version remains "1.0".
---------------------------------------------------------------------- Simple Anonymous Messaging (SAM version 1.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=1.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 "1" and less than "2" to use version 1. 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. ---------------------------------------------------------------------- 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 %}