Skip to content
Snippets Groups Projects
Commit be9d7406 authored by Mark Haines's avatar Mark Haines
Browse files

Add some links to the spec for the various primitives being used.

parent 40e49ee1
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 27 additions and 17 deletions
docs/olm.rst
+ 27
− 17
View file @ be9d7406
...@@ -11,13 +11,13 @@ The Olm Algorithm ...@@ -11,13 +11,13 @@ The Olm Algorithm
Initial setup 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:`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 :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
chain key, :math:`C_{0,0}`, are derived from the shared secret using an 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"`` HMAC-based Key Derivation Function using SHA-256_ as the hash function
as the info. (HKDF-SHA-256_) with default salt and ``"OLM_ROOT"`` as the info.
.. math:: .. math::
\begin{align} \begin{align}
...@@ -34,8 +34,9 @@ Curve25519 inputs: the previous ratchet key, :math:`T_{i-1}`, and the current ...@@ -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. 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
using :math:`R_{i-1}` as the salt and ``"OLM_RATCHET"`` as the info. HKDF-SHA-256_ using :math:`R_{i-1}` as the salt and ``"OLM_RATCHET"`` as the
info.
.. math:: .. math::
\begin{align} \begin{align}
...@@ -51,8 +52,8 @@ Advancing the chain key ...@@ -51,8 +52,8 @@ Advancing the chain key
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
Advancing a root key takes the previous chain key, :math:`C_{i,j-i}`. The next 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 chain key, :math:`C_{i,j}`, is the HMAC-SHA-256_ of ``"\x02"`` using the
key as the key. previous chain key as the key.
.. math:: .. math::
\begin{align} \begin{align}
...@@ -63,9 +64,9 @@ Creating a message key ...@@ -63,9 +64,9 @@ Creating a message key
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
Creating a message key takes the current chain key, :math:`C_{i,j}`. The 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 message key, :math:`M_{i,j}`, is the HMAC-SHA-256_ of ``"\x01"`` using the
chain key as the key. The message keys where :math:`i` is even are used by current chain key as the key. The message keys where :math:`i` is even are used
Alice to encrypt messages. The message keys where :math:`i` is odd are used by Alice to encrypt messages. The message keys where :math:`i` is odd are used
by Bob to encrypt messages. by Bob to encrypt messages.
.. math:: .. math::
...@@ -225,18 +226,27 @@ Olm Authenticated Encryption ...@@ -225,18 +226,27 @@ Olm Authenticated Encryption
Version 1 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 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 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"``. the default salt and an info of ``"OLM_KEYS"``.
First the plain-text, :math:`P_{i,j}`, is encrypted to get the cipher-text First the plain-text is encrypted to get the cipher-text, :math:`X_{i,j}`.
:math:`X_{i,j}`. Then the entire message, both the headers and cipher-text, Then the entire message, both the headers and cipher-text, are HMAC'd and the
are HMAC'd and the MAC is appended to the message. MAC is appended to the message.
.. math:: .. math::
\begin{align} \begin{align}
AES\_KEY_{i,j}\;\parallel\;HMAC\_KEY_{i,j}\;\parallel\;AES\_IV_{i,j} 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} \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
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment