aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMark Haines <mark.haines@matrix.org>2015-08-04 18:09:44 +0100
committerMark Haines <mark.haines@matrix.org>2015-08-04 18:09:44 +0100
commit49c117c62eccf914fb7b12ac4a7c3973ac172513 (patch)
tree8d748e86f5cb6ca5f4bfcd5d7f8032f4810ad228
parent41a8fb61afacc57e6da2e2cb427ecdf889dcabdf (diff)
Start writing protocol spec for olm
-rw-r--r--docs/olm.rst42
1 files changed, 42 insertions, 0 deletions
diff --git a/docs/olm.rst b/docs/olm.rst
new file mode 100644
index 0000000..07836f6
--- /dev/null
+++ b/docs/olm.rst
@@ -0,0 +1,42 @@
+Olm: A Crytographic Ratchet
+===========================
+
+An implementation of the cryptographic ratchet described by
+https://github.com/trevp/axolotl/wiki.
+
+
+The Olm Algorithm
+-----------------
+
+.. figure:: Axolotl.svg
+
+
+Initial setup
+~~~~~~~~~~~~~
+
+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).
+
+.. math::
+ \begin{align}
+ S&=ECDH\left(I_A,\,E_B\right)\;\parallel\;ECDH\left(E_A,\,I_B\right)\;
+ \parallel\;ECDH\left(E_A,\,E_B\right)\\
+ R_0\;\parallel\;C_{0,0}&=HKDF(S,\,\text{"OLM\_ROOT"})
+ \end{align}
+
+Advancing the root key
+~~~~~~~~~~~~~~~~~~~~~~
+
+Advancing a root key takes the previous root key, :math:`R_{i-1}`, and two
+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, `S` is generated
+using Diffie-Hellman on the ratchet keys. The next root key, :math:`R_o`, and
+chain key, :math:`C_{i,0}`, are derived from the shared secret using an
+HMAC-based Key Derivation Function (HKDF).
+
+