timoreo/olm
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add spec for the authenticated encryption used by olm

Browse source
This commit is contained in:
Mark Haines 2015-08-11 18:13:26 +01:00
parent 447501bd57
commit 40e49ee173
1 changed files with 18 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
docs/olm.rst
View file

@ -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 :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 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 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:: .. math::
\begin{align} \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 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 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 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:: .. math::
\begin{align} \begin{align}
@ -224,6 +225,18 @@ Olm Authenticated Encryption
Version 1 Version 1
~~~~~~~~~ ~~~~~~~~~
Version 1 of Olm uses AES-256 in CBC mode for encryption and HMAC-SHA-256 for Version 1 of Olm uses AES-256 in CBC mode with PCKS#7 padding for encryption
authentication. The 256 bit AES key, 256 bit HMAC key, and 128 bit AES IV are and HMAC-SHA-256 for authentication. The 256 bit AES key, 256 bit HMAC key,
derived from the message key using HKDF. 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}