source: apps/sam/doc/sam.3.0-protocol.txt @ 4ffa2450

Last change on this file since 4ffa2450 was 4ffa2450, checked in by mkvore-commit <mkvore-commit@…>, 12 years ago
  • SAMv3 : doc/sam.3.0-protocol.txt updated
  • SAMv3 : SAMv3StreamSession.java: thread naming for debugging purpose
  • Property mode set to 100644
File size: 17.3 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 a 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
300After establishing a SAM session with STYLE=DATAGRAM, the client can
301send datagrams through SAM's UDP port (7655).
302
303The first line of a datagram sent through this port has to be in the
304following format :
305
3063.0 {$nickname} {$base64_public_destination_key}
307
308 * 3.0 is the version of SAM
309 * {$nickname} is the id of the DGRAM session that will be used
310 * {$base64_public_destination_key} is the destination of the
311    datagram
312 * this line is '\n' terminated.
313
314The first line will be discarded by SAM before sending the remaining
315of the message to the specified destination.
316
317----------------------------------------------------------------------
318SAM repliable datagrams : receiving a datagram
319----------------------------------------------------------------------
320Received datagrams are written by SAM on the socket from which the
321datagram session was opened, unless specified otherwise by the CREATE
322command.
323
324When a datagram arrives, the bridge delivers it to the client via the
325message :
326
327<-  DATAGRAM RECEIVED
328           DESTINATION=$base64key
329           SIZE=$numBytes\n[$numBytes of data]
330
331The SAM bridge never exposes to the client the authentication headers
332or other fields, merely the data that the sender provided.  This
333continues until the session is closed (by the client dropping the
334connection).
335
336----------------------------------------------------------------------
337SAM repliable datagrams : forwarding datagrams
338----------------------------------------------------------------------
339When creating a datagram session, the client can ask SAM to forward
340incoming messages to a specified ip:port. It does so by issuing the
341CREATE command with PORT and HOST options :
342
343-> SESSION CREATE
344          STYLE=DATAGRAM
345          ID={$nickname}
346          DESTINATION={$private_destination_key,TRANSIENT}
347          PORT={$port}
348          [HOST={$host}]
349          [option=value]*
350
351 * {$host} is the hostname or IP address of the datagram server to
352     which SAM will forward datagrams. If not given, SAM takes the
353     IP of the socket that issued the forward command.
354
355 * {$port} is the port number of the datagram server to which SAM
356     will forward datagrams.
357
358When a datagram arrives, the bridge sends to the specified host:port
359a message containing the following data :
360
361${sender_base64_destination_key}\n{$datagram_payload}
362
363
364----------------------------------------------------------------------
365SAM anonymous datagrams
366----------------------------------------------------------------------
367Squeezing the most out of I2P's bandwidth, SAM allows clients to send
368and receive anonymous datagrams, leaving authentication and reply
369information up to the client themselves.  These datagrams are
370unreliable and unordered, and may be up to 32KB in size.
371
372After establishing a SAM session with STYLE=RAW, the client can
373send anonymous datagrams throug the SAM bridge exactly the same way
374he sends non anonymous datagrams.
375
376Both ways of receiving datagrams are also available for anonymous
377datagrams.
378
379When anonymous datagrams are to be written to the socket that created
380the session,the bridge delivers it to the client via:
381
382<- RAW RECEIVED
383      SIZE=$numBytes\n[$numBytes of data]
384
385When anonymous datagrams are to be forwarded to some host:port,
386the bridge sends to the specified host:port a message containing
387the following data :
388
389{$datagram_payload}
390
391
392----------------------------------------------------------------------
393SAM utility functionality
394----------------------------------------------------------------------
395The following message can be used by the client to query the SAM
396bridge for name resolution:
397
398 NAMING LOOKUP
399        NAME=$name
400
401which is answered by
402
403 NAMING REPLY
404        RESULT=$result
405        NAME=$name
406        [VALUE=$base64key]
407        [MESSAGE=$message]
408
409
410The RESULT value may be one of:
411
412    OK
413    INVALID_KEY
414    KEY_NOT_FOUND
415
416If NAME=ME, then the reply will contain the base64key used by the
417current session (useful if you're using a TRANSIENT one).  If $result
418is not OK, MESSAGE may convey a descriptive message, such as "bad
419format", etc.
420
421Public and private base64 keys can be generated using the following
422message:
423
424 DEST GENERATE
425
426which is answered by
427
428 DEST REPLY
429      PUB=$pubkey
430      PRIV=$privkey
431
432----------------------------------------------------------------------
433RESULT values
434----------------------------------------------------------------------
435These are the values that can be carried by the RESULT field, with
436their meaning:
437
438 OK              Operation completed succesfully
439 CANT_REACH_PEER The peer exists, but cannot be reached
440 DUPLICATED_DEST The specified Destination is already in use
441 I2P_ERROR       A generic I2P error (e.g. I2CP disconnection, etc.)
442 INVALID_KEY     The specified key is not valid (bad format, etc.)
443 KEY_NOT_FOUND   The naming system can't resolve the given name
444 PEER_NOT_FOUND  The peer cannot be found on the network
445 TIMEOUT         Timeout while waiting for an event (e.g. peer answer)
446
447----------------------------------------------------------------------
448Tunnel Pool Options
449----------------------------------------------------------------------
450
451These options can be passed in as name=value pairs at the end of a
452SAM SESSION CREATE line.
453
454 inbound.nickname            - Name shows up in I2P router console.
455 inbound.quantity            - Number of tunnels, default 2.
456 inbound.backupQuantity      - Number of backup tunnels, default 0.
457 inbound.rebuildPeriod       - Obsolete - ignored - the router controls rebuilding
458 inbound.duration            - Tunnels last X ms, default 10*60*1000.
459                               (change not recommended, will break anonymmity
460                                if it works at all)
461 inbound.length              - Depth of tunnels, default 2.
462 inbound.lengthVariance      - If negative, randomly skews from
463                               (length - variance) to
464                               (length + variance).  If positive, from
465                               length to (length + var), inclusive.
466                               Default -1.
467 inbound.allowZeroHop        - Zero hop allowed?  Default "true".
468 outbound.*                  - Same properties as inbound.
469 i2p.streaming.connectDelay  - If 0, connect ASAP.  If positive, wait
470                               until X ms have passed or output stream
471                               is flushed or buffer fills.  Default 0.
472 i2p.streaming.maxWindowSize - Max window size, default 64.
473
474----------------------------------------------------------------------
475Client library implementations:
476----------------------------------------------------------------------
477 C/C++:  libSAM: http://www.innographx.com/mpc/libsam/ or i2p/sam/c/
478 Python: Python/I2P: http://dev.i2p.net/contrib/apps/sam/python/index.html
479 Others: See apps/sam/ in I2P CVS.
Note: See TracBrowser for help on using the repository browser.