From d2068f3db7ec3e912787e4e9cd57d35c38ad4cb2 Mon Sep 17 00:00:00 2001
From: zzz <zzz@mail.i2p>
Date: Tue, 24 Aug 2010 01:48:03 +0000
Subject: [PATCH] tunnel routing, garlic routing, fixups

---
 www.i2p2/pages/common_structures_spec.html |  24 +-
 www.i2p2/pages/how.html                    |  12 +-
 www.i2p2/pages/how_cryptography.html       |  26 +-
 www.i2p2/pages/how_garlicrouting.html      | 273 ++++++++++++++++++---
 www.i2p2/pages/how_networkdatabase.html    |  12 +-
 www.i2p2/pages/how_peerselection.html      |   2 +-
 www.i2p2/pages/how_tunnelrouting.html      | 261 +++++++++++++-------
 www.i2p2/pages/i2np_spec.html              |   2 +-
 www.i2p2/pages/ntcp.html                   |   2 +-
 www.i2p2/pages/tunnel-alt.html             |  13 +-
 10 files changed, 472 insertions(+), 155 deletions(-)

diff --git a/www.i2p2/pages/common_structures_spec.html b/www.i2p2/pages/common_structures_spec.html
index 498fe775..64795613 100644
--- a/www.i2p2/pages/common_structures_spec.html
+++ b/www.i2p2/pages/common_structures_spec.html
@@ -54,7 +54,8 @@ Deprecated - unused
 <h2 id="type_PublicKey">PublicKey</h2>
 <h4>Description</h4>
 <p>
-  This structure is used in ElGamal encryption, representing only the exponent, not the primes, which are constant and defined in the appropriate spec.
+  This structure is used in ElGamal encryption, representing only the exponent, not the primes, which are constant and defined in
+  <a href="how_cryptography.html#elgamal">the cryptography specification</a>.
 </p>
 <h4>Contents</h4>
 <p>
@@ -66,7 +67,8 @@ Deprecated - unused
 <h2 id="type_PrivateKey">PrivateKey</h2>
 <h4>Description</h4>
 <p>
-  This structure is used in ElGamal decryption, representing only the exponent, not the primes which are constant and defined in the appropriate spec.
+  This structure is used in ElGamal decryption, representing only the exponent, not the primes which are constant and defined in
+  <a href="how_cryptography.html#elgamal">the cryptography specification</a>.
 </p>
 <h4>Contents</h4>
 <p>
@@ -150,7 +152,7 @@ Deprecated - unused
 <h2 id="type_TunnelId">TunnelId</h2>
 <h4>Description</h4>
 <p>
-  Defines an identifier that is unique within a particular set of routers for a tunnel.
+  Defines an identifier that is unique to each router in a tunnel.
 </p>
 <h4>Contents</h4>
 <p>
@@ -191,6 +193,19 @@ payload :: data
 {% endfilter %}
 </pre>
 
+<h4>Notes</h4>
+<ul>
+<li>
+For <a href="#struct_RouterIdentity">Router Identities</a>, the Certificate is always NULL, no others are currently implemented.
+</li><li>
+For <a href="i2np_spec.html#struct_GarlicClove">Garlic Cloves</a>, the Certificate is always NULL, no others are currently implemented.
+</li><li>
+For <a href="i2np_spec.html#msg_Garlic">Garlic Messages</a>, the Certificate is always NULL, no others are currently implemented.
+</li><li>
+For <a href="#struct_Destination">Destinations</a>, the Certificate may be non-NULL,
+however non-NULL certs are not widely used, and any checking is left to the application-level.
+</li></ul>
+
 <h4><a href="http://docs.i2p2.de/core/net/i2p/data/Certificate.html">Javadoc</a></h4>
 
 
@@ -456,7 +471,7 @@ end_date :: Date
 +----+----+----+----+----+----+----+----+
 
 destination :: Destination
-               length -> >= 397 bytes
+               length -> >= 387 bytes
 
 encryption_key :: PublicKey
                   length -> 256 bytes
@@ -466,6 +481,7 @@ signing_key :: SigningPublicKey
 
 num :: Integer
        length -> 1 byte
+       value: 0 <= num <= 6
 
 leases :: [Lease]
           length -> >= $num*399 bytes
diff --git a/www.i2p2/pages/how.html b/www.i2p2/pages/how.html
index 790383d7..6251c97b 100644
--- a/www.i2p2/pages/how.html
+++ b/www.i2p2/pages/how.html
@@ -118,10 +118,10 @@ I2P is a message-oriented router. The messages sent between routers are defined
 Selecting peers, requesting tunnels through those peers, and encrypting and routing messages through these tunnels.
 <ul>
 <li><a href="how_peerselection.html">Peer profiling and selection</a></li>
-<li><a href="how_tunnelrouting.html">Tunnel routing</a></li>
-<li><a href="how_garlicrouting.html">Garlic routing</a></li>
+<li><a href="how_tunnelrouting.html">Tunnel routing overview</a></li>
+<li><a href="how_garlicrouting.html">Garlic routing and "garlic" terminology</a></li>
 <li><a href="tunnel-alt.html">Tunnel building and encryption</a></li>
-<li><a href="how_elgamalaes.html">ElGamal/AES+SessionTag</a> for build request encryption</li>
+<li><a href="how_elgamalaes.html">ElGamal/AES</a> for build request encryption</li>
 <li><a href="how_cryptography.html">ElGamal and AES cryptography details</a></li>
 <li><a href="tunnel-alt-creation.html">Tunnel building specification</a></li>
 <li><a href="tunnel_message_spec.html">Low-level tunnel message specification</a></li>
