diff --git a/router/doc/udp.html b/router/doc/udp.html new file mode 100644 index 000000000..1d46daf6b --- /dev/null +++ b/router/doc/udp.html @@ -0,0 +1,496 @@ +$Id$ + +

Secure Semireliable UDP (SSU)

+DRAFT + +

+The goal of this protocol is to provide secure and authenticated +semireliable, undordered message delivery, exposing only a minimal +amount of data easily discernable to third parties. It should +support high degree communication as well as TCP-friendly congestion +control, and may include PMTU detection. It should be capable of +efficiently moving bulk data at rates sufficient for home users. +In addition, it should support techniques for addressing network +obstacles, like most NATs or firewalls.

+ +

Addressing and introduction

+ +

To contact an ESU peer, one of two sets of information is necessary: +a direct address, for when the peer is publicly reachable, or an +indirect address, for using a third party to introduce the peer. +There is no restriction on the number of addresses a peer may have.

+ +
+    Direct: udp://host:port/introKey
+  Indirect: udp://tag@relayhost:port/relayIntroKey/targetIntroKey
+
+ +

These introduction keys are delivered through an external channel +and must be used when establishing a session key. For the indirect +address, the peer must first contact the relayhost and ask them for +an introduction to the peer known at that relayhost under the given +tag. If possible, the relayhost sends a message to the addressed +peer telling them to contact the requesting peer, and also gives +the requesting peer the IP and port on which the addressed peer is +located. In addition, the peer establishing the connection must +already know the public keys of the peer they are connecting to (but +not necessary to any intermediary relay peer).

+ +

Header

+ +

All UDP datagrams begin with a MAC and an IV, followed by a variable +size payload encrypted with the appropriate key. The MAC used is +HMAC-SHA256, truncated to 16 bytes, while the key is a full AES256 +key. The specific construct of the MAC is the first 16 bytes from:

+
+  HMAC-SHA256(payload, HMAC-SHA256(IV || payloadLength, key))
+
+ +

The payload itself is AES256/CBC encrypted with the IV and the key, +with replay prevention addressed within its body, explained below.

+ +

Payload

+ +

Within the AES encrypted payload, there is a minimal common structure +to the various messages - a one byte flag and a four byte sending +timestamp (*seconds* since the unix epoch). The flag byte contains +the following bitfields:

+
+  bits 0-3: payload type
+     bit 4: rekey?
+     bit 5: extended options included
+  bits 6-7: reserved
+
+ +

If the rekey flag is set, 32 bytes of keying material follow the +timestamp. If the extended options flag is set, a one byte option +size value is appended to, followed by that many extended option +bytes, which are currently uninterpreted.

+ +

When rekeying, the keying material is fed into a SHA256 to produce +the new key, though that key is not immediately used. The other +side should also reply with the rekey flag set and that same keying +material. Once both sides have sent and received those values, the +new key should be used and the previous key discarded. It may be +useful to keep the old key around briefly, to address packet loss +and reordering.

+ +
+ Header: 37+ bytes
+ +----+----+----+----+----+----+----+----+
+ |                  MAC                  |
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ |                   IV                  |
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ |flag|        time       | (optionally  |
+ +----+----+----+----+----+              |
+ | this may have 32 byte keying material |
+ | and/or a one+N byte extended options) |
+ +---------------------------------------|
+
+ +

Messages

+ +

SessionRequest (type 0)

+ + + + + + + +
Peer:Alice to Bob
Data:
    +
  • 256 byte X, to begin the DH agreement
    • +
  • 1 byte IP address size
    • +
  • that many byte representation of Bob's IP address
    • +
  • N bytes, currently uninterpreted (later, for challenges)
    • +
Key used:introKey
+ +
+ +----+----+----+----+----+----+----+----+
+ |         X, as calculated from DH      |
+ |                                       |
+                 .   .   .               
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ |size| that many byte IP address (4-16) |
+ +----+----+----+----+----+----+----+----+
+ |           arbitrary amount            |
+ |        of uninterpreted data          |
+                 .   .   .               
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+
+ +

SessionCreated (type 1)

+ + + + + + + +
Peer:Bob to Alice
Data:
    +
  • 256 byte Y, to complete the DH agreement
    • +
  • 1 byte IP address size
    • +
  • that many byte representation of Alice's IP address
    • +
  • 2 byte port number (unsigned, big endian 2s complement)
    • +
  • 0-15 pad bytes to reach the 16 byte boundary
    • +
  • 4 byte relay tag which Alice can publish (else 0x0)
    • +
  • 40 byte DSA signature of the critical exchanged data
    • +
  • N bytes, currently uninterpreted (later, for challenges)
    • +
Key used:introKey for the data through the pad bytes, and the + sessionKey for the DSA signature
+ +
+ +----+----+----+----+----+----+----+----+
+ |         Y, as calculated from DH      |
+ |                                       |
+                 .   .   .               
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ |size| that many byte IP address (4-16) |
+ +----+----+----+----+----+----+----+----+
+ | Port (A)| (pad to 16 byte boundary)   |
+ +----+----+----+----+----+----+----+----+
+ |  public relay tag | DSA signature     |
+ +----+----+----+----+                   |
+ |                                       |
+ |                                       |
+ |                                       |
+ |                                       |
+ +                   +----+----+----+----+
+ |                   | arbitrary amount  |
+ +----+----+----+----+                   |
+ |     of uninterpreted data             |
+ +----+----+----+----+----+----+----+----+
+
+ +

