Start using mdbook

mdbook/.gitignore

@@ -0,0 +1 @@
+book

mdbook/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Joseph Birr-Pixton"]
+language = "en"
+multilingual = false
+src = "src"
+title = "rustls Documentation"

mdbook/src/SUMMARY.md

@@ -0,0 +1,6 @@
+# Summary
+
+[Introduction](./intro.md)
+
+- [Review of implementation vulnerabilties](./impl-vulns.md)
+- [Review of TLS protocol vulnerabilties](./proto-vulns.md)

mdbook/src/impl-vulns.md

@@ -0,0 +1,69 @@
+# A review of implementation vulnerabilities
+
+An important part of engineering involves studying and learning from the mistakes of the past.
+It would be tremendously unfortunate to spend effort re-discovering and re-fixing the same
+vulnerabilities that were discovered in the past.
+
+## Memory safety
+
+Being written entirely in the safe-subset of Rust immediately offers us freedom from the entire
+class of memory safety vulnerabilities.  There are too many to exhaustively list, and there will
+certainly be more in the future.
+
+Examples:
+
+- Heartbleed [CVE-2014-0160](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-0160) (OpenSSL)
+- Memory corruption in ASN.1 decoder [CVE-2016-2108](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-2108) (OpenSSL)
+- Buffer overflow in read_server_hello [CVE-2014-3466](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-3466) (GnuTLS)
+
+## `goto fail`
+
+This is the name of a vulnerability in Apple Secure Transport [CVE-2014-1266](https://nvd.nist.gov/vuln/detail/CVE-2014-1266).
+This boiled down to the following code, which validates the server's signature on the key exchange:
+
+```
+    if ((err = SSLHashSHA1.update(&hashCtx, &serverRandom)) != 0)
+        goto fail;
+    if ((err = SSLHashSHA1.update(&hashCtx, &signedParams)) != 0)
+        goto fail;
+>       goto fail;
+    if ((err = SSLHashSHA1.final(&hashCtx, &hashOut)) != 0)
+        goto fail;
+```
+
+The marked line was duplicated, likely accidentally during a merge.  This meant
+the remaining part of the function (including the actual signature validation)
+was unconditionally skipped.
+
+Ultimately the one countermeasure to this type of bug is basic testing: that a
+valid signature returns success, and that an invalid one does not.  rustls
+has such testing, but this is really table stakes for security code.
+
+Further than this, though, we could consider that the *lack* of an error from
+this function is a poor indicator that the signature was valid.  rustls, instead,
+has zero-size and non-copyable types that indicate a particular signature validation
+has been performed.  These types can be thought of as *capabilities* originated only
+by designated signature verification functions -- such functions can then be a focus
+of manual code review.  Like capabilities, values of these types are otherwise unforgeable,
+and are communicable only by Rust's move semantics.
+
+Values of these types are threaded through the protocol state machine, leading to terminal
+states that look like:
+
+```
+struct ExpectTraffic {
+   (...)
+    _cert_verified: verify::ServerCertVerified,
+    _sig_verified: verify::HandshakeSignatureValid,
+    _fin_verified: verify::FinishedMessageVerified,
+}
+```
+
+Since this state requires a value of these types, it will be a compile-time error to
+reach that state without performing the requisite security-critical operations.
+
+This approach is not infallable, but it has zero runtime cost.
+
+## State machine attacks: EarlyCCS and SKIP
+
+

mdbook/src/intro.md

@@ -0,0 +1,9 @@
+# Introduction
+
+This documentation primarily aims to explain design decisions taken in rustls.
+It does this from a few aspects: how rustls attempts to avoid construction vulnerabilities
+that occured in other TLS libraries, how rustls attempts to avoid past TLS
+protocol vulnerabilities, and assorted advice for achieving common tasks with rustls.
+
+This is a separate concern from API documentation, which can be viewed on [docs.rs](https://docs.rs/rustls/).
+

mdbook/src/proto-vulns.md

@@ -0,0 +1,50 @@
+# A review of protocol vulnerabilities
+
+## CBC MAC-then-encrypt ciphersuites
+
+Back in 2000 [Bellare and Namprempre](https://eprint.iacr.org/2000/025) discussed how to make authenticated
+encryption by composing separate encryption and authentication primitives.  That paper included this table:
+
+| Composition Method | Privacy || Integrity ||
+|--------------------|---------||-----------||
+|| IND-CPA | IND-CCA | NM-CPA | INT-PTXT | INT-CTXT |
+| Encrypt-and-MAC | insecure | insecure | insecure | secure | insecure |
+| MAC-then-encrypt | secure | insecure | insecure | secure | insecure |
+| Encrypt-then-MAC | secure | secure | secure | secure | secure |
+
+One may assume from this fairly clear result that encrypt-and-MAC and MAC-then-encrypt compositions would be quickly abandoned
+in favour of the remaining proven-secure option.  But that didn't happen, not in TLSv1.1 (2006) nor in TLSv1.2 (2008).  Worse,
+both RFCs included incorrect advice on countermeasures for implementors, suggesting that the flaw was "not believed to be large
+enough to be exploitable".
+
+[Lucky 13](http://www.isg.rhul.ac.uk/tls/Lucky13.html) (2013) exploited this flaw and affected all implementations, including
+those written [after discovery](https://aws.amazon.com/blogs/security/s2n-and-lucky-13/). OpenSSL even had a
+[memory safety vulnerability in the fix for Lucky 13](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-2107), which
+gives a flavour of the kind of complexity required to remove the side channel.
+
+rustls does not implement CBC MAC-then-encrypt ciphersuites for these reasons.  TLS1.3 removed support for these
+ciphersuites in 2018.
+
+There are some further rejected options worth mentioning: [RFC7366](https://tools.ietf.org/html/rfc7366) defines
+Encrypt-then-MAC for TLS, but unfortunately cannot be negotiated without also supporting MAC-then-encrypt
+(clients cannot express "I offer CBC, but only EtM and not MtE").
+
+## BEAST
+
+## CRIME
+
+## Logjam
+
+## SWEET32
+
+## FREAK
+
+## DROWN
+
+## Poodle
+
+## GCM nonces
+
+## 3SHAKE / Renegotiation
+
+## RSA PKCS#1 encryption