@@ -154,6 +154,8 @@ The protocols for direct (point-to-point) router to router communication.
 <a href="jbigi.html">Native BigInteger Library</a>
 </li><li>
 Time synchronization and NTP
+</li><li>
+<a href="performance.html">Performance</a>
 </li></ul>
 
 <h3>Developer's Guides</h3>
@@ -163,6 +165,10 @@ Time synchronization and NTP
 <a href="newtranslators.html">New Translator's Guide</a>
 </li><li>
 <a href="monotone.html">Monotone Guide</a>
+</li><li>
+<a href="http://docs.i2p2.i2p/">Javadocs</a>
+</li><li>
+<a href="todo.html">To Do List</a>
 </li></ul>
 
 
diff --git a/www.i2p2/pages/how_cryptography.html b/www.i2p2/pages/how_cryptography.html
index 1478ce12..93e63f82 100644
--- a/www.i2p2/pages/how_cryptography.html
+++ b/www.i2p2/pages/how_cryptography.html
@@ -26,12 +26,17 @@ block is formatted (in network byte order):
 <p>
 <p>
 <PRE>
- |_______1_______2_______3_______4_______5_______6_______7_______8
- |nonzero|H(data)
- |
- |
- |
- |       | data     ...  |
+   +----+----+----+----+----+----+----+----+
+   |nonz|           H(data)                |
+   +----+                                  +
+   |                                       |
+   +                                       +
+   |                                       |
+   +                                       +
+   |                                       |
+   +    +----+----+----+----+----+----+----+
+   |    |  data...
+   +----+----+----+--//                   
 
 </PRE>
 <p>
@@ -266,11 +271,12 @@ It may be quite difficult to make any change backward-compatible.
 
 <h2 id="transports">Transports</h2>
 <p>
-At the lowest 
-level, inter-router communication is protected by the transport layer security.
+At the lowest protocol layer,
+point-to-point inter-router communication is protected by the transport layer security.
 Both transports use 256 byte (2048 bit) Diffie-Hellman key exchange
 using
-<a href="#elgamal">the same shared prime and generator as specified above for ElGamal</a>.
+<a href="#elgamal">the same shared prime and generator as specified above for ElGamal</a>,
+followed by symmetric AES encryption as described above.
 </p>
 
 <H3><a name="tcp">NTCP connections</a></H3>
@@ -305,7 +311,7 @@ checking.
 See <a href="udp.html#keys">the SSU specification</a> for details.
 
 
-<H3>References</H3>
+<H2>References</H2>
 <ul>
 <li>
 <a href="http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf">NIST 800-57</a>
diff --git a/www.i2p2/pages/how_garlicrouting.html b/www.i2p2/pages/how_garlicrouting.html
index a1929350..21d21b21 100644
--- a/www.i2p2/pages/how_garlicrouting.html
+++ b/www.i2p2/pages/how_garlicrouting.html
@@ -1,53 +1,258 @@
 {% extends "_layout.html" %}
-{% block title %}How Garlic Routing Works{% endblock %}
+{% block title %}Garlic Routing{% endblock %}
 {% block content %}<p>
-As briefly explained on the <a href="how_intro">intro</a>, in addition to sending 
-messages through tunnels (via <a href="how_tunnelrouting">tunnels</a>), I2P uses a technique called
-"garlic routing" - layered encryption of messages, passing through routers 
-selected by the original sender.  This is similar to the way Mixmaster
+Updated August 2010 for release 0.8
+</p>
+
+<h2>Garlic Routing and "Garlic" Terminology</h2>
+<p>
+The terms "garlic routing" and "garlic encryption" are often used rather loosely when referring to I2P's technology.
+Here, we explain the history of the terms, the various meanings, and
+the usage of "garlic" methods in I2P.
+</p><p>
+"Garlic routing" was first coined by
+<a href="http://www.cs.princeton.edu/~mfreed/">Michael J. Freedman</a>
+in Roger Dingledine's Free Haven 
+<a href="http://www.freehaven.net/papers.html">Master's thesis</a> Section 8.1.1 (June 2000), as derived from 
+<a href="http://onion-router.net/">Onion Routing</a>.
+</p><p>
+"Garlic" may have been used originally by I2P developers because I2P implements a form of
+bundling as Freedman describes, or simply to emphasize general differences from Tor.
+The specific reasoning may be lost to history.
+Generally, when referring to I2P, the term "garlic" may mean one of three things:
+<ol><li>
+Layered Encryption
+</li><li>
+Bundling multiple messages together
+</li><li>
+ElGamal/AES Encryption
+</li></ol>
+Unfortunately, I2P's usage of "garlic" terminology over the past seven years has not always been precise; therefore the reader is
+cautioned when encountering the term.
+Hopefully, the explanation below will make things clear.
+</p>
+
+<h3>Layered Encryption</h3>
+<p>
+Onion routing is a technique for building paths, or tunnels, through a series of peers,
+and then using that tunnel.
+Messages are repeatedly encrypted by the originator, and then decrypted by each hop.
+During the building phase, only the routing instructions for the next hop are exposed to each peer.
+During the operating phase, messages are passed through the tunnel, and the
+message and its routing instructions are only exposed to the endpoint of the tunnel.
+</p><p>
+This is similar to the way Mixmaster
 (see <a href="how_networkcomparisons">network comparisons</a>) sends messages - taking a message, encrypting it
 to the recipient's public key, taking that encrypted message and encrypting
 it (along with instructions specifying the next hop), and then taking that
 resulting encrypted message and so on, until it has one layer of encryption