SessionConfirmed (type 2)

+ + + + + + + +
Peer:Bob to Alice
Data:
    +
  • 1 byte identity fragment info:
    +bits 0-3: current identity fragment #
+bits 4-7: total identity fragments
    • +
  • N byte fragment of Alice's identity, sent over a number + of messages.
    • +
  • on the last identity fragment, the last 40 bytes contain + the DSA signature of the critical exchanged data
    • +
Key used:sessionKey
+ +
+ Fragment 1 through N-1
+ +----+----+----+----+----+----+----+----+
+ |info| fragment of Alice's full         |
+ +----+                                  |
+ |            identity keys              |
+                 .   .   .               
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ 
+ Fragment N:
+ +----+----+----+----+----+----+----+----+
+ |info| fragment of Alice's full         |
+ +----+                                  |
+ |            identity keys              |
+                 .   .   .               
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ |  arbitrary amount of uninterpreted    |
+ |        data, up from the end of the   |
+ |  identity key to 40 bytes prior to    |
+ |       end of the current packet       |
+ +----+----+----+----+----+----+----+----+
+ | DSA signature                         |
+ |                                       |
+ |                                       |
+ |                                       |
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+
+ +

RelayRequest (type 3)

+ + + + + + + +
Peer:Alice to Bob
Data:
    +
  • 4 byte relay tag
    • +
  • 1 byte IP address size
    • +
  • that many byte representation of Bob's IP address
    • +
  • 1 byte IP address size
    • +
  • that many byte representation of Alice's IP address
    • +
  • 2 byte port number (of Alice)
    • +
  • 1 byte challenge size
    • +
  • that many bytes to be relayed to Charlie in the intro
    • +
  • N bytes, currently uninterpreted
    • +
Key used:introKey (or sessionKey, if Alice/Bob is established)
+ +
+ +----+----+----+----+----+----+----+----+
+ |      relay tag    |size| that many    |
+ +----+----+----+----+----+         +----|
+ | bytes making up Bob's IP address |size|
+ +----+----+----+----+----+----+----+----+
+ | that many bytes making up Alice's IP  |
+ +----+----+----+----+----+----+----+----+
+ | Port (A)|size| that many challenge    |
+ +----+----+----+                        |
+ | bytes to be delivered to Charlie      |
+ +----+----+----+----+----+----+----+----+
+ | arbitrary amount of uninterpreted data|
+ +----+----+----+----+----+----+----+----+
+
+ +

RelayResponse (type 4)

+ + + + + + + +
Peer:Bob to Alice
Data:
    +
  • 1 byte IP address size
    • +
  • that many byte representation of Charlie's IP address
    • +
  • 2 byte port number
    • +
  • 1 byte IP address size
    • +
  • that many byte representation of Alice's IP address
    • +
  • 2 byte port number
    • +
  • N bytes, currently uninterpreted
    • +
Key used:introKey (or sessionKey, if Alice/Bob is established)
+ +
+ +----+----+----+----+----+----+----+----+
+ |size| that many bytes making up        |
+ +----+                        +----+----+
+ | Charlie's IP address        | Port (C)|
+ +----+----+----+----+----+----+----+----+
+ |size| that many bytes making up        |
+ +----+                        +----+----+
+ | Alice's IP address          | Port (A)|
+ +----+----+----+----+----+----+----+----+
+ | arbitrary amount of uninterpreted data|
+ +----+----+----+----+----+----+----+----+
+
+ +

RelayIntro (type 5)

+ + + + + + + +
Peer:Bob to Charlie
Data:
    +
  • 1 byte IP address size
    • +
  • that many byte representation of Alice's IP address
    • +
  • 2 byte port number (of Alice)
    • +
  • 1 byte challenge size
    • +
  • that many bytes relayed from Alice
    • +
  • N bytes, currently uninterpreted
    • +
Key used:sessionKey
+ +
+ +----+----+----+----+----+----+----+----+
+ |size| that many bytes making up        |
+ +----+                        +----+----+
+ | Charlie's IP address        | Port (C)|
+ +----+----+----+----+----+----+----+----+
+ |size| that many bytes of challenge     |
+ +----+                                  |
+ | data relayed from Alice               |
+ +----+----+----+----+----+----+----+----+
+ | arbitrary amount of uninterpreted data|
+ +----+----+----+----+----+----+----+----+
+
+ +

Data (type 6)

+ + + + + + + +
Peer:Any
Data:
    +
  • 1 byte flags:
    +   bit 0: explicit ACKs included
