From 447501bd576f25263f8c741f1fd75a54aff90292 Mon Sep 17 00:00:00 2001
From: Mark Haines <mark.haines@matrix.org>
Date: Tue, 11 Aug 2015 13:12:51 +0100
Subject: [PATCH] Document the pre-key messages
---
docs/olm.rst | 48 ++++++++++++++++++++++++++++++++++++++++++------
1 file 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.
--
GitLab