-per hop along the path.  The only significant difference between that technique
-and I2P's garlic routing is that at each layer, any number of messages can be
+per hop along the path.
+</p><p>
+In this sense, "garlic routing" as a general concept is identical to "onion routing".
+As implemented in I2P, of course, there are several differences from the implementation in Tor; see below.
+Even so, there are substantial similarities such that I2P benefits from a
+<a href="http://www.onion-router.net/Publications.html">large amount of academic research on onion routing</a>,
+<a href="http://freehaven.net/anonbib/topic.html">Tor, and similar mixnets</a>.
+</p>
+
+
+<h3>Bundling Multiple Messages</h3>
+<p>
+Michael Freedman defined "garlic routing" as an extension to onion routing,
+in which multiple messages are bundled together.
+He called each message a "bulb".
+All the messages, each with its own delivery instructions, are exposed at the
+endpoint.
+This allows the efficient bundling of an onion routing "reply block" with the original message.
+</p><p>
+This concept is implemented in I2P, as described below.
+Our term for garlic "bulbs" is "cloves".
+Any number of messages can be
 contained, instead of just a single message.
+This is a significant distinction from the onion routing implemented in Tor.
+However, it is only one of many major architectural differences between I2P and Tor;
+perhaps it is not, by itself, enough to justify a change in terminology.
+
+</p><p>
+Another difference
+from the method described by Freedman with I2P's bundling
+is that the path is unidirectional - there is no "turning point" as seen in onion routing
+or mixmaster reply blocks, which greatly simplifies the algorithm and allows for more flexible
+and reliable delivery.
+</p>
+
+
+<h3>ElGamal/AES Encryption</h3>
+In some cases, "garlic encryption" may simply mean
+<a href="how_elgamalaes">ElGamal/AES+SessionTag</a> encryption
+(without multiple layers).
+
+
+
+<H2>"Garlic" Methods in I2P</H2>
 
 <p>
-In addition to the cloves, each unwrapped garlic message contains a sender
-specified amount of padding data, allowing the sender to take active countermeasures 
-against traffic analysis.
-
-<H2>Uses within I2P</H2>
-
-<p>
-I2P uses garlic routing in three places:
-<UL>
-<li> For building tunnels
-<li> For determining the success or failure of end to end message delivery (by wrapping an additional 
-     DeliveryStatusMessage in with the payload, where the clove containing the DeliveryStatusMessage 
-     has instructions forwarding it back through other routers and tunnels to the original sender)
-
+Now that we've defined various "garlic" terms, we can say that
+I2P uses garlic routing, bundling and encryption in three places:
+<ol>
+<li> For building and routing through tunnels (layered encryption)
+<li> For determining the success or failure of end to end message delivery (bundling)
 <li> For publishing some network database entries (dampening the probability of a successful traffic analysis attack)
-</UL>
+     (ElGamal/AES)
+</ol>
 <p>
 There are also significant ways that this technique can be used to improve the performance of the network, 
 exploiting transport latency/throughput tradeoffs, and branching data through redundant paths to increase reliability.  
 
-<H2>Encryption</H2>
 
+<h3>Tunnel Building and Routing</h3>
 <p>
