Document the pre-key messages
This commit is contained in:
parent
9e79571d07
commit
447501bd57
1 changed files with 42 additions and 6 deletions
48
docs/olm.rst
48
docs/olm.rst
|
@ -33,8 +33,8 @@ 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
|
chain key, :math:`C_{i,0}`, are derived from the shared secret using an HKDF
|
||||||
HMAC-based Key Derivation Function (HKDF) using :math:`R_{i-1}` as the salt.
|
using :math:`R_{i-1}` as the salt.
|
||||||
|
|
||||||
.. math::
|
.. math::
|
||||||
\begin{align}
|
\begin{align}
|
||||||
|
@ -151,7 +151,6 @@ 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
|
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.
|
they will create a new chain when they next send a message.
|
||||||
|
|
||||||
|
|
||||||
The Olm Message Format
|
The Olm Message Format
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
|
@ -161,13 +160,14 @@ Normal Messages
|
||||||
Olm messages start with a one byte version followed by a variable length
|
Olm messages start with a one byte version followed by a variable length
|
||||||
payload followed by a fixed length message authentication code.
|
payload followed by a fixed length message authentication code.
|
||||||
|
|
||||||
|
|
||||||
.. code::
|
.. code::
|
||||||
|
|
||||||
+--------------+------------------------------------+-----------+
|
+--------------+------------------------------------+-----------+
|
||||||
| Version Byte | Payload Bytes | MAC Bytes |
|
| 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
|
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
|
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:
|
integer tag where the 3 lowest bits indicates the type of the value:
|
||||||
|
@ -184,10 +184,46 @@ significant bits are stored in the first byte.
|
||||||
=========== ===== ======== ================================================
|
=========== ===== ======== ================================================
|
||||||
Name Tag Type Meaning
|
Name Tag Type Meaning
|
||||||
=========== ===== ======== ================================================
|
=========== ===== ======== ================================================
|
||||||
Chain-Index 0x0A Integer The chain index, :math:`j`, of the message
|
Ratchet-Key 0x0A String The ratchet key, :math:`T_{i}`, of the message
|
||||||
Ratchet-Key 0x10 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
|
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 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.
|
||||||
|
|
Loading…
Reference in a new issue