diff options
Diffstat (limited to 'docs/olm.rst')
| -rw-r--r-- | docs/olm.rst | 48 |
1 files changed, 42 insertions, 6 deletions
diff --git a/docs/olm.rst b/docs/olm.rst index 8f1c612..30d2146 100644 --- a/docs/olm.rst +++ b/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. 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 -HMAC-based Key Derivation Function (HKDF) using :math:`R_{i-1}` as the salt. +chain key, :math:`C_{i,0}`, are derived from the shared secret using an HKDF +using :math:`R_{i-1}` as the salt. .. math:: \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 they will create a new chain when they next send a message. - The Olm Message Format ---------------------- @@ -161,13 +160,14 @@ 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: @@ -184,10 +184,46 @@ significant bits are stored in the first byte. =========== ===== ======== ================================================ Name Tag Type Meaning =========== ===== ======== ================================================ -Chain-Index 0x0A Integer The chain index, :math:`j`, of the message -Ratchet-Key 0x10 String The ratchet key, :math:`T_{i}`, of the message +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 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. |