-The encryption of each layer in the garlic message uses the <a href="how_elgamalaes">ElGamal/AES+SessionTag</a> algorithm, 
-which avoids the cost of a full 2048bit ElGamal encryption for subsequent messages (using instead a random previously 
-specified SessionTag plus 256bit AES encryption).
+In I2P, tunnels are unidirectional, and we require two tunnels
+(one outbound and one inbound) for end-to-end communication in each direction.
+Therefore, four tunnels are required for a single round-trip message and reply.
+</p><p>
+Tunnels are built, and then used, with layered encryption.
+This is described on the
+<a href="tunnel-alt.html">tunnel implementation page</a>.
+Tunnel building details are defined on
+<a href="tunnel-alt-creation.html">this page</a>.
+We use
+<a href="how_elgamalaes">ElGamal/AES+SessionTag</a> for the encryption.
+</p><p>
+Tunnels are a general-purpose mechanism to transport all
+<a href="i2np.html">I2NP messages</a>, and
+<a href="i2np_spec.html#msg_Garlic">Garlic Messages</a> are not used to build tunnels.
+We do not bundle multiple
+<a href="i2np.html">I2NP messages</a> into a single
+<a href="i2np_spec.html#msg_Garlic">Garlic Message</a> for unwrapping at the outbound tunnel endpoint;
+the tunnel encryption is sufficient.
+</p>
+
+
+<h3>End-to-End Message Bundling</h3>
+<p>
+At the layer above tunnels, I2P delivers end-to-end messages between
+<a href="common_structures_spec#struct_Destination">Destinations</a>.
+Just as within a single tunnel, we use
+<a href="how_elgamalaes">ElGamal/AES+SessionTag</a> for the encryption.
+Each client message as delivered to the router through the
+<a href="i2cp.html">I2CP interface</a> becomes a single
+<a href="i2np.html#struct_GarlicClove">Garlic Clove</a>
+with its own
+<a href="tunnel_message_spec.html#delivery">Delilvery Instructions</a>,
+inside a
+<a href="i2np.html#msg_Garlic">Garlic Message</a>.
+Delivery Instructions may specify a Destination, Router, or Tunnel.
+</p><p>
+Generally, a Garlic Message will contain only one clove.
+However, the router will periodically bundle two additional
+cloves in the Garlic Message:
+
+<ol><li>
+A
+<a href="i2np.html#msg_DeliveryStatus">Delivery Status Message</a>,
+with
+<a href="tunnel_message_spec.html#delivery">Delivery Instructions</a>
+specifying that it be sent back to the originating router as an acknowledgement.
+This is similar to the "reply block" or "reply onion"
+described in the references.
+It is used for determining the success or failure of end to end message delivery.
+The originating router may, upon failure to receive the Delivery Status Message
+within the expected time period, modify the routing to the far-end Destination,
+or take other actions.
+
+</li><li>
+A
+<a href="i2np.html#msg_DatabaseStore">Database Store Message</a>,
+containing a
+<a href="common_structures_spec#struct_LeaseSet">LeaseSet</a>
+for the originating Destnation, with
+<a href="tunnel_message_spec.html#delivery">Delivery Instructions</a>
+specifying the far-end destination's router.
+By periodically bundling a LeaseSet, the router ensures that the far-end will be able
+to maintain communications.
+Otherwise the far-end would have to query a floodfill router for the network database entry,
+and all LeaseSets would have to be published to the network database, as explained on the
+<a href="how_networkdatabase.html">network database page</a>.
+</li></ol>
+
+</p><p>
+In the current implementation, the Delivery Status and Database Store Messages
+are bundled when the local LeaseSet changes, when additional
+<a href="common_structures_spec#type_SessionTag">Session Tags</a>
+are delivered, or if the messages have not been bundled in the previous minute.
+
+</p><p>
+Obviously, the additional messages are currently bundled for specific purposes,
+and not part of a general-purpose routing scheme.
+</p>
+
+<h3> Storage to the Floodfill Network Database</h3>
+</p>
+As explained on the
+<a href="how_networkdatabase.html#delivery">network database page</a>,
+local
+<a href="common_structures_spec#struct_LeaseSet">LeaseSets</a>
+are sent to floodfill routers in a
+<a href="i2np.html#msg_DatabaseStore">Database Store Message</a>
+wrapped in a
+<a href="i2np.html#msg_Garlic">Garlic Message</a>
+so it is not visible to the tunnel's outbound gateway.
+</p>
+
+
+<H2>Future Work</H2>
+<p>
+The Garlic Message mechanism is very flexible and provides a structure for
+implementing many types of mixnet delivery methods.
+Together with the unused delay option in the
+<a href="tunnel_message_spec.html#delivery">tunnel message Delivery Instructions</a>,
+a wide spectrum of batching, delay, mixing, and routing strategies are possible.
+</p><p>
+In particular, there is potential for much more flexibility at the outbound tunnel endpoint.
+Messages could possibly be routed from there to one of several tunnels
+(thus minimizing point-to-point connections), or multicast to several tunnels
+for redundancy, or streaming audio and video.
+</p><p>
+Such experiments may conflict with the need to ensure security and anonymity, such
+as limiting certain routing paths, restricting the types of I2NP messages that may
+be forwarded along various paths, and enforcing certain message expiration times.
+</p><p>
+As a part of
+<a href="how_elgamalaes">ElGamal/AES encryption</a>,
+a garlic message contains a sender
+specified amount of padding data, allowing the sender to take active countermeasures 
+against traffic analysis.
+This is not currently used, beyond the requirement to pad to a multiple of 16 bytes.
+</p><p>
+Encryption of additional messages to and from the
+<a href="how_networkdatabase.html#delivery">floodfill routers</a>.
+</p>
+
+
+
 
 <H2>References</H2>
+<ul><li>
+The term garlic routing was first coined in Roger Dingledine's Free Haven 
+<a href="http://www.freehaven.net/papers.html">Master's thesis</a> (June 2000),
+see Section 8.1.1 authored by
+<a href="http://www.cs.princeton.edu/~mfreed/">Michael J. Freedman</a>.
+</li><li>
+<a href="http://www.onion-router.net/Publications.html">Onion router publications</a>
+</li><li>
+<a href="http://en.wikipedia.org/wiki/Onion_routing">Onion Routing on Wikipedia</a>
+</li><li>
+<a href="http://en.wikipedia.org/wiki/Garlic_routing">Garlic Routing on Wikipedia</a>
+</li><li>
+<a href="meeting58.html#delivery">I2P Meeting 58</a> (2003) discussing the implementation of garlic routing
+</li><li>
+<a href="https://www.torproject.org/">Tor</a>
+</li><li>
+<a href="http://freehaven.net/anonbib/topic.html">Free Haven publications</a>
+</li><li>
+Onion routing was first described in <a href="http://www.onion-router.net/Publications/IH-1996.pdf">Hiding Routing Information</a>
+by David M. Goldschlag, Michael G. Reed, and Paul F. Syverson in 1996.
+</li></ul>
 
-<p>
-The term garlic routing was first coined by Michael Freedman in Roger Dingledine's Free Haven 
-<a href="http://www.freehaven.net/papers.html">Master's thesis</a> (June 2000), which was derived from 
-<a href="http://onion-router.net/">Onion Routing</a>.  The main difference
-from the method described by Freedman with I2P's garlic routing
-is that the path is unidirectional - there is no "turning point" as seen in onion routing
-or mixmaster reply blocks, which greatly simplifies the algorithm and allows for more flexible
-and reliable delivery.{% endblock %}
+{% endblock %}
diff --git a/www.i2p2/pages/how_networkdatabase.html b/www.i2p2/pages/how_networkdatabase.html
index 034e98dd..71b801d7 100644
--- a/www.i2p2/pages/how_networkdatabase.html
+++ b/www.i2p2/pages/how_networkdatabase.html
@@ -1,5 +1,5 @@
 {% extends "_layout.html" %}
-{% block title %}How the Network Database (netDb) Works{% endblock %}
+{% block title %}The Network Database{% endblock %}
 {% block content %}
 
 <p>
@@ -411,7 +411,7 @@
 </p>
 
 <p>
