Olm: A Cryptographic Ratchet ============================ An implementation of the double cryptographic ratchet described by https://github.com/trevp/double_ratchet/wiki. Notation -------- This document uses :math:`\parallel` to represent string concatenation. When :math:`\parallel` appears on the right hand side of an :math:`=` it means that the inputs are concatenated. When :math:`\parallel` appears on the left hand side of an :math:`=` it means that the output is split. When this document uses :math:`ECDH\left(K_A,\,K_B\right)` it means that each party computes a Diffie-Hellman agreement using their private key and the remote party's public key. So party :math:`A` computes :math:`ECDH\left(K_B_public,\,K_A_private\right)` and party :math:`B` computes :math:`ECDH\left(K_A_public,\,K_B_private\right)`. Where this document uses :math:`HKDF\left(salt,\,IKM,\,info,\,L\right)` it refers to the `HMAC-based key derivation function`_ with a salt value of :math:`salt`, input key material of :math:`IKM`, context string :math:`info`, and output keying material length of :math:`L` bytes. 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 ephemeral 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 using SHA-256_ as the hash function (HKDF-SHA-256_) 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(0,\,S,\,\text{"OLM\_ROOT"},\,64\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 HKDF-SHA-256_ 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( R_{i-1},\, ECDH\left(T_{i-1},\,T_i\right),\, \text{"OLM\_RATCHET"},\, 64 \right) \end{align} Advancing the chain key ~~~~~~~~~~~~~~~~~~~~~~~ Advancing a chain key takes the previous chain key, :math:`C_{i,j-i}`. The next chain key, :math:`C_{i,j}`, is the HMAC-SHA-256_ 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-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:: \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 the public parts of 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`. She generates a new single-use key, :math:`E_A`, and computes a root key, :math:`R_0`, and a chain key :math:`C_{0,0}`. She also generates a new ratchet key :math:`T_0`. Sending the first pre-key messages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Alice computes a message key, :math:`M_{0,j}`, and a new chain key, :math:`C_{0,j+1}`, using the current chain key. She replaces the current chain key with the new one. Alice encrypts her plain-text with the message key, :math:`M_{0,j}`, using an authenticated encryption scheme (see below) to get a cipher-text, :math:`X_{0,j}`. She then sends the following to Bob: * The public part of her identity key, :math:`I_A` * The public part of her single-use key, :math:`E_A` * The public part of Bob's single-use key, :math:`E_B` * The current chain index, :math:`j` * The public part of her ratchet key, :math:`T_0` * The cipher-text, :math:`X_{0,j}` 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 as above. Bob looks up the private part of his single-use key, :math:`E_B`. He can now compute the root key, :math:`R_0`, and the chain key, :math:`C_{0,0}`, from :math:`I_A`, :math:`E_A`, :math:`I_B`, and :math:`E_B`. Bob then advances the chain key :math:`j` times, to compute the chain key used by the message, :math:`C_{0,j}`. He now creates the message key, :math:`M_{0,j}`, and attempts to decrypt the cipher-text, :math:`X_{0,j}`. If the cipher-text's authentication is correct then Bob can discard the private part of his single-use one-time key, :math:`E_B`. Bob stores Alice's initial ratchet key, :math:`T_0`, until he wants to send a message. Sending normal messages ~~~~~~~~~~~~~~~~~~~~~~~ Once a message has been received from the other side, a session is considered established, and a more compact form is used. To send a message, the user checks if they have a sender chain key, :math:`C_{i,j}`. Alice uses 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 new root key :math:`R_i` and chain key :math:`C_{i,0}` are 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 (see below) to get a cipher-text, :math:`X_{i,j}`. The user then sends the following to the recipient: * The current chain index, :math:`j` * The public part of the current ratchet key, :math:`T_i` * The cipher-text, :math:`X_{i,j}` Receiving messages ~~~~~~~~~~~~~~~~~~ The user receives a message as above with the sender's current chain index, :math:`j`, the sender's ratchet key, :math:`T_i`, and the cipher-text, :math:`X_{i,j}`. 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 root key, :math:`R_i`, and a new receiver chain, with chain key :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 receiver 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 ---------------------- Olm uses two types of messages. The underlying transport protocol must provide a means for recipients to distinguish between them. 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 ``"\x03"``. 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 public part of 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. (Olm version 1 uses HMAC-SHA-256, truncated to 8 bytes). The MAC protects all of the bytes preceding 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 ``"\x03"``. The payload uses the same key-value format as for normal messages. ============ ===== ======== ================================================ Name Tag Type Meaning ============ ===== ======== ================================================ One-Time-Key 0x0A String The public part of Bob's single-use key, :math:`E_b`. Base-Key 0x12 String The public part of Alice's single-use key, :math:`E_a`. Identity-Key 0x1A String The public part of 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_ (truncated to 64 bits) 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"``. .. math:: \begin{align} AES\_KEY_{i,j}\;\parallel\;HMAC\_KEY_{i,j}\;\parallel\;AES\_IV_{i,j} &= HKDF\left(0,\,M_{i,j},\text{"OLM\_KEYS"},\,80\right) \\ \end{align} The plain-text is encrypted with AES-256, using the key :math:`AES\_KEY_{i,j}` and the IV :math:`AES\_IV_{i,j}` to give the cipher-text, :math:`X_{i,j}`. Then the entire message (including the Version Byte and all Payload Bytes) are passed through HMAC-SHA-256. The first 8 bytes of the MAC are appended to the message. IPR --- The Olm specification (this document) is hereby placed in the public domain. Feedback -------- Can be sent to mark at matrix.org. Acknowledgements ---------------- The ratchet that Olm implements was designed by Trevor Perrin and Moxie Marlinspike - details at https://github.com/trevp/double_ratchet/wiki. Olm is an entirely new implementation written by the Matrix.org team. .. _`Curve25519`: http://cr.yp.to/ecdh.html .. _`Triple Diffie-Hellman`: https://whispersystems.org/blog/simplifying-otr-deniability/ .. _`HMAC-based key derivation function`: https://tools.ietf.org/html/rfc5869 .. _`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