Document the pre-key messages

1 files changed, 42 insertions, 6 deletions

diff --git a/docs/olm.rst b/docs/olm.rst
index 8f1c612..30d2146 100644
--- a/docs/olm.rst
+++ b/docs/olm.rst
@@ -33,8 +33,8 @@ Curve25519 inputs: the previous ratchet key, :math:`T_{i-1}`, and the current
 ratchet key :math:`T_i`. The even ratchet keys are generated by Alice.
 The odd ratchet keys are generated by Bob. A shared secret is generated
 using Diffie-Hellman on the ratchet keys. The next root key, :math:`R_i`, and
-chain key, :math:`C_{i,0}`, are derived from the shared secret using an
-HMAC-based Key Derivation Function (HKDF) using :math:`R_{i-1}` as the salt.
+chain key, :math:`C_{i,0}`, are derived from the shared secret using an HKDF
+using :math:`R_{i-1}` as the salt.
 
 .. math::
     \begin{align}
@@ -151,7 +151,6 @@ process so that they can decode out of order messages. If the receiver created
 a new receiver chain then they discard their current sender chain so that
 they will create a new chain when they next send a message.
 
-
 The Olm Message Format
 ----------------------
 
@@ -161,13 +160,14 @@ Normal Messages
 Olm messages start with a one byte version followed by a variable length
 payload followed by a fixed length message authentication code.
 
-
 .. code::
 
    +--------------+------------------------------------+-----------+
    | Version Byte | Payload Bytes                      | MAC Bytes |
    +--------------+------------------------------------+-----------+
 
+The version byte is ``"\x01"``.
+
 The payload consists of key-value pairs where the keys are integers and the
 values are integers and strings. The keys are encoded as a variable length
 integer tag where the 3 lowest bits indicates the type of the value:
@@ -184,10 +184,46 @@ significant bits are stored in the first byte.
 =========== ===== ======== ================================================
     Name     Tag    Type                     Meaning
 =========== ===== ======== ================================================
-Chain-Index  0x0A Integer  The chain index, :math:`j`, of the message
-Ratchet-Key  0x10 String   The ratchet key, :math:`T_{i}`, of the message
+Ratchet-Key  0x0A String   The ratchet key, :math:`T_{i}`, of the message
+Chain-Index  0x10 Integer  The chain index, :math:`j`, of the message
 Cipher-Text  0x22 String   The cipher-text, :math:`X_{i,j}`, of the message
 =========== ===== ======== ================================================
 
+The length of the MAC is determined by the authenticated encryption algorithm
+being used. The MAC protects all of the bytes preceeding the MAC.
+
+Pre-Key Messages
+~~~~~~~~~~~~~~~~
+
+Olm pre-key messages start with a one byte version followed by a variable
+length payload.
+
+.. code::
+
+   +--------------+------------------------------------+
+   | Version Byte | Payload Bytes                      |
+   +--------------+------------------------------------+
+
+The version byte is ``"\x01"``.
+
+The payload uses the same key-value format as for normal messages.
+
+============ ===== ======== ================================================
+    Name      Tag    Type                     Meaning
+============ ===== ======== ================================================
+One-Time-Key  0x0A String   Bob's single-use key, :math:`E_b`.
+Base-Key      0x12 String   Alice's single-use key, :math:`E_a`.
+Identity-Key  0x1A String   Alice's identity key, :math:`I_a`.
+Message       0x22 String   An embedded Olm message with its own version and
+                            MAC.
+============ ===== ======== ================================================
+
+Olm Authenticated Encryption
+----------------------------
 
+Version 1
+~~~~~~~~~
 
+Version 1 of Olm uses AES-256 in CBC mode for encryption and HMAC-SHA-256 for
+authentication. The 256 bit AES key, 256 bit HMAC key, and 128 bit AES IV are
+derived from the message key using HKDF.