Add manual

README.md

@@ -31,6 +31,8 @@ If you'd like to help out, please see [CONTRIBUTING.md](CONTRIBUTING.md).
     compatible with the client-offered ciphersuites.  Prior to this change
     it was likely that server key type switching would not work for clients
     that offer signature schemes mismatched with their ciphersuites.
+  - Add manual with goal-oriented documentation, and rationale for design
+    decisions.
 * 0.16.0 (2019-08-10):
   - Optimisation of read path for polled non-blocking IO.
   - Correct an omission in TLS1.3 middlebox compatibility mode, causing

rustls/src/lib.rs

@@ -307,3 +307,5 @@ pub use crate::verify::{ServerCertVerifier, ServerCertVerified,
 #[cfg_attr(docsrs, doc(cfg(feature = "dangerous_configuration")))]
 pub use crate::client::danger::DangerousClientConfig;
 
+/// This is the rustls manual.
+pub mod manual;

rustls/src/manual/features.rs

@@ -0,0 +1,50 @@
+/*!
+
+## Current features
+
+* TLS1.2 and TLS1.3.
+* ECDSA or RSA server authentication by clients.
+* ECDSA or RSA server authentication by servers.
+* Forward secrecy using ECDHE; with curve25519, nistp256 or nistp384 curves.
+* AES128-GCM and AES256-GCM bulk encryption, with safe nonces.
+* Chacha20Poly1305 bulk encryption.
+* ALPN support.
+* SNI support.
+* Tunable MTU to make TLS messages match size of underlying transport.
+* Optional use of vectored IO to minimise system calls.
+* TLS1.2 session resumption.
+* TLS1.2 resumption via tickets (RFC5077).
+* TLS1.3 resumption via tickets or session storage.
+* TLS1.3 0-RTT data for clients.
+* Client authentication by clients.
+* Client authentication by servers.
+* Extended master secret support (RFC7627).
+* Exporters (RFC5705).
+* OCSP stapling by servers.
+* SCT stapling by servers.
+* SCT verification by clients.
+
+## Possible future features
+
+* PSK support.
+* OCSP verification by clients.
+* Certificate pinning.
+
+## Non-features
+
+For reasons explained in the other sections of this manual, rustls does not
+and will not support:
+
+* SSL1, SSL2, SSL3, TLS1 or TLS1.1.
+* RC4.
+* DES or triple DES.
+* EXPORT ciphersuites.
+* MAC-then-encrypt ciphersuites.
+* Ciphersuites without forward secrecy.
+* Renegotiation.
+* Kerberos.
+* Compression.
+* Discrete-log Diffie-Hellman.
+* Automatic protocol version downgrade.
+
+*/

rustls/src/manual/howto.rs

@@ -0,0 +1,36 @@
+/*! # Customising private key usage
+
+By default rustls supports PKCS#8-format[^1] RSA or ECDSA keys, plus PKCS#1-format RSA keys.
+
+However, if your private key resides in a HSM, or in another process, or perhaps
+another machine, rustls has some extension points to support this:
+
+The main trait you must implement is [`sign::SigningKey`][signing_key]. The primary method here
+is [`choose_scheme`][choose_scheme] where you are given a set of [`SignatureScheme`s][sig_scheme] the client says
+it supports: you must choose one (or return `None` -- this aborts the handshake). Having
+done that, you return an implementation of the [`sign::Signer`][signer] trait.
+The [`sign()`][sign_method] performs the signature and returns it.
+
+(Unfortunately this is currently designed for keys with low latency access, like in a
+PKCS#11 provider, Microsoft CryptoAPI, etc. so is blocking rather than asynchronous.
+It's a TODO to make these and other extension points async.)
+
+Once you have these two pieces, configuring a server to use them involves, briefly:
+
+- packaging your `sign::SigningKey` with the matching certificate chain into a [`sign::CertifiedKey`][certified_key]
+- making a [`ResolvesServerCertUsingSNI`][cert_using_sni] and feeding in your `sign::CertifiedKey` for all SNI hostnames you want to use it for,
+- setting that as your `ServerConfig`'s [`cert_resolver`][cert_resolver]
+
+[signing_key]: ../../sign/trait.SigningKey.html
+[choose_scheme]: ../../sign/trait.SigningKey.html#tymethod.choose_scheme
+[sig_scheme]: ../../enum.SignatureScheme.html
+[signer]: ../../sign/trait.Signer.html
+[sign_method]: ../../sign/trait.Signer.html#tymethod.sign
+[certified_key]: ../../sign/struct.CertifiedKey.html
+[cert_using_sni]: ../../struct.ResolvesServerCertUsingSNI.html
+[cert_resolver]: ../../struct.ServerConfig.html#structfield.cert_resolver
+
+[^1]: For PKCS#8 it does not support password encryption -- there's not a meaningful threat
+      model addressed by this, and the encryption supported is typically extremely poor.
+
+*/

rustls/src/manual/implvulns.rs

@@ -0,0 +1,104 @@
+/*! # A review of TLS 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 infallible, but it has zero runtime cost.
+
+## State machine attacks: EarlyCCS and SMACK/SKIP/FREAK
+
+EarlyCCS [CVE-2014-0224](https://nvd.nist.gov/vuln/detail/CVE-2014-0224) was a vulnerability in OpenSSL
+found in 2014.  The TLS `ChangeCipherSpec` message would be processed at inappropriate times, leading
+to data being encrypted with the wrong keys (specifically, keys which were not secret).  This resulted
+from OpenSSL taking a *reactive* strategy to incoming messages ("when I get a message X, I should do Y")
+which allows it to diverge from the proper state machine under attacker control.
+
+[SMACK](https://mitls.org/pages/attacks/SMACK) is a similar suite of vulnerabilities found in JSSE,
+CyaSSL, OpenSSL, Mono and axTLS.  "SKIP-TLS" demonstrated that some implementations allowed handshake
+messages (and in one case, the entire handshake!) to be skipped leading to breaks in security.  "FREAK"
+found that some implementations incorrectly allowed export-only state transitions (ie, transitions that
+were only valid when an export ciphersuite was in use).
+
+rustls represents its protocol state machine carefully to avoid these defects.  We model the handshake,
+CCS and application data subprotocols in the same single state machine.  Each state in this machine is
+represented with a single struct, and transitions are modelled as functions that consume the current state
+plus one TLS message[^1] and return a struct representing the next state.  These functions fully validate
+the message type before further operations.
+
+A sample sequence for a full TLSv1.2 handshake by a client looks like:
+
+- `hs::ExpectServerHello` (nb. ClientHello is logically sent before this state); transition to `tls12::ExpectCertificate`
+- `tls12::ExpectCertificate`; transition to `tls12::ExpectServerKX`
+- `tls12::ExpectServerKX`; transition to `tls12::ExpectServerDoneOrCertReq`
+- `tls12::ExpectServerDoneOrCertReq`; delegates to `tls12::ExpectCertificateRequest` or `tls12::ExpectServerDone` depending on incoming message.
+  - `tls12::ExpectServerDone`; transition to `tls12::ExpectCCS`
+- `tls12::ExpectCCS`; transition to `tls12::ExpectFinished`
+- `tls12::ExpectFinished`; transition to `tls12::ExpectTraffic`
+- `tls12::ExpectTraffic`; terminal state; transitions to `tls12::ExpectTraffic`
+
+In the future we plan to formally prove that all possible transitions modelled in this system of types
+are correct with respect to the standard(s).  At the moment we rely merely on exhaustive testing.
+
+[^1]: a logical TLS message: post-decryption, post-fragmentation.
+
+
+*/

rustls/src/manual/mod.rs

@@ -0,0 +1,26 @@
+/*!
+
+This documentation primarily aims to explain design decisions taken in rustls.
+
+It does this from a few aspects: how rustls attempts to avoid construction errors
+that occured in other TLS libraries, how rustls attempts to avoid past TLS
+protocol vulnerabilities, and assorted advice for achieving common tasks with rustls.
+*/
+#![allow(non_snake_case)]
+
+/// This section discusses vulnerabilities in other TLS implementations, theorising their
+/// root cause and how we aim to avoid them in rustls.
+#[path = "implvulns.rs"]
+pub mod _01_impl_vulnerabilities;
+
+/// This section discusses vulnerabilities and design errors in the TLS protocol.
+#[path = "tlsvulns.rs"]
+pub mod _02_tls_vulnerabilities;
+
+/// This section collects together goal-oriented documentation.
+#[path = "howto.rs"]
+pub mod _03_howto;
+
+/// This section documents rustls itself: what protocol features are and are not implemented.
+#[path = "features.rs"]
+pub mod _04_features;