aboutsummaryrefslogtreecommitdiff
path: root/docs/olm.rst
diff options
context:
space:
mode:
authorMark Haines <mark.haines@matrix.org>2015-08-11 18:13:26 +0100
committerMark Haines <mark.haines@matrix.org>2015-08-11 18:13:26 +0100
commit40e49ee173bd711fcb15c517549597bced3d0210 (patch)
tree8d29cc8c276e298bd3fe79ec81fd2e1b5b7f6e0c /docs/olm.rst
parent447501bd576f25263f8c741f1fd75a54aff90292 (diff)
Add spec for the authenticated encryption used by olm
Diffstat (limited to 'docs/olm.rst')
-rw-r--r--docs/olm.rst23
1 files changed, 18 insertions, 5 deletions
diff --git a/docs/olm.rst b/docs/olm.rst
index 30d2146..78c9731 100644
--- a/docs/olm.rst
+++ b/docs/olm.rst
@@ -16,7 +16,8 @@ The setup takes four Curve25519 inputs: Identity 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.
+HMAC-based Key Derivation Function (HKDF) with default salt and ``"OLM_ROOT"``
+as the info.
.. math::
\begin{align}
@@ -34,7 +35,7 @@ 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.
+using :math:`R_{i-1}` as the salt and ``"OLM_RATCHET"`` as the info.
.. math::
\begin{align}
@@ -224,6 +225,18 @@ 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.
+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.
+
+.. 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) \\
+ \end{align}