-  Queries are sent through<i>multiple routes simultaneously</i>
+  Queries are sent through <i>multiple routes simultaneously</i>
   to <i>reduce the chance of query failure</i>.
 </p>
 
@@ -482,7 +482,7 @@
 
 <p>
   Destinations may be hosted on multiple routers simultaneously, by using the same
-  private and public keys (traditionally named eepPriv.dat files).
+  private and public keys (traditionally stored in eepPriv.dat files).
   As both instances will periodically publish their signed LeaseSets to the floodfill peers,
   the most recently published LeaseSet will be returned to a peer requesting a database lookup.
   As LeaseSets have (at most) a 10 minute lifetime, should a particular instance go down,
@@ -566,7 +566,7 @@
   metrics described above, this is a difficult scenario to handle.
   Tor's response can be much more nimble in the relay case, as the suspicious relays
   can be manually removed from the consensus.
-  Some possible responses in the I2P case, none of them satisfactory:
+  Some possible responses for the I2P network are listed below, however none of them is completely satisfactory:
 </p>
 <ul>
   <li>Compile a list of bad router hashes or IPs, and announce the list through various means
@@ -611,11 +611,11 @@ This attack becomes more difficult as the network size grows.
 <p>
   As a partial defense against this attack,
   the algorithm used to determine Kademlia "closeness" varies over time.
-  Rather than using the Hash of the key (i.e. H(k))to determine closeness,
+  Rather than using the Hash of the key (i.e. H(k)) to determine closeness,
   we use the Hash of the key appended with the current date string, i.e. H(k + YYYYMMDD).
   A function called the "routing key generator" does this, which transforms the original key into a "routing key".
   In other words, the entire netdb keyspace "rotates" every day at UTC midnight.
-  Any partial-keyspace attack would have to be regenerated every day, as
+  Any partial-keyspace attack would have to be regenerated every day, for
   after the rotation, the attacking routers would no longer be close
   to the target key, or to each other.
 </p>
diff --git a/www.i2p2/pages/how_peerselection.html b/www.i2p2/pages/how_peerselection.html
index 0a5870ce..16968718 100644
--- a/www.i2p2/pages/how_peerselection.html
+++ b/www.i2p2/pages/how_peerselection.html
@@ -90,7 +90,7 @@ send or receive on a single tunnel through the peer in a minute.  For this estim
 performance in the previous minute.
 </p>
 
-<h3>Capacity</h3>
+<h3 id="capacity">Capacity</h3>
 
 <p>The capacity calculation
 simply goes through the profile and estimates how many tunnels the peer
diff --git a/www.i2p2/pages/how_tunnelrouting.html b/www.i2p2/pages/how_tunnelrouting.html
index f30185d4..fd720203 100644
--- a/www.i2p2/pages/how_tunnelrouting.html
+++ b/www.i2p2/pages/how_tunnelrouting.html
@@ -1,22 +1,35 @@
 {% extends "_layout.html" %}
-{% block title %}How Tunnel Routing Works{% endblock %}
-{% block content %}<i>Note: these documents have not yet been updated to include the changes made
-in I2P 0.5 - the new 
-<a href="tunnel-alt.html">tunnel 
-routing and encryption</a> algorithms, addressing <a href="todo#tunnelId">several</a>
-<a href="todo#tunnelLength">issues</a> (with the groundwork for addressing
-<a href="todo#ordering">others</a>).</i>
+{% block title %}Tunnel Overview{% endblock %}
+{% block content %}
+<p>
+Updated August 2010 for release 0.8
+</p>
 
-<p>As briefly explained in the <a href="how_intro">intro</a>, I2P builds virtual "tunnels" -
+<h2>Tunnel Overview</h2>
+<p>
+This page contains an overview of I2P tunnel terminology and operation, with
+links to more technical pages, details, and specifications.
+</p>
+<p>As briefly explained in the <a href="how_intro">introduction</a>, I2P builds virtual "tunnels" -
 temporary and unidirectional paths through a sequence of routers.  These 
-tunnels can be categorized as either inbound tunnels (where everything 
-given to it goes towards the creator of the tunnel) and outbound tunnels
+tunnels are classified as either inbound tunnels (where everything 
+given to it goes towards the creator of the tunnel) or outbound tunnels
 (where the tunnel creator shoves messages away from them).  When Alice
 wants to send a message to Bob, she will (typically) send it out one of
 her existing outbound tunnels with instructions for that tunnel's endpoint
 to forward it to the gateway router for one of Bob's current inbound 
 tunnels, which in turn passes it to Bob.</p>
+<p><center>
 <img src="/_static/images/tunnelSending.png" alt="Tunnel" />
+<pre>
+A: Outbound Gateway (Alice)
+B: Outbound Participant
+C: Outbound Endpoint
+D: Inbound Gateway
+E: Inbound Participant
+F: Inbound Endpoint (Bob)
+</pre>
+</center></p>
 
 <h2>Tunnel vocabulary</h2>
 <ul>
@@ -32,77 +45,105 @@ tunnels, which in turn passes it to Bob.</p>
 			<li><b>0-hop tunnel</b> - a tunnel where the gateway is also the endpoint</li>
 			<li><b>1-hop tunnel</b> - a tunnel where the gateway talks directly to the
 				endpoint</li>
-			<li><b>2-(or more)-hop tunnel</b> - a tunnel where there is at least one
+			<li><b>2-(or more)-hop tunnel</b> - a tunnel where there is at least one intermediate
 				tunnel participant. (the above diagram includes two 2-hop tunnels - one
 				outbound from Alice, one inbound to Bob)</li>
 		</ul>
 	</li>
