First stab at the mpOTR spec with Joseph

spec/mpOTR.txt

@@ -0,0 +1,121 @@
+=========================================================================
+                   __________________________________
+                  < Cryptocat's mpOTR implementation >
+                   ----------------------------------
+                          \   ^__^
+                           \  (xx)\_______
+                              (__)\       )\/\
+                               U  ||----w |
+                                  ||     ||
+
+=========================================================================
+
+This specification attempts to document what is believed to be the first mpOTR
+implementation.
+
+The mpOTR paper by Ian Goldberg et al. is the basis for the cryptography in the
+mpOTR Cryptocat implementation. It is lacking in several areas and we felt it
+important to choose specifics for the handwaving parts of the paper carefully.
+Our implementation is mostly a toy but we believe it is a reasonable first stab
+at creating a simple mpOTR demonstration. With native implementations, we
+believe that mpOTR is a very reasonable encrypted chat protocol but our
+implementation is by no means peer-reviewed and should be considered an
+experiment.
+
+We have chosen to use elliptic curve cryptography and specifically, we've
+chosen to use (all hail the NSA?) P256, for use with Elliptic curve
+Diffie–Hellman (ECDH) as our ephemeral key agreement protocol,
+Elliptic Curve Digital Signature Algorithm (ECDSA) over P256 as our digital
+signature algorithm (512 bits in length giving 128 bits of security),
+whirlpool512 as our hash function (512 bits in length), HMAC as our MAC over
+our hash function (128 bits in length), AES-128 in OFB with a random IV for
+encryption (128 bits of key material, obviously), BASE64 for encoding of data,
+keys and HTTP for the transport - we assume HTTPS or Tor Hidden Service and
+consider those details out of scope. These choices should work with other
+protocols such as XMPP as the server is essentially just relaying messages -
+encoding will need to be considered for protocols other than HTTP.
+
+The original mpOTR paper leaves the group key agreement protocol open. We have
+chosen to define the group session key as the XOR of secrets from all the
+participants. The secrets are exchanged between each pair of users by using
+Elliptic Curve El Gamal, authenticated by the pair's ephemeral signing keys.
+
+Each chat message is encrypted with AES in OFB mode with the group session
+key and signed with the sender's ephemeral ECDSA key.
+
+Alice, Bob, Mallory, and Eve wish to have a chat using the Cryptocat
+chat server https://crypto.cat/ in the channel '#protocol-spec'.
+
+Alice generates a long term private/public key pair for verification of her
+identity. She does this once and (optionally) stores it for all time.
+
+  XXX: TODO: We have not yet implemented persistance of this key or a way to
+  verify the key.
+  XXX: TODO: We need to implement binding if we want to bind to specific
+  servers.
+
+Currently, any time the list of particpants changes, it is necessary to
+re-start the key-agreement protocol. In the future, it may be beneficial to
+periodically re-start the protocol to limt the window in which compromise of
+any principal can undermine deniability of messages sent after that point.
+
+At the beginning of the key agreement protocol, each party generates an
+ephemeral ECDSA private/public key pair for the chat session. Each party then
+sends its nickname and a random number to the server, which are shared by the
+server and used to generate a unique, non-secret session ID which is shared
+between all parties.
+
+  XXX: TODO: Enforce binding that each client's value for the channel name is
+consistent. This could be checked in the Assert() message before allowing chat.
+
+Each principal performs a pair-wise deniable authenticated key-exchange,
+multiplexed by the Cryptocat server. Currently, this is an Elliptic Curve
+Diffie-Hellman key exchange authenticated with each principal's long-term ECDSA
+key.
+
+  XXX: Implement deniability - lucky us, we haven't implemented persistance of
+  identity keys. We get deniability on accident.
+
+After completing pair-wise key exchange, each party sends messages to confirm
+correct receipt of ephemeral keys, as described by the mpOTR protocol.
+
+Finally, once all users have exchanged ephemeral keys, a group key exchange
+protocol is conducted to derive a group session key. Currently, each party
+generates a 128-bit random value, and exchanges it pairwise with all other
+participants using Elliptic Curve Diffie Hellman authenticated by each
+principal's ephemeral private key. The group session key is then the XOR of
+all principals' random values.
+
+  XXX: TODO: Prior to chatting, each user must send an Attest() message
+  committing to the session ID and any other parameters which should be globally
+  agreed upon. This should include in our case the version of the protocol, the
+  timeout (if any), and the name of the chat channel.
+
+When Alice wishes to send a message to the channel - she encrypts it with AES
+in OFB mode using the group session key, signs it with her ephemeral ECDSA key,
+and sends it to the server.
+
+Alice wants to share a message with Bob and so she does...
+
+  XXX: File sharing should be documented here
+
+Alice leaves the chat and sends her private ephemeral signing key to the
+channel. Each party confirms receipt of the key and at that time, the entire
+chat channel re-keys.
+
+   XXX: We have not implemented the tear-down steps of the mpOTR paper.
+
+Eve is not part of the chat but is able to intercept data sent to and from the
+server. Eve is able to learn the nickname of each chat member and to watch the
+frequency and size of the messages sent by each pary. If she does not witness
+the setup phase, she will not learn the participants' nicknames.
+
+Mallory can use Alice's ephemeral signing key to forge messages that appears to
+be from her. Alice can reasonably believe that her ephemeral signing key proves
+nothing about her statements after that point.
+
+The server is able to learn the nickname, the number of parties, the chat
+channel name, the IP addresses of the client, the timestamps and the size of
+messages.
+
+XXX: TODO - Document examples of each part of the protocol and process.