add security.md and clean up README

README.md

@@ -17,16 +17,25 @@ I am trying to:
 * **Not** make a totally unhackable, NSA-proof server.
 * **Not** make something customizable by power users.
 
-The long-term goal is to have this be a one-click email appliance with *no* user-configurable setup options.
-
-For more background, see [The Rationale](https://github.com/mail-in-a-box/mailinabox/wiki).
-
 This setup is what has been powering my own personal email since September 2013.
 
 The Box
 -------
 
-Mail-in-a-Box turns a fresh Ubuntu 14.04 LTS 64-bit machine into a working mail server, including SMTP ([postfix](http://www.postfix.org/)), IMAP ([dovecot](http://dovecot.org/)), Exchange ActiveSync ([z-push](https://github.com/fmbiete/Z-Push-contrib)), webmail ([Roundcube](http://roundcube.net/)), spam filtering ([spamassassin](https://spamassassin.apache.org/)), greylisting ([postgrey](http://postgrey.schweikert.ch/)), CardDAV/CalDAV ([ownCloud](http://owncloud.org/)), DNS, [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework), DKIM ([OpenDKIM](http://www.opendkim.org/)), [DMARC](https://en.wikipedia.org/wiki/DMARC), [DNSSEC](https://en.wikipedia.org/wiki/DNSSEC), [DANE TLSA](https://en.wikipedia.org/wiki/DNS-based_Authentication_of_Named_Entities), [SSHFP](https://tools.ietf.org/html/rfc4255), and basic system services like a firewall, intrusion protection, and setting the system clock.
+Mail-in-a-Box turns a fresh Ubuntu 14.04 LTS 64-bit machine into a working mail server by installing and configuring various components.
+
+It is a one-click email appliance (see the [setup guide](https://mailinabox.email/guide.html)). There are no user-configurable setup options. It "just works".
+
+The components installed are:
+
+* SMTP ([postfix](http://www.postfix.org/)), IMAP ([dovecot](http://dovecot.org/)), CardDAV/CalDAV ([ownCloud](http://owncloud.org/)), Exchange ActiveSync ([z-push](https://github.com/fmbiete/Z-Push-contrib))
+* Webmail ([Roundcube](http://roundcube.net/)), static website hosting ([nginx](http://nginx.org/))
+* Spam filtering ([spamassassin](https://spamassassin.apache.org/)), greylisting ([postgrey](http://postgrey.schweikert.ch/))
+* DNS ([nsd4](http://www.nlnetlabs.nl/projects/nsd/)) with [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework), DKIM ([OpenDKIM](http://www.opendkim.org/)), [DMARC](https://en.wikipedia.org/wiki/DMARC), [DNSSEC](https://en.wikipedia.org/wiki/DNSSEC), [DANE TLSA](https://en.wikipedia.org/wiki/DNS-based_Authentication_of_Named_Entities), and [SSHFP](https://tools.ietf.org/html/rfc4255) records automatically set
+* Firewall ([ufw](https://launchpad.net/ufw)), intrusion protection ([fail2ban](http://www.fail2ban.org/wiki/index.php/Main_Page))
+* A control panel and API for adding/removing mail users, aliases, custom DNS records, etc. and system monitoring.
+
+For more information on how Mail-in-a-Box handles your privacy, see the [security details page](security.md).
 
 Authenticity
 ------------
@@ -62,5 +71,6 @@ The History
 -----------
 
 * In 2007 I wrote a relatively popular Mozilla Thunderbird extension that added client-side SPF and DKIM checks to mail to warn users about possible phishing: [add-on page](https://addons.mozilla.org/en-us/thunderbird/addon/sender-verification-anti-phish/), [source](https://github.com/JoshData/thunderbird-spf).
+* In August 2013 I began Mail-in-a-Box by combining my own mail server configuration with the setup in ["NSA-proof your email in 2 hours"](http://sealedabstract.com/code/nsa-proof-your-e-mail-in-2-hours/) and making the setup steps reproducible with bash scripts.
 * Mail-in-a-Box was a semifinalist in the 2014 [Knight News Challenge](https://www.newschallenge.org/challenge/2014/submissions/mail-in-a-box), but it was not selected as a winner.
 * Mail-in-a-Box hit the front page of Hacker News in [April](https://news.ycombinator.com/item?id=7634514) and [September](https://news.ycombinator.com/item?id=8276171) 2014.

security.md

@@ -0,0 +1,61 @@
+Mail-in-a-Box Security Guide
+============================
+
+Mail-in-a-Box turns a fresh Ubuntu 14.04 LTS 64-bit machine into a mail server appliance by installing and configuring various components.
+
+This page documents the security features of Mail-in-a-Box. The term “box” is used below to mean a configured Mail-in-a-Box.
+
+Threat Model
+------------
+
+Nothing is perfectly secure, and an adversary with sufficient resources can always penetrate a system.
+
+The primary goal of Mail-in-a-Box is to make deploying a good mail server easy, so we balance ― as everyone does ― privacy and security concerns with the practicality of actually deploying the system. That means we make certain assumptions about adversaries. We assume that adversaries . . .
+
+* Do not have physical access to the box (i.e., we do not aim to protect the box from physical access).
+* Have not been given Unix accounts on the box (i.e., we assume all users with shell access are trusted).
+
+On the other hand, we do assume that adversaries are performing passive surveillance and, possibly, active man-in-the-middle attacks. And so:
+
+* User credentials are always sent through SSH/TLS, never in the clear.
+* Outbound mail is sent with the highest level of TLS possible (more on that below).
+
+User Credentials
+----------------
+
+The box's administrator and its (non-administrative) mail users must sometimes communicate their credentials to the box.
+
+### Console access via SSH
+
+Console access (e.g. via SSH) is configured by the system image used to create the box, typically from by a cloud virtual machine provider (e.g. Digital Ocean). Mail-in-a-Box does not set any console access settings, although it will warn the administrator in the System Status Checks if password-based login is turned on.
+
+The [setup guide video](https://mailinabox.email/) explains how to verify the host key fingerprint on first login. If DNSSEC is enabled at the box's domain name's registrar, the SSHFP record that the box automatically puts into DNS can also be used to verify the host key fingerprint by setting `VerifyHostKeyDNS yes` in your `ssh/.config` file or by logging in with `ssh -o VerifyHostKeyDNS=yes`.
+
+### Other services behind TLS
+
+Other services are protected by TLS:
+
+* SMTP Submission (port 587). Mail users submit outbound mail through SMTP with STARTTLS on port 587.
+* IMAP/POP (ports 993, 995). Mail users check for incoming mail through IMAP or POP over TLS.
+* HTTPS (port 443). Webmail, the Echange/ActiveSync protocol, the administrative control panel, and any static hosted websites are accessed over HTTPS.
+
+These services all follow these rules:
+
+* All of the services only offer TLSv1, TLSv1.1 and TLSv1.2 (the older SSL protocols are not offered).
+* No services offer export-grade ciphers, the anonymous DH/ECDH algorithms (aNULL), or clear-text ciphers (eNULL).
+* The minimum cipher key length offered is 112 bits. Diffie-Hellman ciphers use a 2048-bit key.
+* The box provides a self-signed certificate by default. The [setup guide](https://mailinabox.email/guide.html) explains how to verify the certificate fingerprint on first login. Users are encouraged to replace the certificate with a proper CA-signed one, and when using the CSR provided by the box the certificates will use a SHA-2 hash.
+
+Additionally:
+
+* SMTP Submission (port 587) will not accept user credentials without STARTTLS. The minimum cipher key length is 128 bits.
+* HTTPS (port 443): The HTTPS Strict Transport Security header is set. A redirect from HTTP to HTTPS is offered. The [Qualys SSL Labs test](https://www.ssllabs.com/ssltest) should report an A+ grade.
+
+For more details, see the [output of SSLyze stored in github](tests/tls_results.txt).
+
+Supported clients:
+
+The cipher and protocol selection are chosen to support the following clients:
+
+* For HTTPS: Firefox 1, Chrome 1, IE 7, Opera 5, Safari 1, Windows XP IE8, Android 2.3, Java 7.
+* For other protocols: TBD.