-	<li class="gap"><b>Tunnel lifetime</b> - how long a particular tunnel is
-		supposed to be in operation for (each client specifies this when contacting
-		their router, and the router makes sure sufficient tunnels meeting that
-		criteria are built)</li>
+	<li class="gap"><b>Tunnel ID</b> - A <a href="common_structures_spec.html#type_TunnelId">4 byte integer</a>
+                 different for each hop in a tunnel, and unique among all tunnels on a router.
+                 Chosen randomly by the tunnel creator.</li>
 </ul>
 
-<h2>Tunnel information</h2>
-<p>Routers performing the three roles (gateway, endpoint, participant) are given
-different pieces of data to accomplish their tasks:</p>
+<h2>Tunnel Build Information</h2>
+<p>Routers performing the three roles (gateway, participant, endpoint) are given
+different pieces of data in the initial
+<a href="tunnel-alt-creation.html">Tunnel Build Message</a>
+to accomplish their tasks:</p>
 
 <ul>
 	<li class="gap"><b>The tunnel gateway gets:</b>
 		<ul>
-			<li><b>tunnel signing key</b> - a DSA private key for authenticating
-				messages sent down the tunnel</li>
-			<li><b>tunnel encryption key</b> - an AES private key for encrypting
-				messages and instructions to the endpoint</li>
-			<li><b>tunnel id</b> - 4 byte integer (each router can obviously only have
-				one tunnel with each tunnel id at any time)</li>
-			<li><b>next hop [optional]</b> - what router is the next one in the path</li>
-			<li><b>configuration key</b> - an AES private key used by the tunnel's
-				creator for updating the tunnel later on (if necessary)</li>
+			<li><b>tunnel encryption key</b> - an <a href="common_structures_spec.html#type_SessionKey">AES private key</a> for encrypting
+				messages and instructions to the next hop</li>
+			<li><b>tunnel IV key</b> - an <a href="common_structures_spec.html#type_SessionKey">AES private key</a> for double-encrypting
+				the IV to the next hop</li>
+			<li><b>reply key</b> - an <a href="common_structures_spec.html#type_SessionKey">AES public key</a> for encrypting
+				the reply to the tunnel build request</li>
+			<li><b>reply IV</b> - the IV for encrypting
+				the reply to the tunnel build request</li>
+			<li><b>tunnel id</b> - 4 byte integer (inbound gateways only)
+				</li>
+			<li><b>next hop</b> - what router is the next one in the path (unless this is a 0-hop tunnel, and the gateway is also the endpoint)</li>
+			<li><b>next tunnel id</b> - The tunnel ID on the next hop</li>
+		</ul>
+	</li>
+	<li class="gap"><b>All intermediate tunnel participants get:</b>
+		<ul>
+			<li><b>tunnel encryption key</b> - an <a href="common_structures_spec.html#type_SessionKey">AES private key</a> for encrypting
+				messages and instructions to the next hop</li>
+			<li><b>tunnel IV key</b> - an <a href="common_structures_spec.html#type_SessionKey">AES private key</a> for double-encrypting
+				the IV to the next hop</li>
+			<li><b>reply key</b> - an <a href="common_structures_spec.html#type_SessionKey">AES public key</a> for encrypting
+				the reply to the tunnel build request</li>
+			<li><b>reply IV</b> - the IV for encrypting
+				the reply to the tunnel build request</li>
+			<li><b>tunnel id</b> - 4 byte integer
+				</li>
+			<li><b>next hop</b> - what router is the next one in the path</li>
+			<li><b>next tunnel id</b> - The tunnel ID on the next hop</li>
 		</ul>
 	</li>
 	<li class="gap"> <b>The tunnel endpoint gets:</b>
 		<ul>
-			<li><b>tunnel verification key</b> - a DSA public key for authenticating
-				messages sent down the tunnel</li>
-			<li><b>tunnel encryption key</b> - an AES private key for decrypting
-				messages and instructions sent by the gateway</li>
-			<li><b>tunnel id</b> - 4 byte integer (each router can obviously only have
-				one tunnel with each tunnel id at any time)</li>
-			<li><b>configuration key</b> - an AES private key used by the tunnel's
-				creator for updating the tunnel later on (if necessary)</li>
-		</ul>
-	</li>
-	<li class="gap"><b>All tunnel participants get:</b>
-		<ul>
-			<li><b>tunnel verification key</b> - a DSA public key for authenticating
-				messages sent down the tunnel</li>
-			<li><b>tunnel id</b> - 4 byte integer (each router can obviously only have
-				one tunnel with each tunnel id at any time)</li>
-			<li><b>next hop [optional]</b> - what router is the next one in the path</li>
-			<li><b>configuration key</b> - an AES private key used by the tunnel's
-				creator for updating the tunnel later on (if necessary)</li>
+			<li><b>tunnel encryption key</b> - an <a href="common_structures_spec.html#type_SessionKey">AES private key</a> for encrypting
+				messages and instructions to the the endpoint (itself)</li>
+			<li><b>tunnel IV key</b> - an <a href="common_structures_spec.html#type_SessionKey">AES private key</a> for double-encrypting
+				the IV to the endpoint (itself)</li>
+			<li><b>reply key</b> - an <a href="common_structures_spec.html#type_SessionKey">AES public key</a> for encrypting
+				the reply to the tunnel build request (outbound endpoints only)</li>
+			<li><b>reply IV</b> - the IV for encrypting
+				the reply to the tunnel build request (outbound endpoints only)</li>
+			<li><b>tunnel id</b> - 4 byte integer (outbound endpoints only)
+				</li>
+			<li><b>reply router</b> - the inbound gateway of the tunnel to send the reply through (outbound endpoints only)</li>
+			<li><b>reply tunnel id</b> - The tunnel ID of the reply router (outbound endpoints only)</li>
 		</ul>
 	</li>
 </ul>
 
