Add some links to the spec for the various primitives being used.
This commit is contained in:
parent
40e49ee173
commit
be9d74063d
1 changed files with 27 additions and 17 deletions
44
docs/olm.rst
44
docs/olm.rst
|
@ -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
|
||||||
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
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
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
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
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
|
||||||
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
|
||||||
|
|
Loading…
Reference in a new issue