Commit 447501bd by Mark Haines

### Document the pre-key messages

parent 9e79571d
 ... @@ -33,8 +33,8 @@ Curve25519 inputs: the previous ratchet key, :math:T_{i-1}, and the current ... @@ -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 ... @@ -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 ... @@ -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. ... @@ -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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!