-<p>In addition, there are a series of options that the creator of a tunnel sends
-when requesting a router to join a tunnel, such as the expiration date. In I2P
-3.0, options specifying the pooling, mixing, and chaff generation settings will
-be honored, and limits on the quantity and size of messages allowed during the
-tunnel's lifetime will be implemented earlier (e.g. no more than 300 messages or
-1MB per minute).</p>
+<p>
+Details are in the
+<a href="tunnel-alt-creation.html">tunnel creation specification</a>.
+</p>
 
-<h2>Tunnel length</h2>
+<h2>Tunnel pooling</h2>
+<p>
+Several tunnels for a particular purpose may be grouped into a "tunnel pool",
+as described in the
+<a href="tunnel-alt.html#tunnel.pooling">tunnel specification</a>.
+This provides redundancy and additional bandwidth.
+The pools used by the router itself are called "exploratory tunnels".
+The pools used by applications are called "client tunnels".
+</p>
+
+
+
+<h2 id="length">Tunnel length</h2>
 <p>As mentioned above, each client requests that their router provide tunnels to
-include at least a certain number of hops (plus other criteria that aren't
-honored yet, such as bandwidth limits, etc). The decision as to how many routers
+include at least a certain number of hops.
+The decision as to how many routers
 to have in one's outbound and inbound tunnels has an important effect upon the
 latency, throughput, reliability, and anonymity provided by I2P - the more peers
 that messages have to go through, the longer it takes to get there and the more
 likely that one of those routers will fail prematurely.  The less routers in a
 tunnel, the easier it is for an adversary to mount traffic analysis attacks and
-pierce someone's anonymity.</p>
+pierce someone's anonymity.
+Tunnel lengths are specified by clients via
+<a href="i2cp.html#options">I2CP options</a>.
+The maximum number of hops in a tunnel is 7.
+</p>
+
 
 <h3>0-hop tunnels</h3>
 <p>With no remote routers in a tunnel, the user has very basic plausible
@@ -121,54 +162,92 @@ if the adversary ran a sufficient number of routers such that the single remote
 router in the tunnel is often one of those compromised ones, they would be able
 to mount the above statistical traffic analysis attack.</p>
 
-<h3>2-hop (or more) tunnels</h3>
+<h3>2-hop tunnels</h3>
 <p>With two or more remote routers in a tunnel, the costs of mounting the traffic
-analysis attack increases, since all remote routers would have to be compromised
+analysis attack increases, since many remote routers would have to be compromised
 to mount it.</p>
 
-<p>The router will by default use <b>2-hop tunnels</b>, at least in the main
-distribution.  Prior to the 0.2.5 release, all tunnels were 1-hop by default.</p>
+<h3>3-hop (or more) tunnels</h3>
+To reduce the susceptibility to <a href="http://blog.torproject.org/blog/one-cell-enough">some attacks</a>,
+3 or more hops are recommended for the highest level of protection.
+<a href="http://blog.torproject.org/blog/one-cell-enough">recent studies</a>
+also conclude that more than 3 hops does not provide additional protection.
+
+
+<h3>Tunnel default lengths</h3>
+<p>The router uses 2-hop tunnels by default for its exploratory tunnels.
+Client tunnel defaults are set by the application, using
+<a href="i2cp.html#options">I2CP options</a>.
+Most applications use 2 or 3 hops as their default.
+</p>
+
 
-<h2>Tunnel pooling</h2>
-<p>[explain tunnel pools, how we keep a free inbound pool, an outbound pool, and
-a client inbound pool, and how the pools are refreshed every minute or so, using
-the router's default settings]</p>
 
 <h2>Tunnel testing</h2>
 <p>All tunnels are periodically tested by their creator by sending a
-DeliveryStatusMessage out the tunnel and bound for another inbound tunnel
-(testing both tunnels at once).  If either fails, both are marked as no longer
-functional, and if they were used for a client's inbound tunnel, a new leaseSet
-is created.  Other techniques can be used to test tunnels later on, such as
-garlic wrapping a number of tests into cloves, testing individual tunnel
-participants separately (and using the tunnel configuration key to update the
-next hop to work around failures), etc, but that is not implemented at the
-moment.
+DeliveryStatusMessage out an outbound tunnel and bound for another inbound tunnel
+(testing both tunnels at once).  If either fails a number of consecutive tests, it is marked as no longer
+functional. If it was used for a client's inbound tunnel, a new leaseSet
+is created.
+Tunnel test failures are also reflected in the
+<a href="how_peerselection.html#capacity">capacity rating in the peer profile</a>.
 </p>
 
+
 <h2>Tunnel creation</h2>
 <p>Tunnel creation is handled by <a href="how_garlicrouting">garlic routing</a>
-a TunnelCreateMessage to a router, requesting that they participate in the
+a Tunnel Build Message to a router, requesting that they participate in the
 tunnel (providing them with all of the appropriate information, as above, along
 with a certificate, which right now is a 'null' cert, but will support hashcash
-or other non-free certificates when necessary).  The message also includes a
-SourceRouteReplyBlock, which allows the router to encrypt their
-TunnelCreateStatusMessage into a SourceRouteReplyMessage, which is sent to
-another router (specified in the SourceRouteReplyBlock), who then decrypts the
-rest of the SourceRouteReplyBlock, reads out the delivery instructions contained
-therein, and forwards the TunnelCreateStatusMessage accordingly.  (the delivery
-instructions can specify delivery to a specific router or can point at a tunnel)
+or other non-free certificates when necessary).
+That router forwards the message to the next hop in the tunnel.
+Details are in the
+<a href="tunnel-alt-creation.html">tunnel creation specification</a>.
 </p>
 
