updated documenation in accordance with removeal of RSA fingerprints …

…and updated key exchange protocol

docs/conf.py

@@ -48,9 +48,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '3.1.0'
+version = '4.0.0'
 # The full version, including alpha/beta/rc tags.
-release = '3.1.0'
+release = '4.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -23,7 +23,6 @@ Features
 * Runs on Linux, Windows, and Mac OS X
 * No registration or software installation required
 * Chat with multiple people simultaneously
-* Ability to set own RSA keys
 * Ability to host your own server (for the technically inclined)
 * Graphical UI and command line (Curses) UI
 * Open source (LGPL license)
@@ -32,12 +31,9 @@ Features
 How does it work and how is it secure?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-|project| works by relaying messages from one person to another through a relay server. When the program
-starts it generates encryption keys (2048bit RSA and 256bit AES) that all communications are encrypted
-with before leaving your computer and then decrypted on your friend's computer. Further, to ensure that
-no one is listening in on your conversation, the fingerprints of the encryption keys are provided.
-You can use this to verify with your friend that no one is listening. More on this in the :ref:`using-|project|`
-section though.
+|project| works by relaying messages from one person to another through a relay server. It generates
+per-session encryption keys (256bit AES) that all communications are encrypted with before leaving
+your computer and then decrypted on the destination computer.
 
 -----------
 Quick Start
@@ -47,7 +43,7 @@ Quick Start
 2. Launch the executable (no need to install anything).
 3. Select a nickname and connect to the server.
 4. Enter the nickname of the person you want to chat with.
-5. You should now be chatting! (but you should verify the key integrity in the options menu)
+5. You should now be chatting!
 
 Need more info? See the :ref:`using-|project|` page for much more detailed instructions.
 

docs/protocol.rst

@@ -20,10 +20,8 @@ Basic Properties
   * ``destNick``: The nickname of the receiver
   * ``payload``: The content of the message. If an encrypted message, it is base64 encoded
   * ``hmac``: The HMAC as calculated by the sender to be verified against by the receiver
-  * ``key``: If the payload is encrypted, the AES key used for this message (base64 encoded and encrypted with RSA)
-  * ``iv``: If the payload is encrypted, the AES IV used for this message (base64 encoded and encrypted with RSA)
-  * ``salt``: If the payload is encrypted, the AES salt used for this message (base64 encoded and encrypted with RSA)
   * ``error``: The error code, if applicable
+  * ``num``: The message number, starting from 0 and monotonically increasing with sequential numbers.
 
 * All commands *are* case sensitive
 * After the initial handshake is complete, the connection is kept alive indefinitely in a message loop until
@@ -49,26 +47,48 @@ Client Commands
 * ``REDY``: The client is ready to initiate a handshake
 * ``REJ``: If the client rejected a connection from another client
 * ``PUB_KEY [arg]``
-* ``AES_KEY [arg]``
-* ``AES_IV [arg]``
-* ``AES_SALT [arg]``
+* ``SMP1 [arg]``
+* ``SMP2 [arg]``
+* ``SMP3 [arg]``
+* ``SMP4 [arg]``
 * ``MSG [arg]``
+* ``TYPING [arg]``
 * ``END``
 * ``ERR``
 
+^^^^^^^^^^^^^
+Typing Status
+^^^^^^^^^^^^^
+
+A client may optional give the typing status of the user to the remote client by issuing the ``TYPING``
+command. The ``TYPING`` command takes one of three possible arguments:
+
+* ``0``: The user is currently typing
+* ``1``: The user has stopped typing and deleted all text from the buffer
+* ``2``: The user has stopped typing, but left some text in the buffer
+
 ------------------
 Encryption Details
 ------------------
 
-* AES is 256 bits in CBC mode with randomly generated key, IV and 8 byte salt.
-* RSA is 2048 bits with a public exponent of 65537.
-* RSA fingerprints are the MD5 digest of a client's public key.
+* 1568-bit secret is exchanged via Diffie-Hellman.
+* The Socialist Millionaire protocol (as defined by Off-The-Record) is used to verify the Diffie-Hellman secret.
+* An AES key is the first 32 bytes of the SHA512 digest of the Diffie-Hellman secret. The IV last 32 bytes of this hash.
+* All AES operations are with a 256-bit key in CBC mode.
 * HMAC's are the SHA256 digest of the AES key and the encrypted message payload. The receiver calculates
-  and verfies the HMAC before attempting to decrypt the message payload.
-* Each client generates a unique RSA keypair and AES key for each connection. The exception being if the user
-  saved an RSA keypair. Then each connection uses the same keypair, but AES keys are still randomly generated.
-* The AES key, IV, and salt are randomly generated for each message and sent along with the message encrypted
-  with the RSA keys that are exchanged in the handshake.
+  and verifies the HMAC before attempting to decrypt the message payload.
+
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Socialist Millionaire Protocol
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Socialist Millionaire Protocol (SMP) is a method for determining whether two clients share the same secret,
+but without exchanging the secret itself. In |project|'s case, it is used to determine whether a MITM
+attack has occurred or is occurring and compromised the Diffie-Hellman key exchange protocol.
+
+The SMP is relatively complex so it is best to defer to the documentation of it's implementation
+as defined in the Off-The-Record (OTR) protocol version 3.
 
 -----------------
 Handshake Details
