diff --git a/www.i2p2/pages/how_cryptography.html b/www.i2p2/pages/how_cryptography.html
index 2b63e6a8237a68abe6720cebbe12f1b46e4bac4a..7af928f0e4f6b162bbe79ae9ec08d929b148b2dd 100644
--- a/www.i2p2/pages/how_cryptography.html
+++ b/www.i2p2/pages/how_cryptography.html
@@ -18,12 +18,21 @@ technique used in <a href="how_elgamalaes">ElGamal/AES+SessionTag</a> (but we're
<p>
ElGamal is used for asymmetric encryption.
+ElGamal is used in two places in I2P:
+<ul><li>
+To encrypt <a href="tunnel-alt-creation.html">Tunnel Build Messages</a>
+</li><li>
+For end-to-end encryption as a part of <a href="how_elgamalaes">ElGamal/AES+SessionTag</a>
+</li></ul>
+</p>
+
<p>
We use common primes for 2048 ElGamal encryption and decryption, as given by <a href="http://tools.ietf.org/html/rfc3526">IETF RFC-3526</a>.
We currently only use ElGamal to encrypt the IV and session key in a single block, followed by the
-AES encrypted payload using that key and IV. Specifically, the unencrypted ElGamal
-block is formatted (in network byte order):
+AES encrypted payload using that key and IV.
<p>
+The unencrypted ElGamal contains:
+</p>
<p>
<PRE>
+----+----+----+----+----+----+----+----+
@@ -42,11 +51,45 @@ block is formatted (in network byte order):
<p>
The H(data) is the SHA256 of the data that is encrypted in the ElGamal block,
and is preceded by a random nonzero byte. The data encrypted in the block
-can be up to 222 bytes long. See
-<a href="http://trac.i2p2.de/browser/core/java/src/net/i2p/crypto/ElGamalEngine.java?rev=85a542c53d910dffbf34cdcefb8a2faeee96adc4">the ElGamal code</a>.
+may be up to 222 bytes long.
+As the encrypted data may contain a substantial number of zeros if the
+cleartext is smaller than 222 bytes, it is recommended that higher layers pad
+the cleartext to 222 bytes with random data.
+Total length: typically 255 bytes.
+</p><p>
+The encrypted ElGamal contains:
+</p>
<p>
-ElGamal is never used on its own in I2P, but instead always as part of
-<a href="how_elgamalaes">ElGamal/AES+SessionTag</a>.
+<PRE>
+ +----+----+----+----+----+----+----+----+
+ | zero padding... | |
+ +----+----+----+--// ----+ +
+ | |
+ + +
+ | ElG encrypted part 1 |
+ ~ ~
+ | |
+ + +----+----+----+----+----+----+----+
+ | | zero padding... | |
+ +----+----+----+----+--// ----+ +
+ | |
+ + +
+ | ElG encrypted part 2 |
+ ~ ~
+ | |
+ + +----+----+----+----+----+----+
+ | +
+ +----+----+
+
+</PRE>
+Each encrypted part is prepended with zeros to a size of exactly 257 bytes.
+Total length: 514 bytes.
+In typical usage, higher layers pad the cleartext to 222 bytes,
+resulting in 257-byte encrypted parts,
+and there is no zero padding at this layer.
+</p><p>
+See
+<a href="http://trac.i2p2.de/browser/core/java/src/net/i2p/crypto/ElGamalEngine.java?rev=85a542c53d910dffbf34cdcefb8a2faeee96adc4">the ElGamal code</a>.
<p>
The shared prime is the
@@ -124,12 +167,36 @@ Two situations are possible:
2. For situations where we know the size of the data to be sent, we AES encrypt the following:
<p>
<PRE>
- |_______1_______2_______3_______4_______5_______6_______7_______8
- |H(data)
- |
- |
- | |
- | size of data (in bytes) | data ... | rand ... |
+ +----+----+----+----+----+----+----+----+
+ | H(data) |
+ + +
+ | |
+ + +
+ | |
+ + +
+ | |
+ +----+----+----+----+----+----+----+----+
+ | size | data ... |
+ +----+----+ +
+ | |
+ ~ ~
+ | |
+ + +
+ | |
+ + +----//---+----+
+ | | |
+ +----+----+----//---+----+ +
+ | Padding to 16 bytes |
+ +----+----+----+----+----+----+----+----+
+
+H(data): 32-byte SHA-256 Hash of the data
+
+size: 2-byte Integer, number of data bytes to follow
+
+data: payload
+
+padding: random data, to a multiple of 16 bytes
+
</PRE>
<p>
After the data comes an application specified number of randomly generated padding bytes.
diff --git a/www.i2p2/pages/how_elgamalaes.html b/www.i2p2/pages/how_elgamalaes.html
index 1e68a98df0a7747523b44d3324361ea73730f21f..3fdaff70f35714468d057cdd59298b21c0010a22 100644
--- a/www.i2p2/pages/how_elgamalaes.html
+++ b/www.i2p2/pages/how_elgamalaes.html
@@ -1,80 +1,294 @@
{% extends "_layout.html" %}
-{% block title %}How ElGamal and AES Encryption Work{% endblock %}
-{% block content %}<p>
-Within I2P, various messages are encrypted, but we don't want anyone to know
-to whom or from whom it is bound, so we can't just toss a "to" or "from" address.
-In addition, messages are not delivered in order (or reliably), so we can't simply
-ElGamal encrypt the first message and AES the subsequent messages. The alternative
-of ElGamal encrypting each individual message is daunting in light of the message
-frequency desired. Instead, we take each message and evaluate whether it fits into
-the three possible conditions:</p>
+{% block title %}ElGamal/AES + SessionTag Encryption{% endblock %}
+{% block content %}
+Updated August 2010, current as of router version 0.8
+<h2>Overview</h2>
+<p>
+ElGamal/AES+SessionTags is used for end-to-end encryption.
+</p>
+ <p> As an unreliable, unordered, message based system, I2P uses a simple combination
+ of asymmetric and symmetric encryption algorithms to provide data confidentiality
+ and integrity to garlic messages. As a whole, the combination is referred
+ to as ElGamal/AES+SessionTags, but that is an excessively verbose way to describe
+ the use of 2048bit ElGamal, AES256, SHA256, and 32 byte nonces. </p>
+ <p> The first time a router wants to encrypt a garlic message to another router,
+ they encrypt the keying material for an AES256 session key with ElGamal and
+ append the AES256/CBC encrypted payload after that encrypted ElGamal block.
+ In addition to the encrypted payload, the AES encrypted section contains the
+ payload length, the SHA256 hash of the unencrypted payload, as well as a number
+ of "session tags" - random 32 byte nonces. The next time the sender wants
+ to encrypt a garlic message to another router, rather than ElGamal encrypt
+ a new session key they simply pick one of the previously delivered session
+ tags and AES encrypt the payload like before, using the session key used with
+ that session tag, prepended with the session tag itself. When a router receives
+ a garlic encrypted message, they check the first 32 bytes to see if it matches
+ an available session tag - if it does, they simply AES decrypt the message,
+ but if it does not, they ElGamal decrypt the first block. </p>
+ <p> Each session tag can be used only once so as to prevent internal adversaries
+ from unnecessarily correlating different messages as being between the same
+ routers. The sender of an ElGamal/AES+SessionTag encrypted message chooses
+ when and how many tags to deliver, prestocking the recipient with enough tags
+ to cover a volley of messages. Garlic messages may detect the successful tag
+ delivery by bundling a small additional message as a clove (a "delivery status
+ message") - when the garlic message arrives at the intended recipient and
+ is decrypted successfully, this small delivery status message is one of the
+ cloves exposed and has instructions for the recipient to send the clove back
+ to the original sender (through an inbound tunnel, of course). When the original
+ sender receives this delivery status message, they know that the session tags
+ bundled in the garlic message were successfully delivered. </p>
+ <p> Session tags themselves have a short lifetime, after which they are
+ discarded if not used. In addition, the quantity stored for each key is limited,
+ as are the number of keys themselves - if too many arrive, either new or old
+ messages may be dropped. The sender keeps track whether messages using session
+ tags are getting through, and if there isn't sufficient communication it may
+ drop the ones previously assumed to be properly delivered, reverting back
+ to the full expensive ElGamal encryption.
+ A session will continue to exist until all its tags are exhausted or expire.
+</p><p>
+Sessions are unidirectional. Tags are delivered from Alice to Bob,
+and Alice then uses the tags, one by one, in subsequent messages to Bob.
+</p><p>
+Sessions may be established between Destinations, between Routers, or
+between a Router and a Destination.
+Each Router and Destination maintains its own Session Key Manager to
+keep track of Session Keys and Session Tags.
+Separate Session Key Managers prevents correlation of multiple Destinations
+to each other or a Router by adversaries.
+</p>
-<OL>
-<li> its ElGamal encrypted to us</li>
-<li> its AES encrypted to us</li>
-<li> its not encrypted to us</li>
-</OL>
+
+<h2>Message Reception</h2>
<p>
-If its ElGamal encrypted to us, the message is considered a new session, and
-is encrypted per encryptNewSession(...) in
-<a href="http://docs.i2p2.de/core/net/i2p/crypto/ElGamalAESEngine.html">[ElGamalAESEngine]</a>
-as follows -</p>
+Each message received has one of two
+the two possible conditions:</p>
+
+<OL>
+<li> It is part of an existing session and is AES encrypted</li>
+<li> It is for a new session and contains both ElGamal and AES encrypted blocks</li>
+</OL>
+When a router receives a message, it will first assume it is from
+an existing session and attempt to decrypt it using AES.
+If that fails, it will assume it is for a new session and attempt to
+decrypt it using ElGamal.
+</p>
-<p>An initial ElGamal block, encrypted <a href="how_cryptography">as before</a>:</p>
+
+<h2 id="new">New Session Message Specification</h2>
+<p>
+An ElGamal Message contains two parts, an encrypted ElGamal block
+and an encrypted AES block.
+</p><p>
+The encrypted message contains:
<PRE>
- |_______1_______2_______3_______4_______5_______6_______7_______8
- | 32 byte session key
- |
- |
- | |
- | 32 byte pre-IV (first 16 bytes of H(pre-IV) == IV)
- |
- |
- | |
- | (158 bytes of random data)
- | ...
- | |
-</PRE>
+ +----+----+----+----+----+----+----+----+
+ | |
+ + +
+ | ElGamal Encrypted Block |
+ ~ ~
+ | |
+ + +----+----+----+----+----+----+
+ | | |
+ +----+----+ +
+ | |
+ + +
+ | AES Encrypted Block |
+ ~ ~
+ | |
+ + +----+----+----+----+----+----+
+ | +
+ +----+----+
-<p>Followed by the following, AES encrypted <a href="how_cryptography">as before</a>,
-using the session key and IV from the header:</p>
+</PRE>
+</p>
+<h3>ElGamal Block</h3>
+<p>
+The ElGamal Block is always 514 bytes long.
+The AES Block is variable length but is always a multiple of 16 bytes.
+</p><p>
+The unencrypted ElGamal data is 222 bytes long, containing:
+<PRE>
+ +----+----+----+----+----+----+----+----+
+ | |
+ + +
+ | Session Key |
+ + +
+ | |
+ + +
+ | |
+ +----+----+----+----+----+----+----+----+
+ | |
+ + +
+ | Pre-IV |
+ + +
+ | |
+ + +
+ | |
+ +----+----+----+----+----+----+----+----+
+ + +
+ | |
+ + +
+ | 158 bytes random padding |
+ ~ ~
+ | |
+ + +----+----+
+ | |
+ +----+----+----+----+----+----+
+</PRE>
+The 32-byte Session Key is the identifier for the session.
+The 32-byte Pre-IV will be used to generate the IV for the AES block that follows;
+the IV is the first 16 bytes of the SHA-256 Hash of the Pre-IV.
+</p><p>
+The 222 byte payload is encrypted
+<a href="how_cryptography.html#elgamal">using ElGamal</a>
+and the encrypted block is 514 bytes long.
+</p>
+<h3 id="aes">AES Block</h3>
+<p>The unencrypted data in the AES block contains the following:
<PRE>
- |_______1_______2_______3_______4_______5_______6_______7_______8
- | # session tags| that many sessionTags (32 byte random numbers)
- | ...
- | | size of the payload (bytes) | H(payload)
- |
- |
- |
- | | flag |payload
- | ...
- | |
- | random bytes leaving the total AES block (size % 16 == 0) |
+ +----+----+----+----+----+----+----+----+
+ |tag count| |
+ +----+----+ +
+ | |
+ + +
+ | Session Tags |
+ ~ ~
+ | |
+ + +
+ | |
+ + +----+----+----+----+----+----+
+ | | payload size | |
+ +----+----+----+----+----+----+ +
+ | |
+ + +
+ | Payload Hash |
+ + +
+ | |
+ + +----+----+
+ | |flag| |
+ +----+----+----+----+----+----+----+ +
+ | |
+ + +
+ | New Session Key (opt.) |
+ + +
+ | |
+ + +----+
+ | | |
+ +----+----+----+----+----+----+----+ +
+ | |
+ + +
+ | Payload |
+ ~ ~
+ | |
+ + +----//---+----+
+ | | |
+ +----+----+----//---+----+ +
+ | Padding to 16 bytes |
+ +----+----+----+----+----+----+----+----+
+
+tag count: 2-byte <a href="common_structures_spec#type_Integer">Integer</a>, 0-200
+
+Session Tags: That many 32-byte <a href="common_structures_spec#type_SessionTag">Session Tags</a>
+
+payload size: 4-byte <a href="common_structures_spec#type_Integer">Integer</a>
+
+Payload Hash: The 32-byte SHA256 <a href="common_structures_spec#type_Hash">SHA256 Hash</a> of the payload
+
+flag: A one-byte value. Normally == 0. If == 0x01, a Session Key follows
+
+New Session Key: A 32-byte <a href="common_structures_spec#type_SessionKey">Session Key</a>,
+ to replace the old key, and is only present if preceding flag is 0x01
+
+Payload: the data
+
+Padding: Random data to a multiple of 16 bytes for the total length
</PRE>
-<p>If the flag is 0x01, it is followed by a new session key, replacing
-the old one.</p>
+</p><p>
+The data is then <a href="how_cryptography">AES Encrypted</a>,
+using the session key and IV (calculated from the pre-IV) from the ElGamal section.</p>
+
+<h2 id="existing">Existing Session Message Specification</h2>
<p>The session tags delivered successfully are remembered for a
-brief period (30 minutes currently) until they are used (and discarded).
-They are used by packaging in a message that is not preceded by an
-ElGamal block. Instead, it is encrypted per encryptExistingSession(...) in
-<a href="http://docs.i2p2.de/core/net/i2p/crypto/ElGamalAESEngine.html">[ElGamalAESEngine]</a>
-as follows -</p>
+brief period (15 minutes currently) until they are used or discarded.
+A tag is used by packaging one in an Existing Session Message that
+contains only an AES encrypted block, and
+ is not preceded by an
+ElGamal block.
+</p><p?>
+The existing session message is
+as follows:
<PRE>
- |_______1_______2_______3_______4_______5_______6_______7_______8
- | session tag (32 byte random number previously delivered and
- | not yet expired or used). the session tag also serves as
- | the pre-IV (the first 16 bytes of H(sessionTag) == IV)
- | |
+ +----+----+----+----+----+----+----+----+
+ | |
+ + +
+ | Session Tag |
+ + +
+ | |
+ + +
+ | |
+ +----+----+----+----+----+----+----+----+
+ | |
+ + +
+ | AES Encrypted Block |
+ ~ ~
+ | |
+ + +
+ | |
+ +----+----+----+----+----+----+----+----+
+
+Session Tag: A 32-byte <a href="common_structures_spec#type_SessionTag">Session Tag</a>
+ previously delivered in an AES block
+
+AES Encrypyted Block: As specified <a href="#aes">above</a>.
+
</PRE>
+The session tag also serves as
+the pre-IV. The IV is the first 16 bytes of the SHA-256 Hash of the sessionTag.
+</p><p>
+To decode a message from an existing session, a router looks up the Session Tag to find an
+associated Session Key. If the Session Tag is found, the AES block is decrypted using the associated Session Key.
+If the tag is not found, the message is assumed to be a <a href="#new">New Session Message</a>.
+</p>
+
+
+
+<h2 id="future">Future Work</h2>
+<p>
+There are many possible areas to tune the Session Key Manager's algorithms;
+some may interact with the streaming library behavior, or have significant
+impact on overal performance.
+<ul><li>
+Delivery of too many tags at one time may impose substantial overhead for brief streaming connections
+or datagrams, and increase the chance of message loss.
+</li><li>
+A few tags could be delivered in each of several messages, or lots of tags all at once.
+</li><li>
+The number of tags delivered could depend on message size, keeping in mind
+the eventual padding to 1KB at the tunnel message layer.
+</li><li>
+Clients could send an estimate of session lifetime to the router, as an advisory
+on the number of tags required.
+</li><li>
+Delivery of too few tags causes the router to fall back to an expensive ElGamal encryption.
+</li><li>
+The router may assume delivery of Session Tags, or await acknowledgement before using them;
+there are tradeoffs for each strategy.
+</li><li>
+For very brief messages, almost the full 222 bytes of the pre-IV and padding fields in the ElGamal block
+could be used for the entire message, instead of establishing a session.
+</li><li>
+Change from Session Tags to
+<a href="performance.html#prng">a synchronized PRNG</a>.
+</li></ul>
+
+</p>
+
+
-<p>Followed by the AES encrypted block above (2 byte # session tags,
-that many session tags, sizeof(payload), H(payload), flag, payload,
-random padding).</p>
{% endblock %}
diff --git a/www.i2p2/pages/how_threatmodel.html b/www.i2p2/pages/how_threatmodel.html
index 0fc3526426b380984b239674b84cdcc83baa20c7..78b77de0426f19bcf26e8501381a853f0bf702fd 100644
--- a/www.i2p2/pages/how_threatmodel.html
+++ b/www.i2p2/pages/how_threatmodel.html
@@ -230,6 +230,12 @@ this is only relevant for destinations that other people know about - a private
group whose destination is only known to trusted peers does not have to worry,
as an adversary can't "ping" them to mount the attack.</p>
+<p>Reference:
+<a href="http://blog.torproject.org/blog/one-cell-enough">One Cell Enough</a>
+</p>
+
+
+
<h3 id="dos">Denial of service attacks</h3>
<p>There are a whole slew of denial of service attacks available against I2P,
diff --git a/www.i2p2/pages/performance.html b/www.i2p2/pages/performance.html
index 07eacb77caad7e04a7e48f4237847a1ef9f7d691..c104206e1bdd09e1ee36d512966b9c750ed9599c 100644
--- a/www.i2p2/pages/performance.html
+++ b/www.i2p2/pages/performance.html
@@ -1,6 +1,8 @@
{% extends "_layout.html" %}
{% block title %}Performance{% endblock %}
{% block content %}
+Updated August 2010, current as of router version 0.8
+
<p>Probably one of the most frequent things people ask is "how fast is I2P?",
and no one seems to like the answer - "it depends". After trying out I2P, the
next thing they ask is "will it get faster?", and the answer to that is a most
@@ -33,7 +35,7 @@ gave us a reference to someone we had never heard of). We can also do some
tuning on what we actually send - how many peers we bounce back (or even if we
bounce back a reply), as well as how many concurrent searches we perform.</p>
-<h2>Longer SessionTag lifetime</h2>
+<h2>Session Tag Tuning and Improvements</h2>
<p>The way the <a href="how_elgamalaes">ElGamal/AES+SessionTag</a> algorithm
works is by managing a set of random one-time-use 32 byte arrays, and expiring
them if they aren't used quickly enough. If we expire them too soon, we're
@@ -44,8 +46,13 @@ tags, even more encryption failures may occur prior to detection). With some
more active detection and feedback driven algorithms, we can safely and more
efficiently tune the lifetime of the tags, replacing the ElGamal encryption with
a trivial AES operation.</p>
+<p>
+Additional ideas for improving Session Tag delivery are described on the
+<a href="how_elgamalaes.html#future">ElGamal/AES+SessionTag page</a>.
+</p>
-<h2>Migrate sessionTag to synchronized PRNG</h2>
+
+<h2 id="prng">Migrate sessionTag to synchronized PRNG</h2>
<p>Right now, our <a href="how_elgamalaes.html">ElGamal/AES+SessionTag</a>
algorithm works by tagging each encrypted message with a unique random
32 byte nonce (a "session tag"), identifying that message as being encrypted
@@ -76,13 +83,12 @@ network and CPU load (due to expensive tunnel creation messages).</p>
<p>
This appears to be an easy fix for high load on the big-bandwidth routers, but
we should not resort to it until we've tuned the tunnel building algorithms further.
-However, the 10 minute tunnel lifetime is hardcoded in a few places,
-so the code needs to be cleaned up before we could change the duration.
+However, the 10 minute tunnel lifetime is hardcoded in quite a few places,
+so substantial effort would be required to change the duration.
+Also, it would be difficult to maintain backward compatibility with such a change.
</p><p>
-A new tunnel build algorithm was introduced in release 0.6.1.32 and it has greatly
-reduced the number of tunnel builds. Together with better detection of
-unreachable peers and other peer selection strategies implemented in release 0.6.1.33,
-the situation is much improved, and there are no current plans to extend tunnel lifetime.
+Currently, since the network average tunnel build success rate is fairly high,
+there are no current plans to extend tunnel lifetime.
</p>
@@ -111,4 +117,8 @@ bandwidth, latency, and CPU usage.</p>
<li>Web controls and monitoring the health of the various streams, as well
as the ability to explicitly close or throttle them.</li>
</ul>
+<p>
+Additional ideas for improving the streaming library are described on the
+<a href="streaming.html#future">streaming library page</a>.
+</p>
{% endblock %}
diff --git a/www.i2p2/pages/streaming.html b/www.i2p2/pages/streaming.html
index 87f6dfa2ebd27154483621298c5cd4720805227e..b268591caa2f6097062b049b71996e4bd5d8640f 100644
--- a/www.i2p2/pages/streaming.html
+++ b/www.i2p2/pages/streaming.html
@@ -405,7 +405,7 @@ retransmitting lost messages, and the latency and overhead of multiple messages.
-<h2>Future Work</h2>
+<h2 id="future">Future Work</h2>
The behavior of the streaming library has a profound impact on
application-level performance, and as such, is an important
area for further analysis.