prop. 144 updates

i2p2www/spec/proposals/144-ecies-x25519-aead-ratchet.rst

@@ -5,7 +5,7 @@ ECIES-X25519-AEAD-Ratchet
     :author: zzz, chisana
     :created: 2018-11-22
     :thread: http://zzz.i2p/topics/2639
-    :lastupdated: 2019-09-21
+    :lastupdated: 2019-09-24
     :status: Open
 
 .. contents::
@@ -694,7 +694,8 @@ or the two-way pattern "IK" (if the static key is sent).
 1b) New session format (with binding)
 -------------------------------------
 
-Encrypted:
+Length is 96 + payload length.
+Encrypted format:
 
 .. raw:: html
 
@@ -751,7 +752,8 @@ Encrypted:
 If no reply is required, no static key is sent.
 
 
-Encrypted:
+Length is 96 + payload length.
+Encrypted format:
 
 .. raw:: html
 
@@ -815,7 +817,8 @@ If only a single message is expected to be sent,
 no session setup or static key is required.
 
 
-Encrypted:
+Length is 96 + payload length.
+Encrypted format:
 
 .. raw:: html
 
@@ -1122,7 +1125,11 @@ This is the "ss" message pattern:
   // Save for New Session Reply KDF
   h = SHA256(h || ciphertext)
 
-  TODO tag = HKDF(...)
+  tagset = TAGSET.CREATE(chainKey, TODO, 1, session, isInbound = false)
+
+  tagsetEntry = tagset.GET_NEXT_ENTRY()
+
+  tag = tagsetEntry.SESSION_TAG
 
 {% endhighlight %}
 
@@ -1157,7 +1164,14 @@ chainKey = from Flags/Static key section
 1g) New Session Reply format
 ----------------------------
 
-Encrypted:
+The New Session Reply is in two parts.
+The first part is the completion of the Noise IK handshake with a prepended tag.
+The length of the first part is 56 bytes.
+The second part is the data phase payload.
+The length of the second part is 16 + payload length.
+
+Total length is 72 + payload length.
+Encrypted format:
 
 .. raw:: html
 
@@ -1646,6 +1660,75 @@ If a DH ratchet step isn't triggered, then the received N minus the length of th
 is the number of skipped messages in that chain.
 
 
+Recommended Implementation
+``````````````````````````
+
+We define the following data structures and functions to implement these ratchets.
+
+TAGSET_ENTRY
+    A single entry in a TAGSET.
+
+    INDEX
+        An integer index, starting with 0
+
+    SESSION_TAG
+        An identifier to go out on the wire, 8 bytes
+
+    SESSION_KEY
+        A symmetric key, never goes on the wire, 32 bytes
+
+TAGSET
+    A collection of TAGSET_ENTRIES.
+
+    CREATE(key, data, n, session, isOutgoing)
+        Generate a new TAGSET using initial cryptographic material key and data, both 32 bytes.
+        The associated session identifier is provided.
+        isOutgoing is true for an outgoing session, false for an incoming session.
+        The initial number of of tags to create is specified; this is generally 0 or 1
+        for an outgoing session.
+        LAST_INDEX = -1
+        EXTEND(n) is called.
+
+    EXTEND(n)
+        Generate n more TAGSET_ENTRIES by calling EXTEND() n times.
+
+    EXTEND()
+        Generate one more TAGSET_ENTRY.
+        ++ LAST_INDEX
+        Create a new TAGSET_ENTRY with the LAST_INDEX value and the calculated SESSION_TAG.
+        Calls RATCHET_TAG and (optionally) RATCHET_KEY.
+        For inbound sessions, the calculation of the SESSION_KEY may
+        be deferred and calculated in GET_SESSION_KEY().
+
+    RATCHET_TAG
+        Calculates the next SESSION_TAG based on the last SESSION_TAG.
+
+    RATCHET_KEY
+        Calculates the next SESSION_KEY based on the last SESSION_KEY.
+
+    SESSION
+        The associated session.
+
+    CREATION_TIME
+        When the TAGSET was created.
+
+    LAST_INDEX
+        The last TAGSET_ENTRY INDEX generated by EXTEND().
+
+    GET_NEXT_ENTRY()
+        Used for outgoing sessions only.
+        EXTEND(1) is called if there are no remaining TAGSET_ENTRIES.
+        Returns the next unused TAGSET_ENTRY.
+
+    GET_SESSION_KEY(sessionTag)
+        Used for incoming sessions only.
+        Returns the SESSION_KEY associated with the sessionTag.
+        If found, the associated TAGSET_ENTRY is removed.
+        If the SESSION_KEY calculation was deferred, it is calculated now.
+        If there are few TAGSET_ENTRIES remaining, EXTEND(n) is called.
+
+
+
 
 4a) DH Ratchet
 ``````````````
@@ -1709,6 +1792,9 @@ Issues
 KDF
 ~~~
 
+This is the definition of TAGSET.CREATE(key, data, n, session, isInbound).
+
+
 .. raw:: html
 
   {% highlight lang='text' %}
@@ -1813,6 +1899,8 @@ See the Message Number block definition.
 KDF
 ~~~
 
+This is the definition of RATCHET_TAG().
+
 .. raw:: html
 
   {% highlight lang='text' %}
@@ -1883,6 +1971,8 @@ This also provides some additional security, since the session tags go out on th
 KDF
 ~~~
 
+This is the definition of RATCHET_KEY().
+
 .. raw:: html
 
   {% highlight lang='text' %}