@@ -89,6 +109,14 @@ The commands in the handshake must be performed in the following order:
 +--------+---------+--------+
 |(switch to AES encryption) |
 +--------+---------+--------+
+|        |   <-    |SMP1    |
++--------+---------+--------+
+|SMP2    |   ->    |        |
++--------+---------+--------+
+|        |   <-    |SMP3    |
++--------+---------+--------+
+|SMP4    |   ->    |        |
++--------+---------+--------+
 
 The client may reject a connection with the ``REJ`` command instead of sending the ``REDY`` command.
 
@@ -98,10 +126,12 @@ Message Loop Details
 
 Clients may send messages any order including multiple messages in a row.
 
-+--------+---------+-------+
-|Server  |direction| Client|
-+========+=========+=======+
-|MSG     |   <->   |MSG    |
-+--------+---------+-------+
-|END     |   <->   |END    |
-+--------+---------+-------+
++--------+---------+--------+
+|Client A|direction|Client B|
++========+=========+========+
+|MSG     |   <->   |MSG     |
++--------+---------+--------+
+|TYPING  |   <->   |TYPING  |
++--------+---------+--------+
+|END     |   <->   |END     |
++--------+---------+--------+

docs/usage.rst

@@ -38,70 +38,6 @@ Let's run through the process of connecting with a friend.
 
 .. image:: images/chatting.png
 
-**But**, after connecting, you should always verify encrytion key integrity of the person you're
-chatting with to ensure no one is listening in on your conversation. See the
-:ref:`verifying-encryption-key-integrity` section below.
-
-.. _verifying-encryption-key-integrity:
-
-----------------------------------
-Verifying encryption key integrity
-----------------------------------
-
-A common attack against encryption is called the man-in-the-middle attack. To protect against
-this, it is highly recommended to verify the integrity of the encryption keys of the person you're
-chatting with. Fortunately, this is very simple.
-
-First, let's understand what a fingerprint is. Encryption keys look very long to humans. In order to
-make them more managable, we create a fingerprint of a key by doing some fancy math that takes a long
-input and creates a short sequence of letters and numbers. Like a human's fingerprint, an encryption
-key's fingerprint is unique and a good way of proving that you are chatting with who you think you're
-chatting with.
-
-1. Select the ``Verify key integrity`` option by clicking the key icon on the left hand side or from the options menu.
-
-2. You and your friend need to exchange the sequence of numbers and letters under the
-   "You read to them" heading. These are the key fingerprints. A good way of doing this is over the
-   phone so you can verify the voice of your friend. Other options include text message or email
-   (but telephone is preferred if possible) or even in person if you want to chat at some later time.
-
-.. image:: images/fingerprint_dialog.png
-
-3. If both fingerprints match, you're chatting securely! If not, someone is likely listening to your
-   communcations and you should disconnect immediately.
-
-**Note:** You should verify the identity of your friend every time you connect to him/her since
-a new encryption key is generated each time the application is started, the fingerprints you
-exchanged will change. You can avoid this by saving the encryption keys where it is then
-only necessary to exchange this info once, but you should still make sure that the "they read to you"
-section is the same for all subsequent connections. See the :ref:`saving-encryption-keys` section below.
-
-.. _saving-encryption-keys:
-
-----------------------
-Saving encryption keys
-----------------------
-
-By default, |project| generates new encryption keys each time it is started. This means you should
-exchange fingerprints in the verifying key integrity process described above. However, if you save
-your encryption keys, your fingerprint won't change so you only need to exchange fingerprints once
-and then you can check that the fingerprints you exchanged matches for all new connections.
-
-To save your encryption keys:
-
-1. You and your friend should go through the verification of encryption key integrity as described
-   in the above section.
-2. Save (or write down) the sequence from the "they read to you" part of the integriy verification
-   process.
-3. Both you and your friend save your keys by selecting the "Save keys" option in the options menu.
-4. Your encryption keys are secret things. To protect them, |project| will encrypt the encryption
-   keys (yes, it sounds weird, but it's safe!). Enter a passphrase to protect them. You'll need
-   this the each time you start |project| now.
-5. Each subsequent time you connect to your friend, you can now verify the fingerprint in the "they
-   read to you section" with the one you originally exchanged with them.
-
-If you ever want to generate new encryption keys, just select "Clear keys" from the options menu.
-
 -------------------------------
 Command Line Options (advanced)
 -------------------------------