diff options
| -rw-r--r-- | docs/olm.rst | 42 |
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). + + |