Merge remote-tracking branch 'origin/master' into olmkit

1 files changed, 79 insertions, 7 deletions

diff --git a/docs/megolm.rst b/docs/megolm.rst
index 7853963..03ee426 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,79 @@ 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
+-----------
+
+Message Replays
+---------------
+
+A message can be decrypted successfully multiple times. This means that an
+attacker can re-send a copy of an old message, and the recipient will treat it
+as a new message.
+
+To mitigate this it is recommended that applications track the ratchet indices
+they have received and that they reject messages with a ratchet index that
+they have already decrypted.
+
+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 +357,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