From 98b90ec20af1533034adf59e712c5aa0366b8de3 Mon Sep 17 00:00:00 2001 From: str4d Date: Tue, 5 Feb 2013 04:39:24 +0000 Subject: [PATCH] Added translation tags to docs/transport/* --- i2p2www/pages/site/docs/transport/index.html | 148 +++++--- i2p2www/pages/site/docs/transport/ntcp.html | 312 ++++++++------- i2p2www/pages/site/docs/transport/ssu.html | 376 ++++++++++++------- 3 files changed, 505 insertions(+), 331 deletions(-) diff --git a/i2p2www/pages/site/docs/transport/index.html b/i2p2www/pages/site/docs/transport/index.html index 10f0e78c..7ab5ad92 100644 --- a/i2p2www/pages/site/docs/transport/index.html +++ b/i2p2www/pages/site/docs/transport/index.html @@ -1,126 +1,158 @@ {% extends "global/layout.html" %} -{% block title %}Transport Overview{% endblock %} -{% block lastupdated %}July 2010{% endblock %} +{% block title %}{% trans %}Transport Overview{% endtrans %}{% endblock %} +{% block lastupdated %}{% trans %}July 2010{% endtrans %}{% endblock %} {% block accuratefor %}0.8{% endblock %} {% block content %} -

Transports in I2P

+

{% trans %}Transports in I2P{% endtrans %}

+

{% trans -%} A "transport" in I2P is a method for direct, point-to-point communication between two routers. Transports must provide confidentiality and integrity against external adversaries while authenticating that the router contacted is the one who should receive a given message. +{%- endtrans %}

-

I2P supports multiple transports simultaneously. +

{% trans -%} +I2P supports multiple transports simultaneously. There are two transports currently implemented: +{%- endtrans %}

    -
  1. NTCP, a Java New I/O (NIO) TCP transport -
  2. SSU, or Secure Semireliable UDP +
  3. {% trans ntcp=site_url('docs/transport/ntcp') %}NTCP, a Java New I/O (NIO) TCP transport{% endtrans %}
    4. +
  4. {% trans ssu=site_url('docs/transport/ssu') %} SSU, or Secure Semireliable UDP{% endtrans %}
+

{% trans -%} Each provides a "connection" paradigm, with authentication, flow control, acknowledgments and retransmission. +{%- endtrans %}

-

Transport Services

+

{% trans %}Transport Services{% endtrans %}

+

{% trans -%} The transport subsystem in I2P provides the following services: +{%- endtrans %}

-

Transport Addresses

+

{% trans %}Transport Addresses{% endtrans %}

+

{% trans -%} The transport subsystem maintains a set of router addresses, each of which lists a transport method, IP, and port. These addresses constitute the advertised contact points, and are published by the router to the network database. -

-Typical scenarios are: +{%- endtrans %}

+ +

{% trans %}Typical scenarios are:{% endtrans %}

-

Transport Selection

+

{% trans %}Transport Selection{% endtrans %}

-The transport system delivers I2NP messages. The transport selected for any message is +

{% trans i2np=site_url('docs/protocol/i2np') -%} +The transport system delivers I2NP messages. The transport selected for any message is independent of the application-layer protocol (TCP or UDP). -

+{%- endtrans %}

+

{% trans -%} For each outgoing message, the transport system solicits "bids" from each transport. The transport bidding the lowest (best) value wins the bid and receives the message for delivery. A transport may refuse to bid. -

+{%- endtrans %}

+ +

{% trans -%} Whether a transport bids, and with what value, depend on numerous factors: +{%- endtrans %}

-

+

{% trans -%} In general, the bid values are selected so that two routers are only connected by a single transport at any one time. However, this is not a requirement. +{%- endtrans %}

-

New Transports and Future Work

+

{% trans %}New Transports and Future Work{% endtrans %}

+

{% trans -%} Additional transports may be developed, including: +{%- endtrans %}

-

+

{% trans -%} Also, the existing transports will be enhanced to support multiple addresses within a single transport, including IPV6 addresses. Currently, a transport may only advertise a single IPV4 address. +{%- endtrans %}

-

+

{% trans -%} Work continues on adjusting default connection limits for each transport. I2P is designed as a "mesh network", where it is assumed that any router can connect to any other router. This assumption may be broken by routers that have exceeded their connection limits, and by routers that are behind restrictive state firewalls (restricted routes). +{%- endtrans %}

-

+

{% trans -%} The current connection limits are higher for SSU than for NTCP, based on the assumption that the memory requirements for an NTCP connection are higher than that for SSU. However, as NTCP buffers are partially in the kernel and SSU buffers are on the Java heap, that assumption is difficult to verify. +{%- endtrans %}

-

-Analyze -Breaking and Improving Protocol Obfuscation +

{% trans pdf='http://www.cse.chalmers.se/%7Ejohnwolf/publications/hjelmvik_breaking.pdf' -%} +Analyze Breaking and Improving Protocol Obfuscation and see how transport-layer padding may improve things. -

+{%- endtrans %}

{% endblock %} diff --git a/i2p2www/pages/site/docs/transport/ntcp.html b/i2p2www/pages/site/docs/transport/ntcp.html index 509551a3..bb7053e0 100644 --- a/i2p2www/pages/site/docs/transport/ntcp.html +++ b/i2p2www/pages/site/docs/transport/ntcp.html @@ -1,64 +1,65 @@ {% extends "global/layout.html" %} {% block title %}NTCP{% endblock %} -{% block lastupdated %}August 2010{% endblock %} +{% block lastupdated %}{% trans %}August 2010{% endtrans %}{% endblock %} {% block accuratefor %}0.8{% endblock %} {% block content %} -

NTCP (NIO-based TCP)

+

{% trans %}NTCP (NIO-based TCP){% endtrans %}

-

-NTCP -is one of two transports currently implemented in I2P. -The other is SSU. -NTCP -is a Java NIO-based transport -introduced in I2P release 0.6.1.22. +

{% trans transports=site_url('docs/transport'), ssu=site_url('docs/transport/ssu') -%} +NTCP is one of two transports currently implemented in I2P. +The other is SSU. +NTCP is a Java NIO-based transport introduced in I2P release 0.6.1.22. Java NIO (new I/O) does not suffer from the 1 thread per connection issues of the old TCP transport. -

+{%- endtrans %}

-By default, -NTCP uses the IP/Port +

{% trans -%} +By default, NTCP uses the IP/Port auto-detected by SSU. When enabled on config.jsp, SSU will notify/restart NTCP when the external address changes or when the firewall status changes. Now you can enable inbound TCP without a static IP or dyndns service. -

+{%- endtrans %}

+

{% trans -%} The NTCP code within I2P is relatively lightweight (1/4 the size of the SSU code) because it uses the underlying Java TCP transport for reliable delivery. -

+{%- endtrans %}

-

NTCP Protocol Specification

+

{% trans %}NTCP Protocol Specification{% endtrans %}

-

Standard Message Format

-

- After establishment, - the NTCP transport sends individual I2NP messages, with a simple checksum. - The unencrypted message is encoded as follows: +

{% trans %}Standard Message Format{% endtrans %}

+

{% trans -%} +After establishment, +the NTCP transport sends individual I2NP messages, with a simple checksum. +The unencrypted message is encoded as follows: +{%- endtrans %}

  *  +-------+-------+--//--+---//----+-------+-------+-------+-------+
  *  | sizeof(data)  | data | padding | Adler checksum of sz+data+pad |
  *  +-------+-------+--//--+---//----+-------+-------+-------+-------+
- The data is then AES/256/CBC encrypted. The session key for the encryption - is negotiated during establishment (using Diffie-Hellman 2048 bit). - The establishment between two routers is implemented in the EstablishState class - and detailed below. - The IV for AES/256/CBC encryption is the last 16 bytes of the previous encrypted message. -

+

{% trans -%} +The data is then AES/256/CBC encrypted. The session key for the encryption +is negotiated during establishment (using Diffie-Hellman 2048 bit). +The establishment between two routers is implemented in the EstablishState class +and detailed below. +The IV for AES/256/CBC encryption is the last 16 bytes of the previous encrypted message. +{%- endtrans %}

-

+

{% trans -%} 0-15 bytes of padding are required to bring the total message length (including the six size and checksum bytes) to a multiple of 16. The maximum message size is currently 16 KB. Therefore the maximum data size is currently 16 KB - 6, or 16378 bytes. The minimum data size is 1. -

+{%- endtrans %}

-

Time Sync Message Format

-

- One special case is a metadata message where the sizeof(data) is 0. In - that case, the unencrypted message is encoded as: +

{% trans %}Time Sync Message Format{% endtrans %}

+

{% trans -%} +One special case is a metadata message where the sizeof(data) is 0. In +that case, the unencrypted message is encoded as: +{%- endtrans %}

  *  +-------+-------+-------+-------+-------+-------+-------+-------+
  *  |       0       |      timestamp in seconds     | uninterpreted             
@@ -66,19 +67,25 @@ The minimum data size is 1.
  *          uninterpreted           | Adler checksum of bytes 0-11  |
  *  +-------+-------+-------+-------+-------+-------+-------+-------+
+

{% trans -%} Total length: 16 bytes. The time sync message is sent at approximately 15 minute intervals. The message is encrypted just as standard messages are. +{%- endtrans %}

-

Checksums

+

{% trans %}Checksums{% endtrans %}

+

{% trans rfc1950='http://tools.ietf.org/html/rfc1950' -%} The standard and time sync messages use the Adler-32 checksum -as defined in the ZLIB Specification. +as defined in the ZLIB Specification. +{%- endtrans %}

-

Establishment Sequence

+

{% trans %}Establishment Sequence{% endtrans %}

+

{% trans -%} In the establish state, there is a 4-phase message sequence to exchange DH keys and signatures. In the first two messages there is a 2048-bit Diffie Hellman exchange. Then, DSA signatures of the critical data are exchanged to confirm the connection. +{%- endtrans %}

  * Alice                   contacts                      Bob
  * =========================================================
@@ -90,57 +97,58 @@ Then, DSA signatures of the critical data are exchanged to confirm the connectio
 
-  Legend:
-    X, Y: 256 byte DH public keys
+  {% trans %}Legend:{% endtrans %}
+    X, Y: {% trans %}256 byte DH public keys{% endtrans %}
     H(): 32 byte SHA256 Hash
     E(data, session key, IV): AES256 Encrypt
     S(): 40 byte DSA Signature
-    tsA, tsB: timestamps (4 bytes, seconds since epoch)
-    sk: 32 byte Session key
-    sz: 2 byte size of Alice identity to follow
+    tsA, tsB: {% trans %}timestamps (4 bytes, seconds since epoch){% endtrans %}
+    sk: {% trans %}32 byte Session key{% endtrans %}
+    sz: {% trans %}2 byte size of Alice identity to follow{% endtrans %}
-

DH Key Exchange

-

+

{% trans %}DH Key Exchange{% endtrans %}

+

{% trans cryptography=site_url('docs/how/cryptography') -%} The initial 2048-bit DH key exchange uses the same shared prime (p) and generator (g) as that used for I2P's -ElGamal encryption. -

+ElGamal encryption. +{%- endtrans %}

-

+

{% trans -%} The DH key exchange consists of a number of steps, displayed below. The mapping between these steps and the messages sent between I2P routers, is marked in bold. +{%- endtrans %}

    -
  1. Alice generates a secret 226-bit integer x. - She then calculates X = g^x mod p. -
    2. -
  2. Alice sends X to Bob (Message 1).
    3. -
  3. Bob generates a secret 226-bit integer y. - He then calculates Y = g^y mod p.
    4. -
  4. Bob sends Y to Alice.(Message 2)
    5. -
  5. Alice can now compute sessionKey = Y^x mod p.
    6. -
  6. Bob can now compute sessionKey = X^y mod p.
    7. -
  7. Both Alice and Bob now have a shared key sessionKey = g^(x*y) mod p.
    8. +
  8. {% trans %}Alice generates a secret 226-bit integer x. She then calculates X = g^x mod p.{% endtrans %}
    9. +
  9. {% trans %}Alice sends X to Bob (Message 1).{% endtrans %}
    10. +
  10. {% trans %}Bob generates a secret 226-bit integer y. He then calculates Y = g^y mod p.{% endtrans %}
    11. +
  11. {% trans %}Bob sends Y to Alice.(Message 2){% endtrans %}
    12. +
  12. {% trans %}Alice can now compute sessionKey = Y^x mod p.{% endtrans %}
    13. +
  13. {% trans %}Bob can now compute sessionKey = X^y mod p.{% endtrans %}
    14. +
  14. {% trans %}Both Alice and Bob now have a shared key sessionKey = g^(x*y) mod p.{% endtrans %}
+

{% trans -%} The sessionKey is then used to exchange identities in Message 3 and Message 4. -

+{%- endtrans %}

-

Message 1 (Session Request)

-This is the DH request. -Alice already has Bob's -Router Identity, +

{% trans %}Message 1 (Session Request){% endtrans %}

+

{% trans commonstructures=site_url('docs/spec/common-structures'), +netdb=site_url('docs/how/network-database') -%} +This is the DH request. Alice already has Bob's +Router Identity, IP address, and port, as contained in his -Router Info, +Router Info, which was published to the -network database. +network database. Alice sends Bob: +{%- endtrans %}

  *  X+(H(X) xor Bob.identHash)----------------------------->
 
-    Size: 288 bytes
+    {% trans %}Size:{% endtrans %} 288 bytes
-Contents: +

{% trans %}Contents:{% endtrans %}

  +----+----+----+----+----+----+----+----+
  |         X, as calculated from DH      |
@@ -158,28 +166,32 @@ Contents:
  |                                       |
  +----+----+----+----+----+----+----+----+
 
-  X: 256 byte X from Diffie Hellman
+  X: {% trans %}256 byte X from Diffie Hellman{% endtrans %}
 
-  HXxorHI:  SHA256 Hash(X) xored with SHA256 Hash(Bob's Router Identity)
+  HXxorHI:  {% trans commonstructures=site_url('docs/spec/common-structures') -%}
+SHA256 Hash(X) xored with SHA256 Hash(Bob's Router Identity)
+{%- endtrans %}
             (32 bytes)
-

Notes: -

-

Message 2 (Session Created)

+

{% trans %}Message 2 (Session Created){% endtrans %}

+

{% trans -%} This is the DH reply. Bob sends Alice: +{%- endtrans %}

  *  <----------------------------------------Y+E(H(X+Y)+tsB+padding, sk, Y[239:255])
 
-    Size: 304 bytes
+    {% trans %}Size:{% endtrans %} 304 bytes
-Unencrypted Contents: +

{% trans %}Unencrypted Contents:{% endtrans %}

  +----+----+----+----+----+----+----+----+
  |         Y as calculated from DH       |
@@ -201,19 +213,19 @@ Unencrypted Contents:
  |                                       |
  +----+----+----+----+----+----+----+----+
 
-  Y: 256 byte Y from Diffie Hellman
+  Y: {% trans %}256 byte Y from Diffie Hellman{% endtrans %}
 
-  HXY:  SHA256 Hash(X concatenated with Y)
+  HXY:  {% trans %}SHA256 Hash(X concatenated with Y){% endtrans %}
         (32 bytes)
 
-  tsB: 4 byte timestamp (seconds since the epoch)
+  tsB: {% trans %}4 byte timestamp (seconds since the epoch){% endtrans %}
 
-  padding: 12 bytes random data
+  padding: {% trans %}12 bytes random data{% endtrans %}
-Encrypted Contents: +

{% trans %}Encrypted Contents:{% endtrans %}

  +----+----+----+----+----+----+----+----+
  |         Y as calculated from DH       |
@@ -235,29 +247,31 @@ Encrypted Contents:
  |                                       |
  +----+----+----+----+----+----+----+----+
 
-  Y: 256 byte Y from Diffie Hellman
+  Y: {% trans %}256 byte Y from Diffie Hellman{% endtrans %}
 
-  encrypted data: 48 bytes AES encrypted using the DH session key and
-                  the last 16 bytes of Y as the IV
+  encrypted data: {% trans cryptography=site_url('docs/how/cryptography') -%}
+48 bytes AES encrypted using the DH session key and
+                  the last 16 bytes of Y as the IV{% endtrans %}
-

Notes: -

-

Message 3 (Session Confirm A)

+

{% trans %}Message 3 (Session Confirm A){% endtrans %}

+

{% trans -%} This contains Alice's router identity, and a DSA signature of the critical data. Alice sends Bob: +{%- endtrans %}

  *  E(sz+Alice.identity+tsA+padding+S(X+Y+Bob.identHash+tsA+tsB), sk, hX_xor_Bob.identHash[16:31])--->
 
-    Size: 448 bytes (typ. for 387 byte identity)
+    {% trans %}Size:{% endtrans %} 448 bytes (typ. for 387 byte identity)
-Unencrypted Contents: +

{% trans %}Unencrypted Contents:{% endtrans %}

  +----+----+----+----+----+----+----+----+
  |   sz    | Alice's Router Identity     |
@@ -283,21 +297,25 @@ Unencrypted Contents:
  |                                       |
  +----+----+----+----+----+----+----+----+
 
-  sz: 2 byte size of Alice's router identity to follow (should always be 387)
+  sz: {% trans %}2 byte size of Alice's router identity to follow (should always be 387){% endtrans %}
 
-  ident: Alice's 387 byte Router Identity
+  ident: {% trans commonstructures=site_url('docs/spec/common-structures') -%}
+Alice's 387 byte Router Identity
+{%- endtrans %}
 
-  tsA: 4 byte timestamp (seconds since the epoch)
+  tsA: {% trans %}4 byte timestamp (seconds since the epoch){% endtrans %}
 
-  padding: 15 bytes random data
+  padding: {% trans %}15 bytes random data{% endtrans %}
 
-  signature: the 40 byte DSA signature of the following concatenated data:
-             X, Y, Bob's Router Identity, tsA, tsB.
-             Alice signs it with the private signing key associated with the public signing key in her Router Identity
+  signature: {% trans commonstructures=site_url('docs/spec/common-structures') -%}
+the 40 byte DSA signature of the following concatenated data:
+             X, Y, Bob's Router Identity, tsA, tsB.
+             Alice signs it with the private signing key associated with the public signing key in her Router Identity
+{%- endtrans %}
-Encrypted Contents: +

{% trans %}Encrypted Contents:{% endtrans %}

  +----+----+----+----+----+----+----+----+
  |                                       |
@@ -307,30 +325,36 @@ Encrypted Contents:
  |                                       |
  +----+----+----+----+----+----+----+----+
 
-  encrypted data: 448 bytes AES encrypted using the DH session key and
+  encrypted data: {% trans cryptography=site_url('docs/how/cryptography') -%}
+448 bytes AES encrypted using the DH session key and
                   the last 16 bytes of HXxorHI (i.e., the last 16 bytes of message #1) as the IV
+{%- endtrans %}
-

Notes: -

-

Message 4 (Session Confirm B)

+

{% trans %}Message 4 (Session Confirm B){% endtrans %}

+

{% trans -%} This is a DSA signature of the critical data. Bob sends Alice: +{%- endtrans %}

  *  <----------------------E(S(X+Y+Alice.identHash+tsA+tsB)+padding, sk, prev)
 
-    Size: 48 bytes
+    {% trans %}Size:{% endtrans %} 48 bytes
-Unencrypted Contents: +

{% trans %}Unencrypted Contents:{% endtrans %}

  +----+----+----+----+----+----+----+----+
  |                                       |
@@ -347,16 +371,18 @@ Unencrypted Contents:
  +----+----+----+----+----+----+----+----+
 
 
-  signature: the 40 byte DSA signature of the following concatenated data:
-             X, Y, Alice's Router Identity, tsA, tsB.
-             Bob signs it with the private signing key associated with the public signing key in his Router Identity
+  signature: {% trans commonstructures=site_url('docs/spec/common-structures') -%}
+the 40 byte DSA signature of the following concatenated data:
+             X, Y, Alice's Router Identity, tsA, tsB.
+             Bob signs it with the private signing key associated with the public signing key in his Router Identity
+{%- endtrans %}
 
-  padding: 8 bytes random data
+  padding: {% trans %}8 bytes random data{% endtrans %}
-Encrypted Contents: +

{% trans %}Encrypted Contents:{% endtrans %}

  +----+----+----+----+----+----+----+----+
  |                                       |
@@ -366,68 +392,82 @@ Encrypted Contents:
  |                                       |
  +----+----+----+----+----+----+----+----+
 
-  encrypted data: 48 bytes AES encrypted using the DH session key and
+  encrypted data: {% trans cryptography=site_url('docs/how/cryptography') -%}
+48 bytes AES encrypted using the DH session key and
                   the last 16 bytes of the encrypted contents of message #2 as the IV
+{%- endtrans %}
-

Notes: -

-

After Establishment

-

+

{% trans %}After Establishment{% endtrans %}

+

{% trans -%} The connection is established, and standard or time sync messages may be exchanged. All subsequent messages are AES encrypted using the negotiated DH session key. Alice will use the last 16 bytes of the encrypted contents of message #3 as the next IV. Bob will use the last 16 bytes of the encrypted contents of message #4 as the next IV. -

+{%- endtrans %}

-

Check Connection Message

+

{% trans %}Check Connection Message{% endtrans %}

+

{% trans -%} Alternately, when Bob receives a connection, it could be a check connection (perhaps prompted by Bob asking for someone to verify his listener). Check Connection is not currently used. However, for the record, check connections are formatted as follows. - A check info connection will receive 256 bytes containing: +A check info connection will receive 256 bytes containing: +{%- endtrans %}

-

Discussion

-Now on the NTCP Discussion Page. +

{% trans %}Discussion{% endtrans %}

+

{% trans ntcpdisc=site_url('docs/discussions/ntcp') -%} +Now on the NTCP Discussion Page. +{%- endtrans %}

-

Future Work

- {% endblock %} diff --git a/i2p2www/pages/site/docs/transport/ssu.html b/i2p2www/pages/site/docs/transport/ssu.html index 1992bb64..a7ae3caa 100644 --- a/i2p2www/pages/site/docs/transport/ssu.html +++ b/i2p2www/pages/site/docs/transport/ssu.html @@ -1,50 +1,60 @@ {% extends "global/layout.html" %} -{% block title %}SSU Transport{% endblock %} -{% block lastupdated %}October 2012{% endblock %} +{% block title %}{% trans %}SSU Transport{% endtrans %}{% endblock %} +{% block lastupdated %}{% trans %}October 2012{% endtrans %}{% endblock %} {% block accuratefor %}0.9.2{% endblock %} {% block content %} -

Secure Semireliable UDP (SSU)

-

+

{% trans %}Secure Semireliable UDP{% endtrans %} (SSU)

+

{% trans transports=site_url('docs/transport'), ntcp=site_url('docs/transport/ntcp') -%} SSU (also called "UDP" in much of the I2P documentation and user interfaces) -is one of two transports currently implemented in I2P. -The other is NTCP. -

+is one of two transports currently implemented in I2P. +The other is NTCP. +{%- endtrans %}

+ +

{% trans -%} SSU is the newer of the two transports, introduced in I2P release 0.6. In a standard I2P installation, the router uses both NTCP and SSU for outbound connections. +{%- endtrans %}

-

SSU Services

+

{% trans %}SSU Services{% endtrans %}

+

{% trans -%} Like the NTCP transport, SSU provides reliable, encrypted, connection-oriented, point-to-point data transport. Unique to SSU, it also provides IP detection and NAT traversal services, including: +{%- endtrans %}

-

Protocol Details

+

{% trans %}Protocol Details{% endtrans %}

-

Congestion control

+

{% trans %}Congestion control{% endtrans %}

-

SSU's need for only semireliable delivery, TCP-friendly operation, +

{% trans -%} +SSU's need for only semireliable delivery, TCP-friendly operation, and the capacity for high throughput allows a great deal of latitude in congestion control. The congestion control algorithm outlined below is -meant to be both efficient in bandwidth as well as simple to implement.

+meant to be both efficient in bandwidth as well as simple to implement. +{%- endtrans %}

-

Packets are scheduled according to the router's policy, taking care +

{% trans -%} +Packets are scheduled according to the router's policy, taking care not to exceed the router's outbound capacity or to exceed the measured capacity of the remote peer. The measured capacity operates along the lines of TCP's slow start and congestion avoidance, with additive increases to the sending capacity and multiplicative decreases in face of congestion. Unlike for TCP, routers may give up on some messages after a given period or number of retransmissions while continuing to transmit -other messages.

+other messages. +{%- endtrans %}

-

The congestion detection techniques vary from TCP as well, since each +

{% trans -%} +The congestion detection techniques vary from TCP as well, since each message has its own unique and nonsequential identifier, and each message has a limited size - at most, 32KB. To efficiently transmit this feedback to the sender, the receiver periodically includes a list of fully ACKed @@ -52,48 +62,62 @@ message identifiers and may also include bitfields for partially received messages, where each bit represents the reception of a fragment. If duplicate fragments arrive, the message should be ACKed again, or if the message has still not been fully received, the bitfield should be -retransmitted with any new updates.

+retransmitted with any new updates. +{%- endtrans %}

-

The current implementation does not pad the packets to +

{% trans -%} +The current implementation does not pad the packets to any particular size, but instead just places a single message fragment into a packet and sends it off (careful not to exceed the MTU). -

+{%- endtrans %}

MTU

-

+

{% trans -%} As of router version 0.8.12, two MTU values are used: 620 and 1484. The MTU value is adjusted based on the percentage of packets that are retransmitted. -

+{%- endtrans %}

+ +

{% trans -%} For both MTU values, it is desirable that (MTU % 16) == 12, so that the payload portion after the 28-byte IP/UDP header is a multiple of 16 bytes, for encryption purposes. This calculation is for IPv4 only. While the protocol as specified supports IPv6 addresses, IPv6 is not yet implemented. -

+{%- endtrans %}

+ +

{% trans -%} For the small MTU value, it is desirable to pack a 2646-byte Variable Tunnel Build Message efficiently into multiple packets; with a 620-byte MTU, it fits into 5 packets with nicely. -

+{%- endtrans %}

+ +

{% trans -%} Based on measurements, 1492 fits nearly all reasonably small I2NP messages (larger I2NP messages may be up to 1900 to 4500 bytes, which isn't going to fit into a live network MTU anyway). -

+{%- endtrans %}

+ +

{% trans -%} The MTU values were 608 and 1492 for releases 0.8.9 - 0.8.11. The large MTU was 1350 prior to release 0.8.9. -

+{%- endtrans %}

+ +

{% trans -%} The maximum receive packet size is 1571 bytes as of release 0.8.12. For releases 0.8.9 - 0.8.11 it was 1535 bytes. Prior to release 0.8.9 it was 2048 bytes. -

+{%- endtrans %}

+ +

{% trans -%} As of release 0.9.2, if a router's network interface MTU is less than 1484, it will publish that in the network database, and other routers should honor that when a connection is established. -

+{%- endtrans %}

-

Message Size Limits

-

+

{% trans %}Message Size Limits{% endtrans %}

+

{% trans -%} While the maximum message size is nominally 32KB, the practical limit differs. The protocol limits the number of fragments to 7 bits, or 128. The current implementation, however, limits each message to a maximum of 64 fragments, @@ -102,97 +126,115 @@ Due to overhead for bundled LeaseSets and session keys, the practical limit at the application level is about 6KB lower, or about 26KB. Further work is necessary to raise the UDP transport limit above 32KB. For connections using the larger MTU, larger messages are possible. -

+{%- endtrans %}

-

Keys

+

{% trans %}Keys{% endtrans %}

-

All encryption used is AES256/CBC with 32 byte keys and 16 byte IVs. +

{% trans -%} +All encryption used is AES256/CBC with 32 byte keys and 16 byte IVs. The MAC and session keys are negotiated as part of the DH exchange, used for the HMAC and encryption, respectively. Prior to the DH exchange, -the publicly knowable introKey is used for the MAC and encryption.

+the publicly knowable introKey is used for the MAC and encryption. +{%- endtrans %}

-

When using the introKey, both the initial message and any subsequent +

{% trans -%} +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 requester (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.

+Bob. +{%- endtrans %}

-

Upon receiving a message, the receiver checks the "from" IP address and port +

{% trans -%} +Upon receiving a message, the receiver checks the "from" IP address and port with all established sessions - if there are matches, that session's MAC keys are tested 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.

+it may be dropped anyway. +{%- endtrans %}

-

If Alice and Bob have an established session, but Alice loses the +

{% trans -%} +If Alice and Bob have an established session, but Alice loses the keys 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.

+new one. +{%- endtrans %}

-

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

+

{% trans rfc3526='http://www.faqs.org/rfcs/rfc3526.html' -%} +For the DH key agreement, +RFC3526 2048bit +MODP group (#14) is used: +{%- endtrans %}

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

+

{% trans cryptography=site_url('docs/how/cryptography') -%} These are the same p and g used for I2P's -ElGamal encryption. -

+ElGamal encryption. +{%- endtrans %}

-

Replay prevention

+

{% trans %}Replay prevention{% endtrans %}

-

Replay prevention at the SSU layer occurs by rejecting packets +

{% trans -%} +Replay prevention at the SSU layer occurs by rejecting packets with exceedingly old timestamps or those which reuse an IV. To detect duplicate IVs, a sequence of Bloom filters are employed to -"decay" periodically so that only recently added IVs are detected.

+"decay" periodically so that only recently added IVs are detected. +{%- endtrans %}

-

The messageIds used in DataMessages are defined at layers above +

{% trans -%} +The messageIds used in DataMessages are defined at layers above the SSU transport and are passed through transparently. These IDs are not in any particular order - in fact, they are likely to be entirely random. The SSU layer makes no attempt at messageId -replay prevention - higher layers should take that into account.

+replay prevention - higher layers should take that into account. +{%- endtrans %}

-

Addressing

+

{% trans %}Addressing{% endtrans %}

-

To contact an SSU 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.

+

{% trans -%} +To contact an SSU 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. +{%- endtrans %}

     Direct: host, port, introKey, options
   Indirect: tag, relayhost, port, relayIntroKey, targetIntroKey, options
-

Each of the addresses may also expose a series of options - special +

{% trans -%} +Each of the addresses may also expose a series of options - special capabilities of that particular peer. For a list of available -capabilities, see below.

+capabilities, see below. +{%- endtrans %}

-

-The addresses, options, and capabilities are published in the network database. -

+

{% trans netdb=site_url('docs/how/network-database') -%} +The addresses, options, and capabilities are published in the network database. +{%- endtrans %}

-

Direct Session Establishment

-

+

{% trans %}Direct Session Establishment{% endtrans %}

+

{% trans -%} Direct session establishment is used when no third party is required for NAT traversal. The message sequence is as follows: -

+{%- endtrans %}

-

Connection establishment (direct)

-

+

{% trans %}Connection establishment (direct){% endtrans %}

+

{% trans -%} Alice connects directly to Bob. -

+{%- endtrans %}

         Alice                         Bob
     SessionRequest --------------------->
@@ -203,28 +245,35 @@ Alice connects directly to Bob.
     DatabaseStoreMessage --------------->
     Data <---------------------------> Data
-

+ +

{% trans i2npspec=site_url('docs/spec/i2np') -%} After the SessionConfirmed message is received, Bob sends a small -DeliveryStatus message +DeliveryStatus message as a confirmation. In this message, the 4-byte message ID is set to a random number, and the 8-byte "arrival time" is set to the current network-wide ID, which is 2 (i.e. 0x0000000000000002). -

+{%- endtrans %}

+ +

{% trans i2npspec=site_url('docs/spec/i2np'), +commonstructures=site_url('docs/spec/common-structures') -%} After the status message is sent, the peers exchange -DatabaseStore messages +DatabaseStore messages containing their -RouterInfos. -

+RouterInfos. +{%- endtrans %}

+ +

{% trans -%} It does not appear that the type of the status message or its contents matters. It was originally added becasue the DatabaseStore message was delayed several seconds; since the store is now sent immediately, perhaps the status message can be eliminated. -

+{%- endtrans %}

-

Introduction

+

{% trans %}Introduction{% endtrans %}

-

Introduction keys are delivered through an external channel +

{% trans -%} +Introduction keys are delivered through an external channel (the network database, where they are identical to the router Hash for now) and must be used when establishing a session key. For the indirect address, the peer must first contact the relayhost and ask them for @@ -234,9 +283,11 @@ 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).

+not necessary to any intermediary relay peer). +{%- endtrans %}

-

Indirect session establishment by means of a third party introduction +

{% trans -%} +Indirect session establishment by means of a third party introduction is necessary for efficient NAT traversal. Charlie, a router behind a NAT or firewall which does not allow unsolicited inbound UDP packets, first contacts a few peers, choosing some to serve as introducers. Each @@ -251,7 +302,8 @@ Alice back a RelayResponse packet containing Charlie's public IP and port number. When Charlie receives the RelayIntro packet, he sends off a small random packet to Alice's IP and port (poking a hole in his NAT/firewall), and when Alice receives Bob's RelayResponse packet, she begins a new -full direction session establishment with the specified IP and port.

+full direction session establishment with the specified IP and port. +{%- endtrans %}

-

Connection establishment (indirect using an introducer)

+

{% trans %}Connection establishment (indirect using an introducer){% endtrans %}

+

{% trans -%} Alice first connects to introducer Bob, who relays the request to Charlie. +{%- endtrans %}

         Alice                         Bob                  Charlie
@@ -279,18 +333,20 @@ Alice first connects to introducer Bob, who relays the request to Charlie.
     Data <--------------------------------------------------> Data
-

+

{% trans -%} After the hole punch, the session is established between Alice and Charlie as in a direct establishment. -

+{%- endtrans %}

-

Peer testing

+

{% trans %}Peer testing{% endtrans %}

-

The automation of collaborative reachability testing for peers is +

{% trans -%} +The automation of collaborative reachability testing for peers is enabled by a sequence of PeerTest messages. With its proper execution, a peer will be able to determine their own reachability and may update its behavior accordingly. The testing process is -quite simple:

+quite simple: +{%- endtrans %}

         Alice                  Bob                  Charlie
@@ -303,147 +359,193 @@ quite simple:

          <------------------------------------------PeerTest
-

Each of the PeerTest messages carry a nonce identifying the +

{% trans -%} +Each of the PeerTest messages carry a nonce identifying the test series itself, as initialized by Alice. If Alice doesn't get a particular message that she expects, she will retransmit accordingly, and based upon the data received or the messages missing, she will know her reachability. The various end states -that may be reached are as follows:

+that may be reached are as follows: +{%- endtrans %}

-

Alice should choose Bob arbitrarily from known peers who seem +

{% trans -%} +Alice should choose Bob arbitrarily from known peers who seem to be capable of participating in peer tests. Bob in turn should choose Charlie arbitrarily from peers that he knows who seem to be capable of participating in peer tests and who are on a different IP from both Bob and Alice. If the first error condition occurs (Alice doesn't get PeerTest messages from Bob), Alice may decide -to designate a new peer as Bob and try again with a different nonce.

+to designate a new peer as Bob and try again with a different nonce. +{%- endtrans %}

-

Alice's introduction key is included in all of the PeerTest +

{% trans -%} +Alice's introduction key is included in all of the PeerTest messages so that she doesn't need to already have an established session with Bob and so that Charlie can contact her without knowing any additional information. Alice may go on to establish a session -with either Bob or Charlie, but it is not required.

+with either Bob or Charlie, but it is not required. +{%- endtrans %}

-

Transmission window, ACKs and Retransmissions

-

+

{% trans %}Transmission window, ACKs and Retransmissions{% endtrans %}

+

{% trans ssuspec=site_url('docs/spec/ssu') -%} The DATA message may contain ACKs of full messages and partial ACKs of individual fragments of a message. See the data message section of -the protocol specification page +the protocol specification page for details. -

+{%- endtrans %}

+ +

{% trans streaming=site_url('docs/api/streaming') -%} The details of windowing, ACK, and retransmission strategies are not specified here. See the Java code for the current implementation. During the establishment phase, and for peer testing, routers should implement exponential backoff for retransmission. For an established connection, routers should implement an adjustable transmission window, RTT estimate and timeout, similar to TCP -or streaming. +or streaming. See the code for initial, min and max parameters. -

+{%- endtrans %}

-

Security

-

+

{% trans %}Security{% endtrans %}

+

{% trans -%} UDP source addresses may, of course, be spoofed. Additionally, the IPs and ports contained inside specific SSU messages (RelayRequest, RelayResponse, RelayIntro, PeerTest) may not be legitimate. Also, certain actions and responses may need to be rate-limited. -

+{%- endtrans %}

+ +

{% trans -%} The details of validation are not specified here. Implementers should add defenses where appropriate. -

+{%- endtrans %}

-

Peer capabilities

+

{% trans %}Peer capabilities{% endtrans %}

B
-
If the peer address contains the 'B' capability, that means - they are willing and able to participate in peer tests as - a 'Bob' or 'Charlie'.
+
{% trans -%} +If the peer address contains the 'B' capability, that means +they are willing and able to participate in peer tests as +a 'Bob' or 'Charlie'. +{%- endtrans %}
C
-
If the peer address contains the 'C' capability, that means - they are willing and able to serve as an introducer - serving - as a Bob for an otherwise unreachable Alice.
+
{% trans -%} +If the peer address contains the 'C' capability, that means +they are willing and able to serve as an introducer - serving +as a Bob for an otherwise unreachable Alice. +{%- endtrans %}
-

Future Work

- + +

{% trans %}Implementation Diagram{% endtrans %}

+

{% trans -%} This diagram should accurately reflect the current implementation, however there may be small differences. +{%- endtrans %}

-

Specification

-Now on the SSU specification page. +

{% trans %}Specification{% endtrans %}

+{% trans %}Now on the SSU specification page{% endtrans %}. {% endblock %}