242 lines
10 KiB
ReStructuredText
242 lines
10 KiB
ReStructuredText
Olm: A Crytographic Ratchet
|
|
===========================
|
|
|
|
An implementation of the cryptographic ratchet described by
|
|
https://github.com/trevp/axolotl/wiki.
|
|
|
|
|
|
The Olm Algorithm
|
|
-----------------
|
|
|
|
Initial setup
|
|
~~~~~~~~~~~~~
|
|
|
|
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.
|
|
|
|
.. math::
|
|
\begin{align}
|
|
S&=ECDH\left(I_A,\,E_B\right)\;\parallel\;ECDH\left(E_A,\,I_B\right)\;
|
|
\parallel\;ECDH\left(E_A,\,E_B\right)\\
|
|
R_0\;\parallel\;C_{0,0}&=HKDF\left(S,\,\text{"OLM\_ROOT"}\right)
|
|
\end{align}
|
|
|
|
Advancing the root key
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Advancing a root key takes the previous root key, :math:`R_{i-1}`, and two
|
|
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.
|
|
|
|
.. math::
|
|
\begin{align}
|
|
R_i\;\parallel\;C_{i,0}&=HKDF\left(
|
|
ECDH\left(T_{i-1},\,T_i\right),\,
|
|
R_{i-1},\,
|
|
\text{"OLM\_RATCHET"}
|
|
\right)
|
|
\end{align}
|
|
|
|
|
|
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.
|
|
|
|
.. math::
|
|
\begin{align}
|
|
C_{i,j}&=HMAC\left(C_{i,j-1},\,\text{"\textbackslash x02"}\right)
|
|
\end{align}
|
|
|
|
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
|
|
by Bob to encrypt messages.
|
|
|
|
.. math::
|
|
\begin{align}
|
|
M_{i,j}&=HMAC\left(C_{i,j},\,\text{"\textbackslash x01"}\right)
|
|
\end{align}
|
|
|
|
|
|
The Olm Protocol
|
|
----------------
|
|
|
|
Creating an outbound session
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Bob publishes his identity key, :math:`I_B`, and some single-use one-time
|
|
keys :math:`E_B`.
|
|
|
|
Alice downloads Bob's identity key, :math:`I_B`, and a one-time key,
|
|
:math:`E_B`. Alice takes her identity key, :math:`I_A`, and generates a new
|
|
single-use key, :math:`E_A`. Alice computes a root key, :math:`R_0`, and a
|
|
chain key :math:`C_{0,0}`. Alice generates a new ratchet key :math:`T_0`.
|
|
|
|
Sending the first pre-key messages
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Alice computes a message key, :math:`M_{0,j}`, using the current chain key,
|
|
:math:`C_{0,j}`. Alice replaces the current chain key with :math:`C_{0,j+1}`.
|
|
Alice encrypts her plain-text with the message key, :math:`M_{0,j}`, using an
|
|
authenticated encryption scheme to get a cipher-text, :math:`X_{0,j}`. Alice
|
|
sends her identity key, :math:`I_A`, her single-use key, :math:`E_A`, Bob's
|
|
single-use key, :math:`E_B`, the current chain index, :math:`j`, her ratchet
|
|
key, :math:`T_0`, and the cipher-text, :math:`X_{0,j}`, to Bob.
|
|
|
|
Alice will continue to send pre-key messages until she receives a message from
|
|
Bob.
|
|
|
|
Creating an inbound session from a pre-key message
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Bob receives a pre-key message with Alice's identity key, :math:`I_A`,
|
|
Alice's single-use key, :math:`E_A`, the public part of his single-use key,
|
|
:math:`E_B`, the current chain index, :math:`j`, Alice's ratchet key,
|
|
:math:`T_0`, and the cipher-text, :math:`X_{0,j}`. Bob looks up the private
|
|
part of the single-use key, :math:`E_B`. Bob computes the root key :math:`R_0`,
|
|
and the chain key :math:`C_{0,0}`. Bob then advances the chain key to compute
|
|
the chain key used by the message, :math:`C_{0,j}`. Bob then creates the
|
|
message key, :math:`M_{0,j}`, and attempts to decrypt the ciphertext,
|
|
:math:`X_{0,j}`. If the cipher-text's authentication is correct then Bob can
|
|
discard private part of his single-use one-time key, :math:`E_B`.
|
|
|
|
Sending messages
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
To send a message the user checks if they have a sender chain key,
|
|
:math:`C_{i,j}`. Alice use chain keys where :math:`i` is even. Bob uses chain
|
|
keys where :math:`i` is odd. If the chain key doesn't exist then a new ratchet
|
|
key :math:`T_i` is generated and a the chain key, :math:`C_{i,0}`, is computed
|
|
using :math:`R_{i-1}`, :math:`T_{i-1}` and :math:`T_i`. A message key,
|
|
:math:`M_{i,j}` is computed from the current chain key, :math:`C_{i,j}`, and
|
|
the chain key is replaced with the next chain key, :math:`C_{i,j+1}`. The
|
|
plain-text is encrypted with :math:`M_{i,j}`, using an authenticated encryption
|
|
scheme to get a cipher-text, :math:`X_{i,j}`. Then user sends the current
|
|
chain index, :math:`j`, the ratchet key, :math:`T_i`, and the cipher-text,
|
|
:math:`X_{i,j}`, to the other user.
|
|
|
|
Receiving messages
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
The user receives a message with the current chain index, :math:`j`, the
|
|
ratchet key, :math:`T_i`, and the cipher-text, :math:`X_{i,j}`, from the
|
|
other user. The user checks if they have a receiver chain with the correct
|
|
:math:`i` by comparing the ratchet key, :math:`T_i`. If the chain doesn't exist
|
|
then they compute a new receiver chain, :math:`C_{i,0}`, using :math:`R_{i-1}`,
|
|
:math:`T_{i-1}` and :math:`T_i`. If the :math:`j` of the message is less than
|
|
the current chain index on the receiver then the message may only be decrypted
|
|
if the receiver has stored a copy of the message key :math:`M_{i,j}`. Otherwise
|
|
the receiver computes the chain key, :math:`C_{i,j}`. The receiver computes the
|
|
message key, :math:`M_{i,j}`, from the chain key and attempts to decrypt the
|
|
cipher-text, :math:`X_{i,j}`.
|
|
|
|
If the decryption succeeds the reciever updates the chain key for :math:`T_i`
|
|
with :math:`C_{i,j+1}` and stores the message keys that were skipped in the
|
|
process so that they can decode out of order messages. If the receiver created
|
|
a new receiver chain then they discard their current sender chain so that
|
|
they will create a new chain when they next send a message.
|
|
|
|
The Olm Message Format
|
|
----------------------
|
|
|
|
Normal Messages
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Olm messages start with a one byte version followed by a variable length
|
|
payload followed by a fixed length message authentication code.
|
|
|
|
.. code::
|
|
|
|
+--------------+------------------------------------+-----------+
|
|
| Version Byte | Payload Bytes | MAC Bytes |
|
|
+--------------+------------------------------------+-----------+
|
|
|
|
The version byte is ``"\x01"``.
|
|
|
|
The payload consists of key-value pairs where the keys are integers and the
|
|
values are integers and strings. The keys are encoded as a variable length
|
|
integer tag where the 3 lowest bits indicates the type of the value:
|
|
0 for integers, 2 for strings. If the value is an integer then the tag is
|
|
followed by the value encoded as a variable length integer. If the value is
|
|
a string then the tag is followed by the length of the string encoded as
|
|
a variable length integer followed by the string itself.
|
|
|
|
Olm uses a variable length encoding for integers. Each integer is encoded as a
|
|
sequence of bytes with the high bit set followed by a byte with the high bit
|
|
clear. The seven low bits of each byte store the bits of the integer. The least
|
|
significant bits are stored in the first byte.
|
|
|
|
=========== ===== ======== ================================================
|
|
Name Tag Type Meaning
|
|
=========== ===== ======== ================================================
|
|
Ratchet-Key 0x0A String The ratchet key, :math:`T_{i}`, of the message
|
|
Chain-Index 0x10 Integer The chain index, :math:`j`, of the message
|
|
Cipher-Text 0x22 String The cipher-text, :math:`X_{i,j}`, of the message
|
|
=========== ===== ======== ================================================
|
|
|
|
The length of the MAC is determined by the authenticated encryption algorithm
|
|
being used. The MAC protects all of the bytes preceeding the MAC.
|
|
|
|
Pre-Key Messages
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Olm pre-key messages start with a one byte version followed by a variable
|
|
length payload.
|
|
|
|
.. code::
|
|
|
|
+--------------+------------------------------------+
|
|
| Version Byte | Payload Bytes |
|
|
+--------------+------------------------------------+
|
|
|
|
The version byte is ``"\x01"``.
|
|
|
|
The payload uses the same key-value format as for normal messages.
|
|
|
|
============ ===== ======== ================================================
|
|
Name Tag Type Meaning
|
|
============ ===== ======== ================================================
|
|
One-Time-Key 0x0A String Bob's single-use key, :math:`E_b`.
|
|
Base-Key 0x12 String Alice's single-use key, :math:`E_a`.
|
|
Identity-Key 0x1A String Alice's identity key, :math:`I_a`.
|
|
Message 0x22 String An embedded Olm message with its own version and
|
|
MAC.
|
|
============ ===== ======== ================================================
|
|
|
|
Olm Authenticated Encryption
|
|
----------------------------
|
|
|
|
Version 1
|
|
~~~~~~~~~
|
|
|
|
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}
|