source: router/doc/udp.html @ 4ce6b30

i2p_0_6_0_1
Last change on this file since 4ce6b30 was 4ce6b30, checked in by zzz <zzz@…>, 16 years ago
  • 2005-08-03 0.6.0.1 released

2005-08-03 jrandom

  • Backed out an inadvertant change to the netDb store redundancy factor.
  • Verify tunnel participant caching.
  • Logging cleanup
  • Property mode set to 100644
File size: 29.8 KB
Line 
1<code>$Id: udp.html,v 1.14 2005/07/27 14:04:07 jrandom Exp $</code>
2
3<h1>Secure Semireliable UDP (SSU)</h1>
4<b>DRAFT</b>
5
6<p>
7The goal of this protocol is to provide secure, authenticated,
8semireliable, and unordered message delivery, exposing only a minimal
9amount of data easily discernible to third parties.  It should
10support high degree communication as well as TCP-friendly congestion
11control, and may include PMTU detection.   It should be capable of
12efficiently moving bulk data at rates sufficient for home users.
13In addition, it should support techniques for addressing network
14obstacles, like most NATs or firewalls.</p>
15
16<h2><a name="addressing">Addressing and introduction</a></h2>
17
18<p>To contact an SSU peer, one of two sets of information is necessary:
19a direct address, for when the peer is publicly reachable, or an
20indirect address, for using a third party to introduce the peer. 
21There is no restriction on the number of addresses a peer may have.</p>
22
23<pre>
24    Direct: ssu://host:port/introKey[?opts=[A-Z]*]
25  Indirect: ssu://tag@relayhost:port/relayIntroKey/targetIntroKey[?opts=[A-Z]*]
26</pre>
27
28<p>These introduction keys are delivered through an external channel
29and must be used when establishing a session key.  For the indirect
30address, the peer must first contact the relayhost and ask them for
31an introduction to the peer known at that relayhost under the given
32tag.  If possible, the relayhost sends a message to the addressed
33peer telling them to contact the requesting peer, and also gives
34the requesting peer the IP and port on which the addressed peer is
35located.  In addition, the peer establishing the connection must
36already know the public keys of the peer they are connecting to (but
37not necessary to any intermediary relay peer).</p>
38
39<p>Each of the addresses may also expose a series of options - special
40capabilities of that particular peer.  For a list of available
41capabilities, see <a href="#capabilities">below</a>.</p>
42
43<h2><a name="header">Header</a></h2>
44
45<p>All UDP datagrams begin with a MAC and an IV, followed by a variable
46size payload encrypted with the appropriate key.  The MAC used is
47HMAC-SHA256, truncated to 16 bytes, while the key is a full AES256
48key.  The specific construct of the MAC is the first 16 bytes from:</p>
49<pre>
50  HMAC-SHA256(payload || IV || payloadLength, macKey)
51</pre>
52
53<p>The payload itself is AES256/CBC encrypted with the IV and the
54sessionKey, with replay prevention addressed within its body,
55explained below.  The payloadLength in the MAC is a 2 byte unsigned
56integer in 2s complement.</p>
57
58<h2><a name="payload">Payload</a></h2>
59
60<p>Within the AES encrypted payload, there is a minimal common structure
61to the various messages - a one byte flag and a four byte sending
62timestamp (*seconds* since the unix epoch).  The flag byte contains
63the following bitfields:</p>
64<pre>
65  bits 0-3: payload type
66     bit 4: rekey?
67     bit 5: extended options included
68  bits 6-7: reserved
69</pre>
70
71<p>If the rekey flag is set, 64 bytes of keying material follow the
72timestamp.  If the extended options flag is set, a one byte option
73size value is appended to, followed by that many extended option
74bytes, which are currently uninterpreted.</p>
75
76<p>When rekeying, the first 32 bytes of the keying material is fed
77into a SHA256 to produce the new MAC key, and the next 32 bytes are
78fed into a SHA256 to produce the new session key, though the keys are
79not immediately used.  The other side should also reply with the
80rekey flag set and that same keying material.  Once both sides have
81sent and received those values, the new keys should be used and the
82previous keys discarded.  It may be useful to keep the old keys
83around briefly, to address packet loss and reordering.</p>
84
85<pre>
86 Header: 37+ bytes
87 +----+----+----+----+----+----+----+----+
88 |                  MAC                  |
89 |                                       |
90 +----+----+----+----+----+----+----+----+
91 |                   IV                  |
92 |                                       |
93 +----+----+----+----+----+----+----+----+
94 |flag|        time       | (optionally  |
95 +----+----+----+----+----+              |
96 | this may have 64 byte keying material |
97 | and/or a one+N byte extended options) |
98 +---------------------------------------|
99</pre>
100
101<h2><a name="messages">Messages</a></h2>
102
103<h3><a name="sessionRequest">SessionRequest (type 0)</a></h3>
104<table border="1">
105<tr><td align="right" valign="top"><b>Peer:</b></td>
106    <td>Alice to Bob</td></tr>
107<tr><td align="right" valign="top"><b>Data:</b></td>
108    <td><ul>
109        <li>256 byte X, to begin the DH agreement</li>
110        <li>1 byte IP address size</li>
111        <li>that many byte representation of Bob's IP address</li>
112        <li>N bytes, currently uninterpreted (later, for challenges)</li>
113        </ul></td></tr>
114<tr><td align="right" valign="top"><b>Key used:</b></td>
115    <td>introKey</td></tr>
116</table>
117
118<pre>
119 +----+----+----+----+----+----+----+----+
120 |         X, as calculated from DH      |
121 |                                       |
122                 .   .   .               
123 |                                       |
124 +----+----+----+----+----+----+----+----+
125 |size| that many byte IP address (4-16) |
126 +----+----+----+----+----+----+----+----+
127 |           arbitrary amount            |
128 |        of uninterpreted data          |
129                 .   .   .               
130 |                                       |
131 +----+----+----+----+----+----+----+----+
132</pre>
133
134<h3><a name="sessionCreated">SessionCreated (type 1)</a></h3>
135<table border="1">
136<tr><td align="right" valign="top"><b>Peer:</b></td>
137    <td>Bob to Alice</td></tr>
138<tr><td align="right" valign="top"><b>Data:</b></td>
139    <td><ul>
140        <li>256 byte Y, to complete the DH agreement</li>
141        <li>1 byte IP address size</li>
142        <li>that many byte representation of Alice's IP address</li>
143        <li>2 byte port number (unsigned, big endian 2s complement)</li>
144        <li>4 byte relay tag which Alice can publish (else 0x0)</li>
145        <li>4 byte timestamp (seconds from the epoch) for use in the DSA
146            signature</li>
147        <li>40 byte DSA signature of the critical exchanged data
148            (X + Y + Alice's IP + Alice's port + Bob's IP + Bob's port + Alice's
149            new relay tag + Bob's signed on time), encrypted with another
150            layer of encryption using the negotiated sessionKey.  The IV
151            is reused here.</li>
152        <li>8 bytes padding, encrypted with an additional layer of encryption
153            using the negotiated session key as part of the DSA block</li>
154        <li>N bytes, currently uninterpreted (later, for challenges)</li>
155        </ul></td></tr>
156<tr><td align="right" valign="top"><b>Key used:</b></td>
157    <td>introKey, with an additional layer of encryption over the 40 byte
158        signature and the following 8 bytes padding.</td></tr>
159</table>
160
161<pre>
162 +----+----+----+----+----+----+----+----+
163 |         Y, as calculated from DH      |
164 |                                       |
165                 .   .   .               
166 |                                       |
167 +----+----+----+----+----+----+----+----+
168 |size| that many byte IP address (4-16) |
169 +----+----+----+----+----+----+----+----+
170 | Port (A)| public relay tag  |  signed
171 +----+----+----+----+----+----+----+----+
172   on time |                             |
173 +----+----+                             |
174 |              DSA signature            |
175 |                                       |
176 |                                       |
177 |                                       |
178 |         +----+----+----+----+----+----+
179 |         |     (8 bytes of padding)
180 +----+----+----+----+----+----+----+----+
181           |                             |
182 +----+----+                             |
183 |           arbitrary amount            |
184 |        of uninterpreted data          |
185                 .   .   .               
186 |                                       |
187 +----+----+----+----+----+----+----+----+
188</pre>
189
190<h3><a name="sessionConfirmed">SessionConfirmed (type 2)</a></h3>
191<table border="1">
192<tr><td align="right" valign="top"><b>Peer:</b></td>
193    <td>Alice to Bob</td></tr>
194<tr><td align="right" valign="top"><b>Data:</b></td>
195    <td><ul>
196        <li>1 byte identity fragment info:<pre>
197bits 0-3: current identity fragment #
198bits 4-7: total identity fragments</pre></li>
199        <li>2 byte size of the current identity fragment</li>
200        <li>that many byte fragment of Alice's identity.</li>
201        <li>on the last identity fragment, the signed on time is
202            included after the identity fragment, and the last 40
203            bytes contain the DSA signature of the critical exchanged
204            data (X + Y + Alice's IP + Alice's port + Bob's IP + Bob's port
205            + Alice's new relay key + Alice's signed on time)</li>
206        </ul></td></tr>
207<tr><td align="right" valign="top"><b>Key used:</b></td>
208    <td>sessionKey</td></tr>
209</table>
210
211<pre>
212 <b>Fragment 1 through N-1</b>
213 +----+----+----+----+----+----+----+----+
214 |info| cursize |                        |
215 +----+----+----+                        |
216 |      fragment of Alice's full         |
217 |            identity keys              |
218                 .   .   .               
219 |                                       |
220 +----+----+----+----+----+----+----+----+
221 
222 <b>Fragment N:</b>
223 +----+----+----+----+----+----+----+----+
224 |info| cursize |                        |
225 +----+----+----+                        |
226 |      fragment of Alice's full         |
227 |            identity keys              |
228                 .   .   .               
229 |                                       |
230 +----+----+----+----+----+----+----+----+
231 |  signed on time   |                   |
232 +----+----+----+----+                   |
233 |  arbitrary amount of uninterpreted    |
234 |        data, up from the end of the   |
235 |  identity key to 40 bytes prior to    |
236 |       end of the current packet       |
237 +----+----+----+----+----+----+----+----+
238 | DSA signature                         |
239 |                                       |
240 |                                       |
241 |                                       |
242 |                                       |
243 +----+----+----+----+----+----+----+----+
244</pre>
245 
246<h3><a name="relayRequest">RelayRequest (type 3)</a></h3>
247<table border="1">
248<tr><td align="right" valign="top"><b>Peer:</b></td>
249    <td>Alice to Bob</td></tr>
250<tr><td align="right" valign="top"><b>Data:</b></td>
251    <td><ul>
252        <li>4 byte relay tag</li>
253        <li>1 byte IP address size</li>
254        <li>that many byte representation of Bob's IP address</li>
255        <li>1 byte IP address size</li>
256        <li>that many byte representation of Alice's IP address</li>
257        <li>2 byte port number (of Alice)</li>
258        <li>1 byte challenge size</li>
259        <li>that many bytes to be relayed to Charlie in the intro</li>
260        <li>N bytes, currently uninterpreted</li>
261        </ul></td></tr>
262<tr><td align="right" valign="top"><b>Key used:</b></td>
263    <td>introKey (or sessionKey, if Alice/Bob is established)</td></tr>
264</table>
265 
266<pre>
267 +----+----+----+----+----+----+----+----+
268 |      relay tag    |size| that many    |
269 +----+----+----+----+----+         +----|
270 | bytes making up Bob's IP address |size|
271 +----+----+----+----+----+----+----+----+
272 | that many bytes making up Alice's IP  |
273 +----+----+----+----+----+----+----+----+
274 | Port (A)|size| that many challenge    |
275 +----+----+----+                        |
276 | bytes to be delivered to Charlie      |
277 +----+----+----+----+----+----+----+----+
278 | arbitrary amount of uninterpreted data|
279 +----+----+----+----+----+----+----+----+
280</pre>
281
282<h3><a name="relayResponse">RelayResponse (type 4)</a></h3>
283<table border="1">
284<tr><td align="right" valign="top"><b>Peer:</b></td>
285    <td>Bob to Alice</td></tr>
286<tr><td align="right" valign="top"><b>Data:</b></td>
287    <td><ul>
288        <li>1 byte IP address size</li>
289        <li>that many byte representation of Charlie's IP address</li>
290        <li>2 byte port number</li>
291        <li>1 byte IP address size</li>
292        <li>that many byte representation of Alice's IP address</li>
293        <li>2 byte port number</li>
294        <li>N bytes, currently uninterpreted</li>
295        </ul></td></tr>
296<tr><td align="right" valign="top"><b>Key used:</b></td>
297    <td>introKey (or sessionKey, if Alice/Bob is established)</td></tr>
298</table>
299
300<pre>
301 +----+----+----+----+----+----+----+----+
302 |size| that many bytes making up        |
303 +----+                        +----+----+
304 | Charlie's IP address        | Port (C)|
305 +----+----+----+----+----+----+----+----+
306 |size| that many bytes making up        |
307 +----+                        +----+----+
308 | Alice's IP address          | Port (A)|
309 +----+----+----+----+----+----+----+----+
310 | arbitrary amount of uninterpreted data|
311 +----+----+----+----+----+----+----+----+
312</pre>
313
314<h3><a name="relayIntro">RelayIntro (type 5)</a></h3>
315<table border="1">
316<tr><td align="right" valign="top"><b>Peer:</b></td>
317    <td>Bob to Charlie</td></tr>
318<tr><td align="right" valign="top"><b>Data:</b></td>
319    <td><ul>
320        <li>1 byte IP address size</li>
321        <li>that many byte representation of Alice's IP address</li>
322        <li>2 byte port number (of Alice)</li>
323        <li>1 byte challenge size</li>
324        <li>that many bytes relayed from Alice</li>
325        <li>N bytes, currently uninterpreted</li>
326        </ul></td></tr>
327<tr><td align="right" valign="top"><b>Key used:</b></td>
328    <td>sessionKey</td></tr>
329</table>
330
331<pre>
332 +----+----+----+----+----+----+----+----+
333 |size| that many bytes making up        |
334 +----+                        +----+----+
335 | Charlie's IP address        | Port (C)|
336 +----+----+----+----+----+----+----+----+
337 |size| that many bytes of challenge     |
338 +----+                                  |
339 | data relayed from Alice               |
340 +----+----+----+----+----+----+----+----+
341 | arbitrary amount of uninterpreted data|
342 +----+----+----+----+----+----+----+----+
343</pre>
344
345<h3><a name="data">Data (type 6)</a></h3>
346<table border="1">
347<tr><td align="right" valign="top"><b>Peer:</b></td>
348    <td>Any</td></tr>
349<tr><td align="right" valign="top"><b>Data:</b></td>
350    <td><ul>
351        <li>1 byte flags:<pre>
352   bit 0: explicit ACKs included
353   bit 1: ACK bitfields included
354   bit 2: reserved
355   bit 3: explicit congestion notification
356   bit 4: request previous ACKs
357   bit 5: want reply
358   bit 6: extended data included
359   bit 7: reserved</pre></li>
360        <li>if explicit ACKs are included:<ul>
361          <li>a 1 byte number of ACKs</li>
362          <li>that many 4 byte MessageIds being fully ACKed</li>
363          </ul></li>
364        <li>if ACK bitfields are included:<ul>
365          <li>a 1 byte number of ACK bitfields</li>
366          <li>that many 4 byte MessageIds + a 1 or more byte ACK bitfield.
367              The bitfield uses the 7 low bits of each byte, with the high
368              bit specifying whether an additional bitfield byte follows it
369              (1 = true, 0 = the current bitfield byte is the last).  These
370              sequence of 7 bit arrays represent whether a fragment has been
371              received - if a bit is 1, the fragment has been received.  To
372              clarify, assuming fragments 0, 2, 5, and 9 have been received,
373              the bitfield bytes would be as follows:<pre>
374byte 0
375   bit 0: 1 (further bitfield bytes follow)
376   bit 1: 1 (fragment 0 received)
377   bit 2: 0 (fragment 1 not received)
378   bit 3: 1 (fragment 2 received)
379   bit 4: 0 (fragment 3 not received)
380   bit 5: 0 (fragment 4 not received)
381   bit 6: 1 (fragment 5 received)
382   bit 7: 0 (fragment 6 not received)
383byte 1
384   bit 0: 0 (no further bitfield bytes)
385   bit 1: 0 (fragment 7 not received)
386   bit 1: 0 (fragment 8 not received)
387   bit 1: 1 (fragment 9 received)
388   bit 1: 0 (fragment 10 not received)
389   bit 1: 0 (fragment 11 not received)
390   bit 1: 0 (fragment 12 not received)
391   bit 1: 0 (fragment 13 not received)</pre></li>
392          </ul></li>
393        <li>If extended data included:<ul>
394          <li>1 byte data size</li>
395          <li>that many bytes of extended data (currently uninterpreted)</li</ul></li>
396        <li>1 byte number of fragments</li>
397        <li>that many message fragments:<ul>
398          <li>4 byte messageId</li>
399          <li>3 byte fragment info:<pre>
400  bits 0-6: fragment #
401     bit 7: isLast (1 = true)
402  bits 8-9: unused
403bits 10-23: fragment size</pre></li>
404          <li>that many bytes</li></ul>
405        <li>N bytes padding, uninterpreted</li>
406        </ul></td></tr>
407<tr><td align="right" valign="top"><b>Key used:</b></td>
408    <td>sessionKey</td></tr>
409</table>
410
411<pre>
412 +----+----+----+----+----+----+----+----+
413 |flag| (additional headers, determined  |
414 +----+                                  |
415 | by the flags, such as ACKs or         |
416 | bitfields                             |
417 +----+----+----+----+----+----+----+----+
418 |#frg|     messageId     |   frag info  |
419 +----+----+----+----+----+----+----+----+
420 | that many bytes of fragment data      |
421                  .  .  .                                       
422 |                                       |
423 +----+----+----+----+----+----+----+----+
424 |     messageId     |   frag info  |    |
425 +----+----+----+----+----+----+----+    |
426 | that many bytes of fragment data      |
427                  .  .  .                                       
428 |                                       |
429 +----+----+----+----+----+----+----+----+
430 |     messageId     |   frag info  |    |
431 +----+----+----+----+----+----+----+    |
432 | that many bytes of fragment data      |
433                  .  .  .                                       
434 |                                       |
435 +----+----+----+----+----+----+----+----+
436 | arbitrary amount of uninterpreted data|
437 +----+----+----+----+----+----+----+----+
438</pre>
439
440<h3><a name="peerTest">PeerTest (type 7)</a></h3>
441<table border="1">
442<tr><td align="right" valign="top"><b>Peer:</b></td>
443    <td><a href="#peerTesting">Any</a></td></tr>
444<tr><td align="right" valign="top"><b>Data:</b></td>
445    <td><ul>
446        <li>4 byte nonce</li>
447        <li>1 byte IP address size</li>
448        <li>that many byte representation of Alice's IP address</li>
449        <li>2 byte port number</li>
450        <li>Alice's introduction key</li>
451        <li>N bytes, currently uninterpreted</li>
452        </ul></td></tr>
453<tr><td align="right" valign="top"><b>Key used:</b></td>
454    <td>introKey (or sessionKey if the connection has already been established)</td></tr>
455</table>
456
457<pre>
458 +----+----+----+----+----+----+----+----+
459 |    test nonce     |size| that many    |
460 +----+----+----+----+----+              |
461 |bytes making up Alice's IP address     |
462 |----+----+----+----+----+----+----+----+
463 | Port (A)| Alice or Charlie's          |
464 +----+----+                             |
465 | introduction key (Alice's is sent to  |
466 | Bob and Charlie, while Charlie's is   |                                      |
467 | sent to Alice)                        |
468 |         +----+----+----+----+----+----+
469 |         | arbitrary amount of         |
470 |----+----+                             |
471 | uninterpreted data                    |
472 +----+----+----+----+----+----+----+----+
473</pre>
474
475<h2><a name="congestioncontrol">Congestion control</a></h2>
476
477<p>SSU's need for only semireliable delivery, TCP-friendly operation,
478and the capacity for high throughput allows a great deal of latitude in
479congestion control.  The congestion control algorithm outlined below is
480meant to be both efficient in bandwidth as well as simple to implement.</p>
481
482<p>Packets are scheduled according to the the router's policy, taking care
483not to exceed the router's outbound capacity or to exceed the measured
484capacity of the remote peer.  The measured capacity should operate along the
485lines of TCP's slow start and congestion avoidance, with additive increases
486to the sending capacity and multiplicative decreases in face of congestion.
487Veering away from TCP, however, routers may give up on some messages after
488a given period or number of retransmissions while continuing to transmit
489other messages.</p>
490 
491<p>The congestion detection techniques vary from TCP as well, since each
492message has its own unique and nonsequential identifier, and each message
493has a limited size - at most, 32KB.  To efficiently transmit this feedback
494to the sender, the receiver periodically includes a list of fully ACKed
495message identifiers and may also include bitfields for partially received
496messages, where each bit represents the reception of a fragment.  If
497duplicate fragments arrive, the message should be ACKed again, or if the
498message has still not been fully received, the bitfield should be
499retransmitted with any new updates.</p>
500
501<p>The simplest possible implementation does not need to pad the packets to
502any particular size, but instead just places a single message fragment into
503a packet and sends it off (careful not to exceed the MTU).  A more efficient
504strategy would be to bundle multiple message fragments into the same packet,
505so long as it doesn't exceed the MTU, but this is not necessary.  Eventually,
506a set of fixed packet sizes may be appropriate to further hide the data
507fragmentation to external adversaries, but the tunnel, garlic, and end to
508end padding should be sufficient for most needs until then.</p>
509
510<h2><a name="keys">Keys</a></h2>
511
512<p>All encryption used is AES256/CBC with 32 byte keys and 16 byte IVs.
513The MAC and session keys are negotiated as part of the DH exchange, used
514for the HMAC and encryption, respectively.  Prior to the DH exchange,
515the publicly knowable introKey is used for the MAC and encryption.</p>
516
517<p>When using the introKey, both the initial message and any subsequent
518reply use the introKey of the responder (Bob) - the responder does
519not need to know the introKey of the requestor (Alice).  The DSA
520signing key used by Bob should already be known to Alice when she
521contacts him, though Alice's DSA key may not already be known by
522Bob.</p>
523
524<p>Upon receiving a message, the receiver checks the from IP address
525with any established sessions - if there is one or more matches,
526those session's MAC keys are tested sequentially in the HMAC.  If none
527of those verify or if there are no matching IP addresses, the
528receiver tries their introKey in the MAC.  If that does not verify,
529the packet is dropped.  If it does verify, it is interpreted
530according to the message type, though if the receiver is overloaded,
531it may be dropped anyway.</p>
532
533<p>If Alice and Bob have an established session, but Alice loses the
534keys for some reason and she wants to contact Bob, she may at any
535time simply establish a new session through the SessionRequest and
536related messages.  If Bob has lost the key but Alice does not know
537that, she will first attempt to prod him to reply, by sending a
538DataMessage with the wantReply flag set, and if Bob continually
539fails to reply, she will assume the key is lost and reestablish a
540new one.</p>
541
542<p>For the DH key agreement,
543<a href="http://www.faqs.org/rfcs/rfc3526.html">RFC3526</a> 2048bit
544MODP group (#14) is used:</p>
545<pre>
546  p = 2^2048 - 2^1984 - 1 + 2^64 * { [2^1918 pi] + 124476 }
547  g = 2
548</pre>
549
550<p>The DSA p, q, and g are shared according to the scope of the
551identity which created them.</p>
552
553<h2><a name="replay">Replay prevention</a></h2>
554
555<p>Replay prevention at the SSU layer occurs by rejecting packets
556with exceedingly old timestamps or those which reuse an IV.  To
557detect duplicate IVs, a sequence of Bloom filters are employed to
558"decay" periodically so that only recently added IVs are detected.</p>
559
560<p>The messageIds used in DataMessages are defined at layers above
561the SSU transport and are passed through transparently.  These IDs
562are not in any particular order - in fact, they are likely to be
563entirely random.  The SSU layer makes no attempt at messageId
564replay prevention - higher layers should take that into account.</p>
565
566<h2><a name="peerTesting">Peer testing</a></h2>
567
568<p>The automation of collaborative reachability testing for peers is
569enabled by a sequence of PeerTest messages.  With its proper
570execution, a peer will be able to determine their own reachability
571and may update its behavior accordingly.  The testing process is
572quite simple:</p>
573
574<pre>
575        Alice                  Bob                  Charlie
576    PeerTest ------------------&gt;
577         &lt;-------------PeerTest  PeerTest-------------&gt;
578         &lt;------------------------------------------PeerTest
579    PeerTest------------------------------------------&gt;
580         &lt;------------------------------------------PeerTest
581</pre>
582
583<p>Each of the PeerTest messages carry a nonce identifying the
584test series itself, as initialized by Alice.  If Alice doesn't
585get a particular message that she expects, she will retransmit
586accordingly, and based upon the data received or the messages
587missing, she will know her reachability.  The various end states
588that may be reached are as follows:</p>
589
590<ul>
591<li>If she doesn't receive a response from Bob, she will retransmit
592up to a certain number of times, but if no response ever arrives,
593she will know that her firewall or NAT is somehow misconfigured,
594rejecting all inbound UDP packets even in direct response to an
595outbound packet.  Alternately, Bob may be down.</li>
596
597<li>If Alice doesn't receive a PeerTest message with the
598expected nonce from a third party (Charlie), she will retransmit
599her initial request to Bob up to a certain number of times, even
600if she has received Bob's reply already.  If Charlie's first message
601still doesn't get through but Bob's does, she knows that she is
602behind a NAT or firewall that is rejecting unsolicited connection
603attempts and that port forwarding is not operating properly (the
604IP and port that Bob offered up should be forwarded).</li>
605
606<li>If Alice receives Bob's PeerTest message and both of Charlie's
607PeerTest messages but the enclosed IP and port numbers in Bob's
608and Charlie's second messages don't match, she knows that she is
609behind a symmetric NAT, rewriting all of her outbound packets with
610different 'from' ports for each peer contacted.  She will need to
611explicitly forward a port and always have that port exposed for
612remote connectivity, ignoring further port discovery.</li>
613
614<li>If Alice receives Charlie's first message but not his second,
615she will retransmit her PeerTest message to Charlie up to a
616certain number of times, but if no response is received she knows
617that Charlie is either confused or no longer online.</li>
618</ul>
619
620<p>Alice should choose Bob arbitrarily from known peers who seem
621to be capable of participating in peer tests.  Bob in turn should
622choose Charlie arbitrarily from peers that he knows who seem to be
623capable of participating in peer tests and who are on a different
624IP from both Bob and Alice.  If the first error condition occurs
625(Alice doesn't get PeerTest messages from Bob), Alice may decide
626to designate a new peer as Bob and try again with a different nonce.</p>
627
628<p>Alice's introduction key is included in all of the PeerTest
629messages so that she doesn't need to already have an established
630session with Bob and so that Charlie can contact her without knowing
631any additional information.  Alice may go on to establish a session
632with either Bob or Charlie, but it is not required.</p>
633
634<h2><a name="messageSequences">Message sequences</a></h2>
635
636<h3><a name="establishDirect">Connection establishment (direct)</a></h3>
637
638<pre>
639        Alice                         Bob
640    SessionRequest---------------------&gt;
641          &lt;---------------------SessionCreated
642    SessionConfirmed-------------------&gt;
643    SessionConfirmed-------------------&gt;
644    SessionConfirmed-------------------&gt;
645    SessionConfirmed-------------------&gt;
646          &lt;--------------------------Data
647</pre>
648
649<h3><a name="establishIndirect">Connection establishment (indirect)</a></h3>
650
651<pre>
652        Alice                         Bob                  Charlie
653    RelayRequest ----------------------&gt;
654         &lt;--------------RelayResponse    RelayIntro-----------&gt;
655         &lt;--------------------------------------------Data (ignored)
656    SessionRequest--------------------------------------------&gt;
657         &lt;--------------------------------------------SessionCreated
658    SessionConfirmed------------------------------------------&gt;
659    SessionConfirmed------------------------------------------&gt;
660    SessionConfirmed------------------------------------------&gt;
661    SessionConfirmed------------------------------------------&gt;
662         &lt;---------------------------------------------------Data
663</pre>
664
665<h2><a name="sampleDatagrams">Sample datagrams</a></h2>
666
667<b>Minimal data message (no fragments, no ACKs, no NACKs, etc)</b><br />
668<i>(Size: 39 bytes)</i>
669
670<pre>
671 +----+----+----+----+----+----+----+----+
672 |                  MAC                  |
673 |                                       |
674 +----+----+----+----+----+----+----+----+
675 |                   IV                  |
676 |                                       |
677 +----+----+----+----+----+----+----+----+
678 |flag|        time       |flag|#frg|    |
679 +----+----+----+----+----+----+----+    |
680 |  padding to fit a full AES256 block   |
681 +----+----+----+----+----+----+----+----+
682</pre>
683
684<b>Minimal data message with payload</b><br />
685<i>(Size: 46+fragmentSize bytes)</i>
686
687<pre>
688 +----+----+----+----+----+----+----+----+
689 |                  MAC                  |
690 |                                       |
691 +----+----+----+----+----+----+----+----+
692 |                   IV                  |
693 |                                       |
694 +----+----+----+----+----+----+----+----+
695 |flag|        time       |flag|#frg|
696 +----+----+----+----+----+----+----+----+
697   messageId    |   frag info  |         |
698 +----+----+----+----+----+----+         |
699 | that many bytes of fragment data      |
700                  .  .  .                                       
701 |                                       |
702 +----+----+----+----+----+----+----+----+
703</pre> 
704
705<h2><a name="capabilities">Peer capabilities</a></h2>
706
707<dl>
708 <dt>A</dt>
709 <dd>If the peer address contains the 'A' capability, that means
710     they are willing and able to participate in peer tests as
711     a 'Bob' or 'Charlie'.</dd>
712 <dt>B</dt>
713 <dd>If the peer address contains the 'B' capability, that means
714     they are willing and able to serve as an introducer - serving
715     as a Bob for an otherwise unreachable Alice.</dd>
716</dl>
Note: See TracBrowser for help on using the repository browser.