Skip navigation

SAM V1 Specification

This page was last updated in July 2014 and is accurate for router version 0.9.14.

SAM V1 Specification

Specified below is version 1 of a simple client protocol for interacting with I2P. Newer alternatives: SAM V2, SAM V3, BOB.

Language libraries for the SAMv1 API

  • C
  • C#
  • Perl
  • Python
The libraries are in the I2P source repository.

I2P 0.9.14 Changes

The reported version remains "1.0".

  • DEST GENERATE now supports a SIGNATURE_TYPE parameter.
  • The MIN parameter in HELLO VERSION is now optional.
  • The MIN and MAX parameters in HELLO VERSION now support single-digit versions such as "3".

Version 1 Protocol

----------------------------------------------------------------------
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.