From be9d74063d5b05e7debe5ad832681c4807f38d24 Mon Sep 17 00:00:00 2001
From: Mark Haines <mark.haines@matrix.org>
Date: Tue, 18 Aug 2015 14:33:40 +0100
Subject: [PATCH] Add some links to the spec for the various primitives being
 used.

---
 docs/olm.rst | 44 +++++++++++++++++++++++++++-----------------
 1 file changed, 27 insertions(+), 17 deletions(-)

diff --git a/docs/olm.rst b/docs/olm.rst
index 78c9731..1331a00 100644
--- a/docs/olm.rst
+++ b/docs/olm.rst
@@ -11,13 +11,13 @@ The Olm Algorithm
 Initial setup
 ~~~~~~~~~~~~~
 
-The setup takes four Curve25519 inputs: Identity keys for Alice and Bob,
+The setup takes four Curve25519_ inputs: Identity keys for Alice and Bob,
 :math:`I_A` and :math:`I_B`, and emphemeral keys for Alice and Bob,
 :math:`E_A` and :math:`E_B`. A shared secret, :math:`S`, is generated using
-Triple Diffie-Hellman. The initial 256 bit root key, :math:`R_0`, and 256 bit
-chain key, :math:`C_{0,0}`, are derived from the shared secret using an
-HMAC-based Key Derivation Function (HKDF) with default salt and ``"OLM_ROOT"``
-as the info.
+`Triple Diffie-Hellman`_. The initial 256 bit root key, :math:`R_0`, and 256
+bit chain key, :math:`C_{0,0}`, are derived from the shared secret using an
+HMAC-based Key Derivation Function using SHA-256_ as the hash function
+(HKDF-SHA-256_) with default salt and ``"OLM_ROOT"`` as the info.
 
 .. math::
     \begin{align}
@@ -34,8 +34,9 @@ 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 HKDF
-using :math:`R_{i-1}` as the salt and ``"OLM_RATCHET"`` as the info.
+chain key, :math:`C_{i,0}`, are derived from the shared secret using
+HKDF-SHA-256_ using :math:`R_{i-1}` as the salt and ``"OLM_RATCHET"`` as the
+info.
 
 .. math::
     \begin{align}
@@ -51,8 +52,8 @@ Advancing the chain key
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Advancing a root key takes the previous chain key, :math:`C_{i,j-i}`. The next
-chain key, :math:`C_{i,j}`, is the HMAC of ``"\x02"`` using the previous chain
-key as the key.
+chain key, :math:`C_{i,j}`, is the HMAC-SHA-256_ of ``"\x02"`` using the
+previous chain key as the key.
 
 .. math::
      \begin{align}
@@ -63,9 +64,9 @@ Creating a message key
 ~~~~~~~~~~~~~~~~~~~~~~
 
 Creating a message key takes the current chain key, :math:`C_{i,j}`. The
-message key, :math:`M_{i,j}`, is the HMAC of ``"\x01"`` using the current
-chain key as the key. The message keys where :math:`i` is even are used by
-Alice to encrypt messages. The message keys where :math:`i` is odd are used
+message key, :math:`M_{i,j}`, is the HMAC-SHA-256_ of ``"\x01"`` using the
+current chain key as the key. The message keys where :math:`i` is even are used
+by Alice to encrypt messages. The message keys where :math:`i` is odd are used
 by Bob to encrypt messages.
 
 .. math::
@@ -225,18 +226,27 @@ Olm Authenticated Encryption
 Version 1
 ~~~~~~~~~
 
-Version 1 of Olm uses AES-256 in CBC mode with PCKS#7 padding for encryption
+Version 1 of Olm uses AES-256_ in CBC_ mode with `PCKS#7`_ padding 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-SHA-256 using
 the default salt and an info of ``"OLM_KEYS"``.
 
-First the plain-text, :math:`P_{i,j}`, is encrypted to get the cipher-text
-:math:`X_{i,j}`. Then the entire message, both the headers and cipher-text,
-are HMAC'd and the MAC is appended to the message.
+First the plain-text is encrypted to get the cipher-text, :math:`X_{i,j}`.
+Then the entire message, both the headers and cipher-text, are HMAC'd and the
+MAC is appended to the message.
 
 .. math::
 
     \begin{align}
     AES\_KEY_{i,j}\;\parallel\;HMAC\_KEY_{i,j}\;\parallel\;AES\_IV_{i,j}
-        &= HKDF\left(M_{i,j},\,\text{"OLM\_RATCHET"}\right) \\
+        &= HKDF\left(M_{i,j},\,\text{"OLM\_KEYS"}\right) \\
     \end{align}
+
+.. _`Curve25519`: http://cr.yp.to/ecdh.html
+.. _`Triple Diffie-Hellman`: https://whispersystems.org/blog/simplifying-otr-deniability/
+.. _`HKDF-SHA-256`: https://tools.ietf.org/html/rfc5869
+.. _`HMAC-SHA-256`: https://tools.ietf.org/html/rfc2104
+.. _`SHA-256`: https://tools.ietf.org/html/rfc6234
+.. _`AES-256`: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
+.. _`CBC`: http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
+.. _`PCKS#7`: https://tools.ietf.org/html/rfc2315