From 49c117c62eccf914fb7b12ac4a7c3973ac172513 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Tue, 4 Aug 2015 18:09:44 +0100 Subject: [PATCH 1/9] Start writing protocol spec for olm --- docs/olm.rst | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/olm.rst diff --git a/docs/olm.rst b/docs/olm.rst new file mode 100644 index 0000000..07836f6 --- /dev/null +++ b/docs/olm.rst @@ -0,0 +1,42 @@ +Olm: A Crytographic Ratchet +=========================== + +An implementation of the cryptographic ratchet described by +https://github.com/trevp/axolotl/wiki. + + +The Olm Algorithm +----------------- + +.. figure:: Axolotl.svg + + +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). + +.. 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(S,\,\text{"OLM\_ROOT"}) + \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, `S` is generated +using Diffie-Hellman on the ratchet keys. The next root key, :math:`R_o`, and +chain key, :math:`C_{i,0}`, are derived from the shared secret using an +HMAC-based Key Derivation Function (HKDF). + + From 531a2fb4264b83788d7cadf64acccd7cfab4441f Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Wed, 5 Aug 2015 17:22:51 +0100 Subject: [PATCH 2/9] Document the olm protocol. --- docs/olm.rst | 127 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 120 insertions(+), 7 deletions(-) diff --git a/docs/olm.rst b/docs/olm.rst index 07836f6..db32cdb 100644 --- a/docs/olm.rst +++ b/docs/olm.rst @@ -19,24 +19,137 @@ The setup takes four Curve25519 inputs: Identity 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). +HMAC-based Key Derivation Function (HKDF) with default salt. .. 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(S,\,\text{"OLM\_ROOT"}) + 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, `S` is generated -using Diffie-Hellman on the ratchet keys. The next root key, :math:`R_o`, and +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). +HMAC-based Key Derivation Function (HKDF) using :math:`R_{i-1}` as the salt. + +.. 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. From 9e79571d07ed1dac4445dff57a7077e265f3d06c Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Fri, 7 Aug 2015 18:24:20 +0100 Subject: [PATCH 3/9] Start specifying the message format --- docs/olm.rst | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/docs/olm.rst b/docs/olm.rst index db32cdb..8f1c612 100644 --- a/docs/olm.rst +++ b/docs/olm.rst @@ -8,9 +8,6 @@ https://github.com/trevp/axolotl/wiki. The Olm Algorithm ----------------- -.. figure:: Axolotl.svg - - Initial setup ~~~~~~~~~~~~~ @@ -153,3 +150,44 @@ 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 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 +=========== ===== ======== ================================================ +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 +Cipher-Text 0x22 String The cipher-text, :math:`X_{i,j}`, of the message +=========== ===== ======== ================================================ + + + From 447501bd576f25263f8c741f1fd75a54aff90292 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Tue, 11 Aug 2015 13:12:51 +0100 Subject: [PATCH 4/9] Document the pre-key messages --- docs/olm.rst | 48 ++++++++++++++++++++++++++++++++++++++++++------ 1 file 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. From 40e49ee173bd711fcb15c517549597bced3d0210 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Tue, 11 Aug 2015 18:13:26 +0100 Subject: [PATCH 5/9] Add spec for the authenticated encryption used by olm --- docs/olm.rst | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/olm.rst b/docs/olm.rst index 30d2146..78c9731 100644 --- a/docs/olm.rst +++ b/docs/olm.rst @@ -16,7 +16,8 @@ The setup takes four Curve25519 inputs: Identity 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. +HMAC-based Key Derivation Function (HKDF) with default salt and ``"OLM_ROOT"`` +as the info. .. math:: \begin{align} @@ -34,7 +35,7 @@ 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. +using :math:`R_{i-1}` as the salt and ``"OLM_RATCHET"`` as the info. .. math:: \begin{align} @@ -224,6 +225,18 @@ 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. +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} From be9d74063d5b05e7debe5ad832681c4807f38d24 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Tue, 18 Aug 2015 14:33:40 +0100 Subject: [PATCH 6/9] Add some links to the spec for the various primitives being used. --- docs/olm.rst | 44 +++++++++++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/docs/olm.rst b/docs/olm.rst index 78c9731..1331a00 100644 --- a/docs/olm.rst +++ b/docs/olm.rst @@ -11,13 +11,13 @@ The Olm Algorithm Initial setup ~~~~~~~~~~~~~ -The setup takes four Curve25519 inputs: Identity keys for Alice and Bob, +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. +`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} @@ -34,8 +34,9 @@ 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. +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} @@ -51,8 +52,8 @@ 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. +chain key, :math:`C_{i,j}`, is the HMAC-SHA-256_ of ``"\x02"`` using the +previous chain key as the key. .. math:: \begin{align} @@ -63,9 +64,9 @@ 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 +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:: @@ -225,18 +226,27 @@ Olm Authenticated Encryption Version 1 ~~~~~~~~~ -Version 1 of Olm uses AES-256 in CBC mode with PCKS#7 padding for encryption +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. +First the plain-text 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) \\ + &= HKDF\left(M_{i,j},\,\text{"OLM\_KEYS"}\right) \\ \end{align} + +.. _`Curve25519`: http://cr.yp.to/ecdh.html +.. _`Triple Diffie-Hellman`: https://whispersystems.org/blog/simplifying-otr-deniability/ +.. _`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 From c4ad39a3c427704492ffefc9a713c9634a55507b Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Tue, 18 Aug 2015 14:40:10 +0100 Subject: [PATCH 7/9] Linkify all of the HMAC and HKDF references --- docs/olm.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/olm.rst b/docs/olm.rst index 1331a00..4a1d3c5 100644 --- a/docs/olm.rst +++ b/docs/olm.rst @@ -226,10 +226,10 @@ 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"``. +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 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 From eee46a549ca3caa397bdbd3396e27c4d8d7c1b89 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Tue, 18 Aug 2015 14:46:57 +0100 Subject: [PATCH 8/9] Fix spelling --- docs/olm.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/olm.rst b/docs/olm.rst index 4a1d3c5..d07dc1d 100644 --- a/docs/olm.rst +++ b/docs/olm.rst @@ -1,5 +1,5 @@ -Olm: A Crytographic Ratchet -=========================== +Olm: A Cryptographic Ratchet +============================ An implementation of the cryptographic ratchet described by https://github.com/trevp/axolotl/wiki. @@ -12,7 +12,7 @@ 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:`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 @@ -113,7 +113,7 @@ Alice's single-use key, :math:`E_A`, the public part of his single-use key, 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, +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 private part of his single-use one-time key, :math:`E_B`. @@ -147,7 +147,7 @@ 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` +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 @@ -192,7 +192,7 @@ 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. +being used. The MAC protects all of the bytes preceding the MAC. Pre-Key Messages ~~~~~~~~~~~~~~~~ From f58b71a14e17a3760fd1ce8baabc57a1afa3522a Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Thu, 20 Aug 2015 10:12:19 +0100 Subject: [PATCH 9/9] Clarify that only the public parts of keys are sent over the wire --- docs/olm.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/olm.rst b/docs/olm.rst index d07dc1d..51a38bd 100644 --- a/docs/olm.rst +++ b/docs/olm.rst @@ -186,7 +186,8 @@ 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 +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 =========== ===== ======== ================================================ @@ -213,9 +214,12 @@ 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`. +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. ============ ===== ======== ================================================