diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/megolm.rst | 75 | ||||
| -rw-r--r-- | docs/olm.rst | 37 |
2 files changed, 102 insertions, 10 deletions
diff --git a/docs/megolm.rst b/docs/megolm.rst index 7853963..4929349 100644 --- a/docs/megolm.rst +++ b/docs/megolm.rst @@ -27,7 +27,7 @@ The Megolm ratchet is intended for encrypted messaging applications where there may be a large number of recipients of each message, thus precluding the use of peer-to-peer encryption systems such as `Olm`_. -It also allows a receipient to decrypt received messages multiple times. For +It also allows a recipient to decrypt received messages multiple times. For instance, in client/server applications, a copy of the ciphertext can be stored on the (untrusted) server, while the client need only store the session keys. @@ -143,7 +143,7 @@ copy of the counter, ratchet, and public key. Message encryption ~~~~~~~~~~~~~~~~~~ -This version of Megolm uses AES-256_ in CBC_ mode with `PCKS#7`_ padding and +This version of Megolm uses AES-256_ in CBC_ mode with `PKCS#7`_ padding and HMAC-SHA-256_ (truncated to 64 bits). The 256 bit AES key, 256 bit HMAC key, and 128 bit AES IV are derived from the megolm ratchet :math:`R_i`: @@ -199,9 +199,9 @@ session. In order to maintain the ability to decrypt conversation history, inbound sessions should store a copy of their earliest known ratchet value (unless they -explicitly want to drop the ability to decrypt that history). They may also -choose to cache calculated ratchet values, but the decision of which ratchet -states to cache is left to the application. +explicitly want to drop the ability to decrypt that history - see `Partial +Forward Secrecy`_\ ). They may also choose to cache calculated ratchet values, +but the decision of which ratchet states to cache is left to the application. Data exchange formats --------------------- @@ -269,7 +269,68 @@ protocol). The MAC protects all of the bytes preceding the MAC. The length of the signature is determined by the signing algorithm being used (64 bytes in this version of the protocol). The signature covers all of the -bytes preceding the signaure. +bytes preceding the signature. + +Limitations +----------- + +Lack of Transcript Consistency +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In a group conversation, there is no guarantee that all recipients have +received the same messages. For example, if Alice is in a conversation with Bob +and Charlie, she could send different messages to Bob and Charlie, or could +send some messages to Bob but not Charlie, or vice versa. + +Solving this is, in general, a hard problem, particularly in a protocol which +does not guarantee in-order message delivery. For now it remains the subject of +future research. + +Lack of Backward Secrecy +~~~~~~~~~~~~~~~~~~~~~~~~ + +Once the key to a Megolm session is compromised, the attacker can decrypt any +future messages sent via that session. + +In order to mitigate this, the application should ensure that Megolm sessions +are not used indefinitely. Instead it should periodically start a new session, +with new keys shared over a secure channel. + +.. TODO: Can we recommend sensible lifetimes for Megolm sessions? Probably + depends how paranoid we're feeling, but some guidelines might be useful. + +Partial Forward Secrecy +~~~~~~~~~~~~~~~~~~~~~~~ + +Each recipient maintains a record of the ratchet value which allows them to +decrypt any messages sent in the session after the corresponding point in the +conversation. If this value is compromised, an attacker can similarly decrypt +those past messages. + +To mitigate this issue, the application should offer the user the option to +discard historical conversations, by winding forward any stored ratchet values, +or discarding sessions altogether. + +Dependency on secure channel for key exchange +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The design of the Megolm ratchet relies on the availability of a secure +peer-to-peer channel for the exchange of session keys. Any vulnerabilities in +the underlying channel are likely to be amplified when applied to Megolm +session setup. + +For example, if the peer-to-peer channel is vulnerable to an unknown key-share +attack, the entire Megolm session become similarly vulnerable. For example: +Alice starts a group chat with Eve, and shares the session keys with Eve. Eve +uses the unknown key-share attack to forward the session keys to Bob, who +believes Alice is starting the session with him. Eve then forwards messages +from the Megolm session to Bob, who again believes they are coming from +Alice. Provided the peer-to-peer channel is not vulnerable to this attack, Bob +will realise that the key-sharing message was forwarded by Eve, and can treat +the Megolm session as a forgery. + +A second example: if the peer-to-peer channel is vulnerable to a replay +attack, this can be extended to entire Megolm sessions. License ------- @@ -285,6 +346,6 @@ Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_. .. _`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 +.. _`PKCS#7`: https://tools.ietf.org/html/rfc2315 .. _`Olm`: ./olm.html .. _`Protocol Buffers encoding`: https://developers.google.com/protocol-buffers/docs/encoding diff --git a/docs/olm.rst b/docs/olm.rst index 99417e0..093cb47 100644 --- a/docs/olm.rst +++ b/docs/olm.rst @@ -30,7 +30,7 @@ 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:`I_A` and :math:`I_B`, and one-time 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 @@ -279,7 +279,7 @@ Olm Authenticated Encryption Version 1 ~~~~~~~~~ -Version 1 of Olm uses AES-256_ in CBC_ mode with `PCKS#7`_ padding for +Version 1 of Olm uses AES-256_ in CBC_ mode with `PKCS#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 @@ -298,6 +298,37 @@ 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. +Message authentication concerns +------------------------------- + +To avoid unknown key-share attacks, the application must include identifying +data for the sending and receiving user in the plain-text of (at least) the +pre-key messages. Such data could be a user ID, a telephone number; +alternatively it could be the public part of a keypair which the relevant user +has proven ownership of. + +.. admonition:: Example attacks + + 1. Alice publishes her public Curve25519 identity key, :math:`I_A`. Eve + publishes the same identity key, claiming it as her own. Bob downloads + Eve's keys, and associates :math:`I_A` with Eve. Alice sends a message to + Bob; Eve intercepts it before forwarding it to Bob. Bob believes the + message came from Eve rather than Alice. + + This is prevented if Alice includes her user ID in the plain-text of the + pre-key message, so that Bob can see that the message was sent by Alice + originally. + + 2. Bob publishes his public Curve25519 identity key, :math:`I_B`. Eve + publishes the same identity key, claiming it as her own. Alice downloads + Eve's keys, and associates :math:`I_B` with Eve. Alice sends a message to + Eve; Eve cannot decrypt it, but forwards it to Bob. Bob believes the + Alice sent the message to him, wheras Alice intended it to go to Eve. + + This is prevented by Alice including the user ID of the intended recpient + (Eve) in the plain-text of the pre-key message. Bob can now tell that the + message was meant for Eve rather than him. + IPR --- @@ -323,4 +354,4 @@ an entirely new implementation written by the Matrix.org team. .. _`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 +.. _`PKCS#7`: https://tools.ietf.org/html/rfc2315 |