+   bit 1: explicit NACKs included
+   bit 2: numACKs included
+bits 3-4: reserved for congestion control
+   bit 5: want reply
+bits 6-7: reserved
    • +
  • if explicit ACKs are included:
      +
    • a 1 byte number of ACKs
      • +
    • that many 4 byte MessageIds being fully ACKed
      • +
    • +
  • if explicit NACKs are included:
      +
    • a 1 byte number of NACKs
      • +
    • that many 4 byte MessageIds + 1 byte fragmentNum NACKs
      • +
    • +
  • if numACKs included:
      +
    • a 1 byte number for how many messages were fully + received in the last minute.
    • +
  • 1 byte number of fragments
    • +
  • that many message fragments:
      +
    • 4 byte messageId
      • +
    • 1 byte fragment info:
      +bits 0-4: fragment #
+   bit 5: isLast (1 = true)
+bits 6-7: unused
      • +
    • 2 byte fragment size
      • +
    • that many bytes
      • +
    • 1 byte fragment size
    +
  • N bytes padding, uninterpreted
    • +
Key used:sessionKey
+ +
+ +----+----+----+----+----+----+----+----+
+ |flag| (additional headers, determined  |
+ +----+                                  |
+ | by the flags, such as ACKs, NACKs, or |
+ | simple rate of full ACKs)             |
+ +----+----+----+----+----+----+----+----+
+ |#frg|     messageId     |info|fragSize |
+ +----+----+----+----+----+----+----+----+
+ | that many bytes of fragment data      |
+                  .  .  .                                       
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ |     messageId     |info|fragSize |    |
+ +----+----+----+----+----+----+----+    |
+ | that many bytes of fragment data      |
+                  .  .  .                                       
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ |     messageId     |info|fragSize |    |
+ +----+----+----+----+----+----+----+    |
+ | that many bytes of fragment data      |
+                  .  .  .                                       
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ | arbitrary amount of uninterpreted data|
+ +----+----+----+----+----+----+----+----+
+
+ +

Keys

+ +

All encryption used is AES256/CBC with 16 byte keys and 16 byte IVs. +When using the introKey, both the initial message and any subsequent +reply use the introKey of the responder (Bob) - the responder does +not need to know the introKey of the requestor (Alice). The DSA +signing key used by Bob should already be known to Alice when she +contacts him, though Alice's DSA key may not already be known by +Bob.

+ +

Upon receiving a message, the receiver checks the from IP address +with any established sessions - if there is one or more matches, +those session keys are tested sequentially in the HMAC. If none +of those verify or if there are no matching IP addresses, the +receiver tries their introKey in the MAC. If that does not verify, +the packet is dropped. If it does verify, it is interpreted +according to the message type, though if the receiver is overloaded, +it may be dropped anyway.

+ +

If Alice and Bob have an established session, but Alice loses the +key for some reason and she wants to contact Bob, she may at any +time simply establish a new session through the SessionRequest and +related messages. If Bob has lost the key but Alice does not know +that, she will first attempt to prod him to reply, by sending a +DataMessage with the wantReply flag set, and if Bob continually +fails to reply, she will assume the key is lost and reestablish a +new one.

+ +

For the DH key agreement, +RFC3526 2048bit +MODP group (#14) is used:

+
+  p = 2^2048 - 2^1984 - 1 + 2^64 * { [2^1918 pi] + 124476 }
+  g = 2
+
+ +

The DSA p, q, and g are shared according to the scope of the +identity which created them.

+ +

Message sequences

+ +

Connection establishment (direct)

+ +
+        Alice                         Bob
+    SessionRequest--------------------->
+          <---------------------SessionCreated
+    SessionConfirmed------------------->
+    SessionConfirmed------------------->
+    SessionConfirmed------------------->
+    SessionConfirmed------------------->
+          <--------------------------Data
+
+ +

Connection establishment (indirect)

+ +
+        Alice                         Bob                  Charlie
+    RelayRequest ---------------------->
+         <--------------RelayResponse    RelayIntro----------->
+         <--------------------------------------------Data (ignored)
+    SessionRequest-------------------------------------------->
+         <--------------------------------------------SessionCreated
+    SessionConfirmed------------------------------------------>
+    SessionConfirmed------------------------------------------>
+    SessionConfirmed------------------------------------------>
+    SessionConfirmed------------------------------------------>
+         <---------------------------------------------------Data
+
+ +

Sample datagrams

+ +Minimal data message (no fragments, no ACKs, no NACKs, etc)
+(Size: 39 bytes) + +
+ +----+----+----+----+----+----+----+----+
+ |                  MAC                  |
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ |                   IV                  |
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ |flag|        time       |flag|#frg|    |
+ +----+----+----+----+----+----+----+    |
+ |  padding to fit a full AES256 block   |
+ +----+----+----+----+----+----+----+----+
+
+ +Minimal data message with payload
+(Size: 46+fragmentSize bytes) + +
+ +----+----+----+----+----+----+----+----+
+ |                  MAC                  |
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ |                   IV                  |
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+ |flag|        time       |flag|#frg| 
+ +----+----+----+----+----+----+----+----+
+   messageId    |info| fragSize|         |
+ +----+----+----+----+----+----+         |
+ | that many bytes of fragment data      |
+                  .  .  .                                       
+ |                                       |
+ +----+----+----+----+----+----+----+----+
+