3 files changed, 89 insertions, 19 deletions
diff --git a/pages/features/cryptography/en.text b/pages/features/cryptography/en.text
index 5c077c6..30b22b4 100644
--- a/pages/features/cryptography/en.text
+++ b/pages/features/cryptography/en.text
@@ -66,10 +66,12 @@ p((. The block-encrypted local SQLite database uses @AES-256-CBC@ using the firs
 
 p((. Per-document encryption of documents stored remotely uses symmetric encryption with AES-256-CTR or XSalsa20 cipher using 256 bit keys. The library pycryptopp is used for this. The key and MAC used to encrypt each individual document are derived as follows:
 
-bc. storage_secret_a = first 256 bits of storage secret
+<pre style="margin-left: 2em">
+storage_secret_a = first 256 bits of storage secret
 storage_secret_b = everything after first 256 bits of storage secret
 document_key = hmac(document_id, storage_secret_b)
 document_mac = hmac(document_id | document_revision | iv | ciphertext, hmac(document_id, storage_secret_a)
+</pre>
 
 p((. Every document has its own key. The [@document_revision@] in the document MAC prevents a rollback to an old version of the document. HMAC uses SHA256.
 
diff --git a/pages/features/email/en.text b/pages/features/email/en.text
index 4b91f78..fe00a40 100644
--- a/pages/features/email/en.text
+++ b/pages/features/email/en.text
@@ -1,24 +1,22 @@
 @title = "Bitmask Email Details"
 @nav_title = "Email"
 
-h2. How it works
-
-When a service provider runs the LEAP platform, their users can access secure email in three steps:
+h2. How to use it
 
 # Download and install the Bitmask application.
 # Run the Bitmask application to log in or sign up with the service provider.
-# Configure the user's mail client to connect to the local Bitmask application. In case of the Thunderbird email client, this configuration is semi-automatic.
+# Configure the user's mail client to connect to the local IMAP and SMTP services provided by the Bitmask application. In case of the Thunderbird email client, this configuration is semi-automatic.
 
 The Bitmask application acts as a local "proxy" between the service provider and the mail client. It handles all the encryption and data synchronization.
 
-h2. Immediate benefits of using Bitmask email
+h2. Benefits of Bitmask Email
 
 Email features include:
 
-* Bitmask encrypted email is easy to use while still being backward compatible with the existing OpenPGP protocol for secure email.
+* Bitmask encrypted email is easy to use while still being backward compatible with the existing protocols for secure email (currently OpenPGP, with additional support for S/MIME coming in the future).
 * Unless already encrypted, all incoming email is automatically encrypted to the recipient on the server before being stored, so only you can read it (including meta-data). The server is able to read unencrypted incoming email for a brief moment, but no email is ever stored in a manner that the provider can read it.
-* Whenever possible, outgoing email is automatically encrypted so that only the recipients can read it (if a valid OpenPGP public keys can be discovered for the recipients). This encryption takes place on the user's device.
-* OpenPGP public keys are [[automatically discovered and validated => https://leap.se/nicknym]], allowing you to have confidence your communication is confidential and with the correct person (without the headache of typical key signing).
+* Whenever possible, outgoing email is automatically encrypted so that only the recipients can read it (if a valid public keys can be discovered for the recipients). This encryption takes place on the user's device.
+* Public keys are [[automatically discovered and validated => https://leap.se/nicknym]], allowing you to have confidence your communication is confidential and with the correct person (without the headache of typical key signing).
 * The user does not need to worry about key management. Their keys are always kept up-to-date on every device.
 * The user is able to use any email client of their choice (e.g. Thunderbird, Apple Mail, Outlook).
 * When disconnected from the internet, the user can still interact with a local copy of all their mail. When the internet connect is available again, all their changes will get synchronized with the server storage and to their other devices.
@@ -30,20 +28,72 @@ General security features of the Bitmask application include:
 * If you download the Bitmask application from https://dl.bitmask.net, your service provider cannot add a backdoor to compromise your security.
 * The Bitmask application is always kept up to date with the latest security patches (coming soon).
 
-h2. Long term benefits when two Bitmask compatible providers talk to one another
+h2. How it works
+
+NOTE: technical jargon ahead.
+
+h3. Receiving mail
+
+*Message reception and storage*
+
+# An incoming email is received by the provider's MX (mail exchange) server.
+# The MX server re-encrypts the incoming email using the public key of the recipient user. This happens even if the email is already encrypted so that the metadata is not stored in a way that anyone but the recipient may access it.
+# The user logs in to their Bitmask client:
+## The client unlocks the locally encrypted storage database.
+## The client asks the server if there is any new data and begins a synchronization process.
+# The client downloads the new incoming message.
+# The message is decrypted using the user's private key, and then stored in the locally encrypted storage database.
+# The local storage database is synchronized with the provider's cloud storage service. To be stored on the server, a unique key generate for each document in the local storage database before it is sent to the server  (see [[Soledad => https://leap.se/en/soledad]] for more details).
+# If the user has the Bitmask client running on other devices, then these clients will notice the change to the storage database and re-synchronize.
+
+*Message validation*
+
+# If the received message was signed, the client will attempt to validate the signature.
+# If the sender's public key is not already known to the client's key manager, the client will attempt to acquire it:
+## If the email was sent from a LEAP-powered provider, the key will be anonymously requested from the sender's provider.
+## If the public key is attached to the email, it will be imported.
+## If the email contains an OpenPGP header, the client will download the public key from the specified source.
+## If all else fails, the client will search OpenPGP keyservers for a key that matches the fingerprint on the signature.
+# Once acquire, the sender's public key is stored in the locally encrypted and synchronized storage database.
+# Public keys are updated using the rules for [[transitional key validation => https://leap.se/en/transitional-key-validation]].
+
+*Reading the message*
+
+The user can read the email in one of two ways:
+
+# By connecting a mail user agent, such as Thunderbird, to the local IMAP server created by Bitmask.
+# By launching the built-in mail app (in progress, not part of current stable releases).
+
+h3. Sending mail
+
+*Composing the message*
+
+The user can compose an email in one of two ways:
+
+# By connecting a mail user agent, such as Thunderbird, to the local SMTP server created by Bitmask.
+# By launching the built-in mail app (in progress, not part of current stable releases).
+
+*Encrypting the message*
 
-One of the fundamental problems with email is that the meta-data routing information is exposed as cleartext. Encrypting a message with OpenPGP or S/MIME does nothing to help with this.
+# The client's key manager acquires the public key for each recipient, if not already stored.
+## The key manager tries whatever means it can. Currently, this includes anonymously contacting the recipient's provider and searching OpenPGP keyservers, and will include DANE/DNSSec and CONIKS in the future.
+## Discovered keys are stored in the locally encrypted storage database, and synchronized among the user's devices.
+# The message is duplicated into separate copies, once for each recipient, and each copy is encrypted for one recipient and relayed for delivery.
 
-The email protocol does support an optional method of securely relaying messages using TLS to encrypt the connection. This method, called StartTLS, is easily undermined by attackers and there is no good way for email providers to validate the authenticity of other servers (without relying on the problematic CA certificate authority system).
+*Relaying the message*
 
-For now, Bitmask addresses these problems with two enhancements when two compatible providers are talking to one another:
+Currently:
 
-* When relaying email, server keys are discovered and validated using DNSSEC/DANE.
-* For these providers, TLS with validated keys becomes required for all communication.
+# The Bitmask client connects to MX server of the sender's provider. This connection is authenticated using a X.509 client certificate stored by the client, a separate one for each sender email address.
+# If the client certificate matches the "From" field of the email, then the email is DKIM signed and relayed to the destination MX server.
 
-This approach is effective against external network observers, but does not protect the meta-data from the service providers themselves. Also, it does not, by itself, protect against more advanced attacks involving timing and traffic analysis.
+In the future (currently being developed):
 
-In the long term, we plan to adopt one of several different schemes for [[securely routing meta-data => https://leap.se/routing]].
+# The Bitmask client checks to see if the recipient supports delivery via Panoramix (anonymous mix network).
+** If supported, the client checks to see if the sender has permission to deliver anonymously to the recipient (via special delivery keys).
+** If delivery permission is granted, the email message will be directly delivered to the recipient's provider using Panoramix. In this case, the sender's provider will never see the email.
+# If Panoramix is not available, the Bitmask client connects to MX server of the sender's provider. This connection is authenticated using a X.509 client certificate stored by the client, a separate one for each sender email address.
+# If the client certificate matches the "From" field of the email, then the email is DKIM signed and relayed to the destination MX server.
 
 h2. Limitations
 
@@ -53,9 +103,11 @@ h2. Limitations
 * Because all data is synced, if a user has one of their devices compromised, then the attacker has access to all their data. This is obvious, but worth mentioning.
 * The user must keep a complete copy of their entire email storage on every device they use. In the future, we plan to support partial syncing for mobile devices.
 * We do not plan to support key revocation. Instead, we plan to migrate to shorter and shorter lived keys, as practical.
-* With the current implementation, a compromised or nefarious service provider can still gather incoming messages that are not encrypted and meta-data routing information. As more users and providers adopt secure email, many of these problems will go away.
+* With the current implementation, a compromised or nefarious service provider can still gather incoming messages that are not encrypted and meta-data routing information. For the future, we are working on a project called Panoramix that will allow for message routing that is anonymous and exposes zero meta-data information to the service provider (so long as both sender and recipient support Panoramix).
+* OpenPGP and S/MIME message encryption has no forward secrecy, although we do use PFS ciphers for StartTLS relay. In the future, we hope to add additional forms of message encryption, such as Axolotl.
+* With our current scheme of automatic key validation, there is a chance that a provider could endorse a bogus public key for a short period of time such that the holder of the correct key does not notice the subterfuge. In the future, we hope to add compatibility with CONIKS, which supports an cryptographic append-only log of all key endorsements and allows for strong auditing of these past endorsements.
 
-For more details, please see [[known limitations => limitations]].
+For more details, please see [[known limitations => https://leap.se/en/limitations]].
 
 h2. Related projects
 
diff --git a/pages/features/email/future notes b/pages/features/email/future notes
new file mode 100644
index 0000000..367ef5b
--- /dev/null
+++ b/pages/features/email/future notes
@@ -0,0 +1,16 @@
+
+h2. Long term benefits when two Bitmask compatible providers talk to one another
+
+One of the fundamental problems with email is that the meta-data routing information is exposed as cleartext. Encrypting a message with OpenPGP or S/MIME does nothing to help with this.
+
+The email protocol does support an optional method of securely relaying messages using TLS to encrypt the connection. This method, called StartTLS, is easily undermined by attackers and there is no good way for email providers to validate the authenticity of other servers (without relying on the problematic CA certificate authority system).
+
+For now, Bitmask addresses these problems with two enhancements when two compatible providers are talking to one another:
+
+* When relaying email, server keys are discovered and validated using DNSSEC/DANE.
+* For these providers, TLS with validated keys becomes required for all communication.
+
+This approach is effective against external network observers, but does not protect the meta-data from the service providers themselves. Also, it does not, by itself, protect against more advanced attacks involving timing and traffic analysis.
+
+In the long term, we plan to adopt one of several different schemes for [[securely routing meta-data => https://leap.se/routing]].
+