Skip to content
GitLab
Menu
Projects
Groups
Snippets
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
matrix-org
Olm
Commits
be9d7406
Commit
be9d7406
authored
Aug 18, 2015
by
Mark Haines
Browse files
Add some links to the spec for the various primitives being used.
parent
40e49ee1
Changes
1
Hide whitespace changes
Inline
Side-by-side
docs/olm.rst
View file @
be9d7406
...
...
@@ -11,13 +11,13 @@ The Olm Algorithm
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:`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 and ``"OLM_ROOT"``
as the info.
`
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
using SHA-256_ as the hash function
(HKDF-SHA-256_) with default salt and ``"OLM_ROOT"``
as the info.
.. math::
\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.
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 and ``"OLM_RATCHET"`` as the info.
chain key, :math:`C_{i,0}`, are derived from the shared secret using
HKDF-SHA-256_ using :math:`R_{i-1}` as the salt and ``"OLM_RATCHET"`` as the
info.
.. math::
\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
chain key, :math:`C_{i,j}`, is the HMAC of ``"\x02"`` using the
previous chain
key as the key.
chain key, :math:`C_{i,j}`, is the HMAC
-SHA-256_
of ``"\x02"`` using the
previous chain
key as the key.
.. math::
\begin{align}
...
...
@@ -63,9 +64,9 @@ Creating a message key
~~~~~~~~~~~~~~~~~~~~~~
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
chain key as the key. The message keys where :math:`i` is even are used
by
Alice to encrypt messages. The message keys where :math:`i` is odd are used
message key, :math:`M_{i,j}`, is the HMAC
-SHA-256_
of ``"\x01"`` using the
current
chain key as the key. The message keys where :math:`i` is even are used
by
Alice to encrypt messages. The message keys where :math:`i` is odd are used
by Bob to encrypt messages.
.. math::
...
...
@@ -225,18 +226,27 @@ Olm Authenticated Encryption
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 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.
First the plain-text 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) \\
&= HKDF\left(M_{i,j},\,\text{"OLM\_
KEYS
"}\right) \\
\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
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment