source: apps/sam/doc/sam.3.0-protocol.txt @ 868e5e9

Last change on this file since 868e5e9 was 965b183d, checked in by mkvore-commit <mkvore-commit@…>, 12 years ago

fix: warnings when generating javadoc

  • Property mode set to 100644
File size: 17.5 KB
Line 
1----------------------------------------------------------------------
2Simple Anonymous Messaging (SAM version 3.0)
3----------------------------------------------------------------------
4Client application talks to SAM bridge, which deals with
5all of the I2P functionality (using the ministreaming
6lib for virtual streams, or I2CP directly for async messages).
7
8All client<-->SAM bridge communication is unencrypted and
9unauthenticated.  Access to the SAM
10bridge should be protected through firewalls or other means
11(perhaps the bridge may have ACLs on what IPs it accepts
12connections from).
13
14All of these SAM messages are sent on a single line in plain ASCII,
15terminated by the newline character (\n).  The formatting shown
16below is merely for readability, and while the first two words in
17each message must stay in their specific order, the ordering of
18the key=value pairs can change (e.g. "ONE TWO A=B C=D" or
19"ONE TWO C=D A=B" are both perfectly valid constructions).  In
20addition, the protocol is case-sensitive.
21In the following, message examples are preceded by "-> " for
22messages sent by the client to the SAM bridge, and by "<- " for
23messages sent by the SAM bridge to the client.
24
25I2P communications can take three distinct forms:
26* Virtual streams
27* Repliable datagrams (messages with a FROM field)
28* Anonymous datagrams (raw anonymous messages)
29
30I2P communications are supported by I2P sessions, and each I2P
31session is bound to an address (called destination). An I2P session
32is associated with one of the three types above, and cannot carry
33communications of another type.
34
35 
36----------------------------------------------------------------------
37SAM connection handshake
38----------------------------------------------------------------------
39No SAM communication can occur until after the client and bridge have
40agreed on a protocol version, which is done by the client sending
41a HELLO and the bridge sending a HELLO REPLY:
42
43->  HELLO VERSION MIN=$min MAX=$max
44
45and
46
47<-  HELLO REPLY RESULT=OK VERSION=3.0
48
49*** In order to force protocol version 3.0, the values of $min and $max
50*** must be "3.0".
51
52If the SAM bridge cannot find a suitable version, it replies with :
53
54<- HELLO REPLY RESULT=NOVERSION
55
56If some error occurred, such as a bad request format, it replies with :
57
58<- HELLO REPLY RESULT=I2P_ERROR MESSAGE={$message}
59
60
61----------------------------------------------------------------------
62SAM sessions
63----------------------------------------------------------------------
64A SAM session is created by a client opening a socket to the SAM
65bridge, operating a handshake, and sending a SESSION CREATE message,
66and the session terminates when the socket is disconnected.
67
68Each registered I2P Destination is uniquely associated with a session ID
69(or nickname).
70
71Each session is uniquely associated with :
72 * the socket from which the client creates the session
73 * its ID (or nickname)
74
75The session creation message can only use one of these forms (messages
76received through other forms are answered with an error message) :
77
78->  SESSION CREATE
79          STYLE={STREAM,DATAGRAM,RAW}
80          ID={$nickname}
81          DESTINATION={$private_destination_key,TRANSIENT}
82          [option=value]*
83
84DESTINATION specifies what destination should be used for
85sending and receiving messages/streams.  It has to be a suitable
86private base64 destination key. If the destination is
87specified as TRANSIENT, the SAM bridge creates a new destination.
88
89{$nickname} is the choice of the client. No whitespace is allowed.
90
91Additional options given are passed to the I2P session
92configuration if not interpreted by the SAM bridge (e.g.
93outbound.length=0). These options are documented below.
94
95The SAM bridge itself should already be configured with what router
96it should communicate over I2P through (though if need be there may
97be a way to provide an override, e.g. i2cp.tcp.host=localhost and
98i2cp.tcp.port=7654).
99
100After receiving the session create message, the SAM bridge will reply
101with a session status message, as follows:
102
103If the creation was successful :
104<-  SESSION STATUS RESULT=OK DESTINATION={$private_destination_key}
105
106If the nickname is already associated with a session :
107<-  SESSION STATUS RESULT=DUPLICATED_ID
108
109If the destination is already in use :
110<-  SESSION STATUS RESULT=DUPLICATED_DEST
111
112If the destination is not a valid private destination key :
113<-  SESSION STATUS RESULT=INVALID_KEY
114
115If some other error has occurred :
116<-  SESSION STATUS RESULT=I2P_ERROR MESSAGE={$message}
117
118If it's not OK, the MESSAGE should contain human-readable information
119as to why the session could not be created.
120
121
122SAM sessions live and die with the socket they are associated with.
123When the socket is closed, the session dies, and all communications
124using the session die at the same time. And the other way round, when
125the session dies for any reason, the SAM bridge closes the socket.
126
127
128----------------------------------------------------------------------
129SAM virtual streams
130----------------------------------------------------------------------
131Virtual streams are guaranteed to be sent reliably and in order, with
132failure and success notification as soon as it is available.
133
134Streams are bidirectional communication sockets between two I2P
135destinations, but their opening has to be requested by one of them.
136Hereafter, CONNECT commands are used by the SAM client for such a
137request. FORWARD / ACCEPT commands are used by the SAM client when
138he wants to listen to requests coming from other I2P destinations.
139
140
141-----------------------------
142SAM virtual streams : CONNECT
143-----------------------------
144A client asks for a connection by :
145 * opening a new socket with the SAM bridge
146 * passing the same HELLO handshake as above
147 * sending the connection command : 
148
149-> STREAM CONNECT
150         ID={$nickname}
151         DESTINATION=$peer_public_base64_key
152         [SILENCE={true,false}]
153
154This establishes a new virtual connection from the local session
155whose ID is {$nickname} to the specified peer.
156
157If SILENCE=true is passed, the SAM bridge won't issue any other message
158on the socket : if the connection fails, the socket will be closed.
159If the connection succeeds, all remaining data passing through the
160current socket is forwarded from and to the connected I2P destination
161peer.
162
163If SILENCE=false, which is the default value, the SAM bridge sends a
164last message to its client before forwarding or shutting down the
165socket :
166
167<-  STREAM STATUS
168         RESULT=$result
169         [MESSAGE=...]
170
171The RESULT value may be one of:
172
173    OK
174    CANT_REACH_PEER
175    I2P_ERROR
176    INVALID_KEY
177    INVALID_ID
178    TIMEOUT
179
180If the RESULT is OK, all remaining data passing through the
181current socket is forwarded from and to the connected I2P destination
182peer. If the connection was not possible (timeout, etc),
183RESULT will contain the appropriate error value (accompanied by an
184optional human-readable MESSAGE), and the SAM bridge closes the
185socket.
186
187----------------------------
188SAM virtual streams : ACCEPT
189----------------------------
190
191A client waits for an incoming connection request by :
192 * opening a new socket with the SAM bridge
193 * passing the same HELLO handshake as above
194 * sending the accept command : 
195
196-> STREAM ACCEPT
197         ID={$nickname}
198         [SILENCE={true,false}]
199
200This makes the session ${nickname} listen for one incoming
201connection request from the I2P network.
202
203The SAM bridge answers with :
204
205<-  STREAM STATUS
206         RESULT=$result
207         [MESSAGE=...]
208
209The RESULT value may be one of:
210
211    OK
212    I2P_ERROR
213    INVALID_ID
214
215If the result is not OK, the socket is closed immediately by the SAM
216bridge. If the result is OK, the SAM bridge starts waiting for an
217incoming connection request from another I2P peer. When a request
218arrives, the SAM bridge accepts it and :
219
220 * If SILENCE=true was passed, the SAM bridge won't issue any other message
221on the client socket : all remaining data passing through the
222current socket is forwarded from and to the connected I2P destination
223peer.
224 * If SILENCE=false was passed, which is the default value, the SAM bridge
225sends the client an ASCII line containing the base64 public destination key
226of the requesting peer. After this '\n' terminated line, all remaining data
227passing through the current socket is forwarded from and to the connected
228I2P destination peer, until one of the peer closes the socket.
229
230-----------------------------
231SAM virtual streams : FORWARD
232-----------------------------
233
234A client can use a regular socket server and wait for connection requests
235coming from I2P. For that, the client has to :
236 * open a new socket with the SAM bridge
237 * pass the same HELLO handshake as above
238 * send the forward command :
239
240-> STREAM FORWARD
241         ID={$nickname}
242         PORT={$port}
243         [HOST={$host}]
244         [SILENCE={true,false}]
245
246This makes the session ${nickname} listen for incoming
247connection requests from the I2P network.
248
249The SAM bridge answers with :
250
251<-  STREAM STATUS
252         RESULT=$result
253         [MESSAGE=...]
254
255The RESULT value may be one of:
256
257    OK
258    I2P_ERROR
259    INVALID_ID
260
261 * {$host} is the hostname or IP address of the socket server to which
262SAM will forward connection requests. If not given, SAM takes the IP
263of the socket that issued the forward command.
264
265 * {$port} is the port number of the socket server to which SAM will
266forward connection requests. It is mandatory.
267
268When a connexion request arrives from I2P, the SAM bridge requests a
269socket connexion from {$host}:{$port}. If it is accepted after no more
270than 3 seconds, SAM will accept the connexion from I2P, and then :
271
272 * If SILENCE=true was passed, all data passing through the obtained
273current socket is forwarded from and to the connected I2P destination
274peer.
275 * If SILENCE=false was passed, which is the default value, the SAM bridge
276sends on the obtained socket an ASCII line containing the base64 public
277destination key of the requesting peer. After this '\n' terminated line,
278all remaining data passing through the socket is forwarded from and to
279the connected I2P destination peer, until one of the sides closes the
280socket.
281
282
283
284The I2P router will stop listening to incoming connection requests as
285soon as the "forwarding" socket is closed.
286
287
288
289
290----------------------------------------------------------------------
291SAM repliable datagrams : sending a datagram
292----------------------------------------------------------------------
293While I2P doesn't inherently contain a FROM address, for ease of use
294an additional layer is provided as repliable datagrams - unordered
295and unreliable messages of up to 31KB in size that include a FROM
296address (leaving up to 1KB for header material).  This FROM address
297is authenticated internally by SAM (making use of the destination's
298signing key to verify the source) and includes replay prevention.
299
300** First method :
301
302After establishing a SAM session with STYLE=DATAGRAM, the client can
303send datagrams through SAM's UDP port (7655).
304
305The first line of a datagram sent through this port has to be in the
306following format :
307
3083.0 {$nickname} {$base64_public_destination_key}
309
310 * 3.0 is the version of SAM
311 * {$nickname} is the id of the DGRAM session that will be used
312 * {$base64_public_destination_key} is the destination of the
313    datagram
314 * this line is '\n' terminated.
315
316The first line will be discarded by SAM before sending the remaining
317of the message to the specified destination.
318
319** Second method :
320
321Datagrams can also be sent through the socket from which the datagram
322session was opened. See the "DATAGRAM SEND" command of SAM versions 1
323and 2.
324
325----------------------------------------------------------------------
326SAM repliable datagrams : receiving a datagram
327----------------------------------------------------------------------
328Received datagrams are written by SAM on the socket from which the
329datagram session was opened, unless specified otherwise by the CREATE
330command.
331
332When a datagram arrives, the bridge delivers it to the client via the
333message :
334
335<-  DATAGRAM RECEIVED
336           DESTINATION=$base64key
337           SIZE=$numBytes\n[$numBytes of data]
338
339The SAM bridge never exposes to the client the authentication headers
340or other fields, merely the data that the sender provided.  This
341continues until the session is closed (by the client dropping the
342connection).
343
344----------------------------------------------------------------------
345SAM repliable datagrams : forwarding datagrams
346----------------------------------------------------------------------
347When creating a datagram session, the client can ask SAM to forward
348incoming messages to a specified ip:port. It does so by issuing the
349CREATE command with PORT and HOST options :
350
351-> SESSION CREATE
352          STYLE=DATAGRAM
353          ID={$nickname}
354          DESTINATION={$private_destination_key,TRANSIENT}
355          PORT={$port}
356          [HOST={$host}]
357          [option=value]*
358
359 * {$host} is the hostname or IP address of the datagram server to
360     which SAM will forward datagrams. If not given, SAM takes the
361     IP of the socket that issued the forward command.
362
363 * {$port} is the port number of the datagram server to which SAM
364     will forward datagrams.
365
366When a datagram arrives, the bridge sends to the specified host:port
367a message containing the following data :
368
369${sender_base64_destination_key}\n{$datagram_payload}
370
371
372----------------------------------------------------------------------
373SAM anonymous datagrams
374----------------------------------------------------------------------
375Squeezing the most out of I2P's bandwidth, SAM allows clients to send
376and receive anonymous datagrams, leaving authentication and reply
377information up to the client themselves.  These datagrams are
378unreliable and unordered, and may be up to 32KB in size.
379
380After establishing a SAM session with STYLE=RAW, the client can
381send anonymous datagrams throug the SAM bridge exactly the same way
382he sends non anonymous datagrams.
383
384Both ways of receiving datagrams are also available for anonymous
385datagrams.
386
387When anonymous datagrams are to be written to the socket that created
388the session,the bridge delivers it to the client via:
389
390<- RAW RECEIVED
391      SIZE=$numBytes\n[$numBytes of data]
392
393When anonymous datagrams are to be forwarded to some host:port,
394the bridge sends to the specified host:port a message containing
395the following data :
396
397{$datagram_payload}
398
399
400----------------------------------------------------------------------
401SAM utility functionality
402----------------------------------------------------------------------
403The following message can be used by the client to query the SAM
404bridge for name resolution:
405
406 NAMING LOOKUP
407        NAME=$name
408
409which is answered by
410
411 NAMING REPLY
412        RESULT=$result
413        NAME=$name
414        [VALUE=$base64key]
415        [MESSAGE=$message]
416
417
418The RESULT value may be one of:
419
420    OK
421    INVALID_KEY
422    KEY_NOT_FOUND
423
424If NAME=ME, then the reply will contain the base64key used by the
425current session (useful if you're using a TRANSIENT one).  If $result
426is not OK, MESSAGE may convey a descriptive message, such as "bad
427format", etc.
428
429Public and private base64 keys can be generated using the following
430message:
431
432 DEST GENERATE
433
434which is answered by
435
436 DEST REPLY
437      PUB=$pubkey
438      PRIV=$privkey
439
440----------------------------------------------------------------------
441RESULT values
442----------------------------------------------------------------------
443These are the values that can be carried by the RESULT field, with
444their meaning:
445
446 OK              Operation completed succesfully
447 CANT_REACH_PEER The peer exists, but cannot be reached
448 DUPLICATED_DEST The specified Destination is already in use
449 I2P_ERROR       A generic I2P error (e.g. I2CP disconnection, etc.)
450 INVALID_KEY     The specified key is not valid (bad format, etc.)
451 KEY_NOT_FOUND   The naming system can't resolve the given name
452 PEER_NOT_FOUND  The peer cannot be found on the network
453 TIMEOUT         Timeout while waiting for an event (e.g. peer answer)
454
455----------------------------------------------------------------------
456Tunnel Pool Options
457----------------------------------------------------------------------
458
459These options can be passed in as name=value pairs at the end of a
460SAM SESSION CREATE line.
461
462 inbound.nickname            - Name shows up in I2P router console.
463 inbound.quantity            - Number of tunnels, default 2.
464 inbound.backupQuantity      - Number of backup tunnels, default 0.
465 inbound.rebuildPeriod       - Obsolete - ignored - the router controls rebuilding
466 inbound.duration            - Tunnels last X ms, default 10*60*1000.
467                               (change not recommended, will break anonymmity
468                                if it works at all)
469 inbound.length              - Depth of tunnels, default 2.
470 inbound.lengthVariance      - If negative, randomly skews from
471                               (length - variance) to
472                               (length + variance).  If positive, from
473                               length to (length + var), inclusive.
474                               Default -1.
475 inbound.allowZeroHop        - Zero hop allowed?  Default "true".
476 outbound.*                  - Same properties as inbound.
477 i2p.streaming.connectDelay  - If 0, connect ASAP.  If positive, wait
478                               until X ms have passed or output stream
479                               is flushed or buffer fills.  Default 0.
480 i2p.streaming.maxWindowSize - Max window size, default 64.
481
482----------------------------------------------------------------------
483Client library implementations:
484----------------------------------------------------------------------
485 C/C++:  libSAM: http://www.innographx.com/mpc/libsam/ or i2p/sam/c/
486 Python: Python/I2P: http://dev.i2p.net/contrib/apps/sam/python/index.html
487 Others: See apps/sam/ in I2P CVS.
Note: See TracBrowser for help on using the repository browser.