-<h2>Issues/TODO</h2>
+
+<h2>Tunnel encryption</h2>
+<p>Multi-layer encryption is handled by <a href="how_garlicrouting">garlic encryption</a>
+of tunnel messages.
+Details are in the
+<a href="tunnel-alt.html">tunnel specification</a>.
+The IV of each hop is encrypted with a separate key as explained there.
+</p>
+
+
+<h2>Future Work</h2>
+<ul><li>
+Other tunnel test techniques could be used, such as
+garlic wrapping a number of tests into cloves, testing individual tunnel
+participants separately,
+etc.
+</li><li>
+Move to 3-hop exploratory tunnels defaults.
+</li><li>
+In a distant future release,
+options specifying the pooling, mixing, and chaff generation settings may be implemented.
+</li><li>
+In a distant future release,
+limits on the quantity and size of messages allowed during the
+tunnel's lifetime may be implemented (e.g. no more than 300 messages or
+1MB per minute).
+</li></ul>
+
+
+<h2>See Also</h2>
 <ul>
-	<li>We will assign unique tunnel IDs for each router in the tunnel, rather
-		than having a single ID across the whole tunnel.  this would make traffic
-		analysis even harder</li>
-	<li>Get rid of the sourceRouteBlock stuff</li>
-	<li>Should inbound tunnels that will be used by clients ever be used for
-		general messages (network database, etc), rather than being free for use until
-		its allocated?</li>
-	<li>I2P 3.0 tunnel mixing / pooling details</li>
-	<li>Tunnel throttling details</li>
-</ul>{% endblock %}
+<li>
+<a href="tunnel-alt.html">tunnel specification</a>
+</li><li>
+<a href="tunnel-alt-creation.html">tunnel creation specification</a>
+</li><li>
+<a href="tunnel_message_spec.html">tunnel message specification</a>
+</li><li>
+<a href="how_garlicrouting.html">garlic routing</a>
+</li><li>
+<a href="how_elgamalaes.html">ElGamal/AES+SessionTag</a>
+</li><li>
+<a href="i2cp.html#options">I2CP options</a>
+</li>
+</ul>
+{% endblock %}
diff --git a/www.i2p2/pages/i2np_spec.html b/www.i2p2/pages/i2np_spec.html
index 9c104272..94fc51c7 100644
--- a/www.i2p2/pages/i2np_spec.html
+++ b/www.i2p2/pages/i2np_spec.html
@@ -197,7 +197,7 @@ total length: 222
 
 encrypted:
 
-toPeer :: Hash
+toPeer :: First 16 bytes of the SHA-256 Hash of the peer's router identity
           length -> 16 bytes
 
 encrypted_data :: ElGamal-2048 encrypted data
diff --git a/www.i2p2/pages/ntcp.html b/www.i2p2/pages/ntcp.html
index 3552589c..bdb2b630 100644
--- a/www.i2p2/pages/ntcp.html
+++ b/www.i2p2/pages/ntcp.html
@@ -184,7 +184,7 @@ Unencrypted Contents:
 
   Y: 256 byte Y from Diffie Hellman
 
-  HXY:  SHA256 Hash(X concatentated with Y)
+  HXY:  SHA256 Hash(X concatenated with Y)
         (32 bytes)
 
   tsB: 4 byte timestamp (seconds since the epoch)
diff --git a/www.i2p2/pages/tunnel-alt.html b/www.i2p2/pages/tunnel-alt.html
index 2581d66c..80f99aba 100644
--- a/www.i2p2/pages/tunnel-alt.html
+++ b/www.i2p2/pages/tunnel-alt.html
@@ -48,6 +48,11 @@ the core I2P layer, there is an optional end to end streaming library
 available for client applications, exposing TCP-esque operation,
 including message reordering, retransmission, congestion control, etc.</p>
 
+<p>
+An overview of I2P terminology is
+<a href="how_tunnelrouting.html">on the tunnel overview page</a>.
+</p>
+
 <h2>2) <a name="tunnel.operation">Tunnel operation</a></h2>
 
 <p>Tunnel operation has four distinct processes, taken on by various 
@@ -72,7 +77,7 @@ peers, each hop's tunnel ID will change.</p>
 
 <p>A tunnel gateway's function is to fragment and pack
 <a href="i2np.html">I2NP messages</a> into fixed-size
-<a href="tunnel_message_specification.html">tunnel messages</a>
+<a href="tunnel_message_spec.html">tunnel messages</a>
 and encrypt the tunnel messages.
 Tunnel messages contain the following:
 
@@ -87,7 +92,7 @@ Tunnel messages contain the following:
 <p>
 
 Details are in the
-<a href="tunnel_message_specification.html">tunnel message specification</a>.
+<a href="tunnel_message_spec.html">tunnel message specification</a>.
 
 
 
@@ -286,9 +291,9 @@ lengths should be randomized, as
 well as any of the other settings allowed when configuring individual tunnels.
 Configuration options are specified on the <a href="i2cp.html">I2CP page</a>.
 
-<h3 id="length">Default Tunnel Lengths</h3>
+<h3 id="length">Tunnel Lengths and Defaults</h3>
 
-TODO
+<a href="how_tunnelrouting.html#length">On the tunnel overview page</a>.
 
 <h3 id="strategy">Anticipatory Build Strategy and Priority</h3>