2016-05-30 20:34:05 +00:00
|
|
|
# Rustls
|
2017-12-31 20:30:44 +00:00
|
|
|
Rustls is a modern TLS library written in Rust. It's pronounced 'rustles'.
|
2016-05-30 20:34:05 +00:00
|
|
|
It uses [*ring*](https://github.com/briansmith/ring) for cryptography
|
|
|
|
and [libwebpki](https://github.com/briansmith/webpki) for certificate
|
|
|
|
verification.
|
|
|
|
|
|
|
|
# Status
|
2016-09-17 18:42:32 +00:00
|
|
|
Rustls is currently in development and hence unstable. [Here's what I'm working on now](https://github.com/ctz/rustls/projects/1).
|
2016-05-30 20:34:05 +00:00
|
|
|
|
|
|
|
[![Build Status](https://travis-ci.org/ctz/rustls.svg?branch=master)](https://travis-ci.org/ctz/rustls)
|
2016-09-25 18:47:19 +00:00
|
|
|
[![Coverage Status](https://coveralls.io/repos/github/ctz/rustls/badge.svg?branch=master)](https://coveralls.io/github/ctz/rustls?branch=master)
|
|
|
|
[![Documentation](https://docs.rs/rustls/badge.svg)](https://docs.rs/rustls/)
|
2016-05-30 20:34:05 +00:00
|
|
|
|
2016-09-27 20:44:33 +00:00
|
|
|
## Release history:
|
|
|
|
|
2018-01-06 22:44:37 +00:00
|
|
|
* 0.12.0 (2018-01-06):
|
2017-12-31 20:30:44 +00:00
|
|
|
- New API for learning negotiated cipher suite.
|
|
|
|
- Move TLS1.3 support from draft 18 to 22.
|
|
|
|
- Allow server-side MTU configuration.
|
|
|
|
- Tested against latest BoringSSL test suite.
|
|
|
|
- Support RFC5705 exporters.
|
|
|
|
- Provide `ResolvesServerCertUsingSNI` for doing SNI-based
|
|
|
|
certificate switching.
|
|
|
|
- Allow disabling SNI extension on clients, for use with
|
|
|
|
custom server certificate verifiers where the hostname
|
|
|
|
may not make sense.
|
|
|
|
- DNS names are now typesafe, using `webpki::DNSName`.
|
|
|
|
- Update dependencies.
|
2017-08-28 17:38:47 +00:00
|
|
|
* 0.11.0 (2017-08-28):
|
|
|
|
- New server API for learning requested SNI name.
|
|
|
|
- Server now checks selected certificate for validity.
|
|
|
|
- Remove time crate dependency.
|
|
|
|
- Follow webpki interface changes.
|
|
|
|
- Update dependencies.
|
2017-08-12 20:31:10 +00:00
|
|
|
* 0.10.0 (2017-08-12):
|
|
|
|
- Request and verify SCTs using sct crate. This doesn't happen
|
|
|
|
unless you pass in some certificate transparency logs -- example code
|
|
|
|
does this.
|
|
|
|
- Request OCSP stapled response and pass to cert verifier.
|
|
|
|
Note that OCSP verification is not implemented, but this is the public
|
|
|
|
API public change required to support this.
|
|
|
|
- Allow OCSP and SCT stapling for servers.
|
|
|
|
- Refactor handshake state machines.
|
|
|
|
- Bind verifications to final state -- note API change for custom cert
|
|
|
|
verification.
|
2017-06-16 20:37:31 +00:00
|
|
|
* 0.9.0 (2017-06-16):
|
|
|
|
- Update dependencies.
|
|
|
|
- Add IO helper function (`complete_io`) to `rustls::Session`.
|
|
|
|
- Add blocking stream type -- `rustls::Stream` -- to ease use on top
|
|
|
|
of blocking sockets.
|
2017-05-14 20:16:21 +00:00
|
|
|
* 0.8.0 (2017-05-14):
|
|
|
|
- Add `dangerous_configuration` feature for unsafe features.
|
|
|
|
* 0.7.0 (2017-05-08):
|
2017-05-08 18:53:42 +00:00
|
|
|
- Update dependencies.
|
2017-05-14 20:16:21 +00:00
|
|
|
* 0.6.0 (2017-05-06):
|
2017-05-06 18:25:32 +00:00
|
|
|
- Update dependencies.
|
|
|
|
- Expose ring's new support for PKCS#8-format private keys.
|
|
|
|
- New API for applying limitation to internal buffer sizes.
|
2017-05-14 20:16:21 +00:00
|
|
|
* 0.5.8 (2017-03-16):
|
2017-03-16 20:56:02 +00:00
|
|
|
- Fix build on later rustc.
|
2017-05-14 20:16:21 +00:00
|
|
|
* 0.5.7 (2017-02-27):
|
2017-02-27 19:30:00 +00:00
|
|
|
- No changes from 0.5.6; republished with nightly cargo for category support.
|
2017-05-14 20:16:21 +00:00
|
|
|
* 0.5.6 (2017-02-19):
|
2017-02-19 09:18:30 +00:00
|
|
|
- RFC7627 extended master secret support
|
|
|
|
- Assorted documentation improvements
|
2017-05-14 20:16:21 +00:00
|
|
|
* 0.5.5 (2017-02-03):
|
2017-02-03 19:41:53 +00:00
|
|
|
- Crate categories.
|
|
|
|
- Protocol errors now permanent for given session.
|
|
|
|
- Exposed `ResolvesServerCert` trait for customising certification
|
|
|
|
selection.
|
|
|
|
- Exposed `SignatureScheme` enum.
|
2017-05-14 20:16:21 +00:00
|
|
|
* 0.5.4 (2017-01-26):
|
2017-01-26 22:38:32 +00:00
|
|
|
- First release with TLS1.3-draft-18 support.
|
|
|
|
- More performance improvements (now ~15Gbps per core).
|
|
|
|
- New API to learn version of negotiated connection.
|
2017-05-14 20:16:21 +00:00
|
|
|
* 0.5.0 (2016-09-27):
|
2016-09-27 20:44:33 +00:00
|
|
|
- Tickets.
|
|
|
|
- Coverage testing.
|
|
|
|
- Benchmarking.
|
|
|
|
- Massive performance improvements (from ~1Gbps to ~6Gbps per core).
|
|
|
|
- OSX support.
|
|
|
|
- Minor API corrections and additional testing.
|
|
|
|
|
2016-06-21 00:49:25 +00:00
|
|
|
# Documentation
|
2016-08-28 21:33:19 +00:00
|
|
|
Lives here: https://docs.rs/rustls/
|
2016-06-21 00:49:25 +00:00
|
|
|
|
2016-05-30 20:34:05 +00:00
|
|
|
# Approach
|
2016-07-03 11:41:33 +00:00
|
|
|
Rustls is a TLS library that aims to provide a good level of cryptographic security,
|
|
|
|
requires no configuration to achieve that security, and provides no unsafe features or
|
|
|
|
obsolete cryptography.
|
|
|
|
|
|
|
|
## Current features
|
|
|
|
|
2017-12-03 15:50:25 +00:00
|
|
|
* TLS1.2 and TLS1.3 (draft 22) only.
|
2016-07-03 11:41:33 +00:00
|
|
|
* ECDSA or RSA server authentication by clients.
|
|
|
|
* 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.
|
2017-01-30 21:22:07 +00:00
|
|
|
* TLS1.2 session resumption.
|
|
|
|
* TLS1.2 resumption via tickets (RFC5077).
|
|
|
|
* TLS1.3 resumption via tickets.
|
2016-08-14 20:01:37 +00:00
|
|
|
* Client authentication by clients.
|
|
|
|
* Client authentication by servers.
|
2017-02-19 09:18:30 +00:00
|
|
|
* Extended master secret support (RFC7627).
|
2017-12-10 18:51:01 +00:00
|
|
|
* Exporters (RFC5705).
|
2017-07-16 16:25:39 +00:00
|
|
|
* OCSP stapling by servers.
|
|
|
|
* SCT stapling by servers.
|
|
|
|
* SCT verification by clients.
|
2016-07-03 11:41:33 +00:00
|
|
|
|
|
|
|
## Possible future features
|
|
|
|
|
|
|
|
* ECDSA server authentication by servers.
|
|
|
|
* PSK support.
|
2017-07-16 16:25:39 +00:00
|
|
|
* OCSP verification by clients.
|
2016-07-03 11:41:33 +00:00
|
|
|
* Certificate pinning.
|
|
|
|
|
|
|
|
## Non-features
|
|
|
|
|
|
|
|
The following things are broken, obsolete, badly designed, underspecified,
|
|
|
|
dangerous and/or insane. Rustls does 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.
|
|
|
|
* AES-GCM with unsafe nonces.
|
|
|
|
|
|
|
|
There are plenty of other libraries that provide these features should you
|
|
|
|
need them.
|
2016-05-30 20:34:05 +00:00
|
|
|
|
2016-07-03 12:09:48 +00:00
|
|
|
# Example code
|
2016-11-08 14:35:53 +00:00
|
|
|
There are two example programs which use
|
|
|
|
[mio](https://github.com/carllerche/mio) to do asynchronous IO.
|
2016-05-30 20:34:05 +00:00
|
|
|
|
2016-07-03 11:41:33 +00:00
|
|
|
## Client example program
|
|
|
|
The client example program is named `tlsclient`. The interface looks like:
|
2016-05-30 20:34:05 +00:00
|
|
|
|
2016-09-11 16:51:51 +00:00
|
|
|
```tlsclient
|
2016-07-03 11:41:33 +00:00
|
|
|
Connects to the TLS server at hostname:PORT. The default PORT
|
|
|
|
is 443. By default, this reads a request from stdin (to EOF)
|
|
|
|
before making the connection. --http replaces this with a
|
|
|
|
basic HTTP GET request for /.
|
|
|
|
|
2016-08-28 14:03:04 +00:00
|
|
|
If --cafile is not supplied, a built-in set of CA certificates
|
|
|
|
are used from the webpki-roots crate.
|
2016-07-03 11:41:33 +00:00
|
|
|
|
|
|
|
Usage:
|
2016-09-11 17:12:25 +00:00
|
|
|
tlsclient [options] [--suite SUITE ...] [--proto PROTO ...] <hostname>
|
2016-09-11 16:51:51 +00:00
|
|
|
tlsclient (--version | -v)
|
|
|
|
tlsclient (--help | -h)
|
2016-07-03 11:41:33 +00:00
|
|
|
|
|
|
|
Options:
|
2016-09-11 16:51:51 +00:00
|
|
|
-p, --port PORT Connect to PORT [default: 443].
|
2016-07-03 11:41:33 +00:00
|
|
|
--http Send a basic HTTP GET request for /.
|
|
|
|
--cafile CAFILE Read root certificates from CAFILE.
|
2016-08-28 14:03:04 +00:00
|
|
|
--auth-key KEY Read client authentication key from KEY.
|
|
|
|
--auth-certs CERTS Read client authentication certificates from CERTS.
|
|
|
|
CERTS must match up with KEY.
|
2016-07-03 11:41:33 +00:00
|
|
|
--suite SUITE Disable default cipher suite list, and use
|
2016-09-11 17:12:25 +00:00
|
|
|
SUITE instead. May be used multiple times.
|
2016-07-03 11:41:33 +00:00
|
|
|
--proto PROTOCOL Send ALPN extension containing PROTOCOL.
|
2016-09-11 17:12:25 +00:00
|
|
|
May be used multiple times to offer serveral protocols.
|
2016-07-03 11:41:33 +00:00
|
|
|
--cache CACHE Save session cache to file CACHE.
|
2016-09-11 16:51:51 +00:00
|
|
|
--no-tickets Disable session ticket support.
|
2017-08-12 20:31:10 +00:00
|
|
|
--insecure Disable certificate verification.
|
2016-07-03 11:41:33 +00:00
|
|
|
--verbose Emit log output.
|
|
|
|
--mtu MTU Limit outgoing messages to MTU bytes.
|
2016-09-11 16:51:51 +00:00
|
|
|
--version, -v Show tool version.
|
|
|
|
--help, -h Show this screen.
|
2016-07-03 11:41:33 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Some sample runs:
|
|
|
|
|
|
|
|
```
|
|
|
|
$ ./tlsclient --http mozilla-modern.badssl.com
|
2016-06-01 18:41:19 +00:00
|
|
|
HTTP/1.1 200 OK
|
2016-05-30 20:34:05 +00:00
|
|
|
Server: nginx/1.6.2 (Ubuntu)
|
2016-06-01 18:41:19 +00:00
|
|
|
Date: Wed, 01 Jun 2016 18:44:00 GMT
|
2016-05-30 20:34:05 +00:00
|
|
|
Content-Type: text/html
|
|
|
|
Content-Length: 644
|
2016-07-03 11:41:33 +00:00
|
|
|
(...)
|
2016-05-30 20:34:05 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
or
|
|
|
|
|
|
|
|
```
|
2016-06-01 18:41:19 +00:00
|
|
|
$ ./target/debug/examples/tlsclient --http expired.badssl.com
|
|
|
|
TLS error: WebPKIError(CertExpired)
|
|
|
|
Connection closed
|
2016-05-30 20:34:05 +00:00
|
|
|
```
|
|
|
|
|
2016-07-03 11:41:33 +00:00
|
|
|
## Server example program
|
|
|
|
The server example program is named `tlsserver`. The interface looks like:
|
|
|
|
|
2016-09-11 16:51:51 +00:00
|
|
|
```tlsserver
|
2016-07-03 11:41:33 +00:00
|
|
|
Runs a TLS server on :PORT. The default PORT is 443.
|
|
|
|
|
|
|
|
`echo' mode means the server echoes received data on each connection.
|
|
|
|
|
2017-08-12 20:31:10 +00:00
|
|
|
`http' mode means the server blindly sends a HTTP response on each
|
|
|
|
connection.
|
2016-07-03 11:41:33 +00:00
|
|
|
|
|
|
|
`forward' means the server forwards plaintext to a connection made to
|
|
|
|
localhost:fport.
|
|
|
|
|
2017-08-12 20:31:10 +00:00
|
|
|
`--certs' names the full certificate chain, `--key' provides the
|
|
|
|
RSA private key.
|
2016-07-03 11:41:33 +00:00
|
|
|
|
|
|
|
Usage:
|
2016-09-11 17:12:25 +00:00
|
|
|
tlsserver --certs CERTFILE --key KEYFILE [--suite SUITE ...] [--proto PROTO ...] [options] echo
|
|
|
|
tlsserver --certs CERTFILE --key KEYFILE [--suite SUITE ...] [--proto PROTO ...] [options] http
|
|
|
|
tlsserver --certs CERTFILE --key KEYFILE [--suite SUITE ...] [--proto PROTO ...] [options] forward <fport>
|
2016-09-11 16:51:51 +00:00
|
|
|
tlsserver (--version | -v)
|
|
|
|
tlsserver (--help | -h)
|
2016-07-03 11:41:33 +00:00
|
|
|
|
|
|
|
Options:
|
2016-09-11 16:51:51 +00:00
|
|
|
-p, --port PORT Listen on PORT [default: 443].
|
2016-07-03 11:41:33 +00:00
|
|
|
--certs CERTFILE Read server certificates from CERTFILE.
|
|
|
|
This should contain PEM-format certificates
|
|
|
|
in the right order (the first certificate should
|
|
|
|
certify KEYFILE, the last should be a root CA).
|
2016-09-11 16:51:51 +00:00
|
|
|
--key KEYFILE Read private key from KEYFILE. This should be a RSA
|
2017-08-12 20:31:10 +00:00
|
|
|
private key or PKCS8-encoded private key, in PEM format.
|
|
|
|
--ocsp OCSPFILE Read DER-encoded OCSP response from OCSPFILE and staple
|
|
|
|
to certificate. Optional.
|
2016-08-28 14:03:04 +00:00
|
|
|
--auth CERTFILE Enable client authentication, and accept certificates
|
|
|
|
signed by those roots provided in CERTFILE.
|
|
|
|
--require-auth Send a fatal alert if the client does not complete client
|
|
|
|
authentication.
|
2016-09-11 16:51:51 +00:00
|
|
|
--resumption Support session resumption.
|
2016-09-20 01:15:26 +00:00
|
|
|
--tickets Support tickets.
|
2016-07-03 11:41:33 +00:00
|
|
|
--suite SUITE Disable default cipher suite list, and use
|
2016-09-11 17:12:25 +00:00
|
|
|
SUITE instead. May be used multiple times.
|
2016-07-03 11:41:33 +00:00
|
|
|
--proto PROTOCOL Negotiate PROTOCOL using ALPN.
|
2016-09-11 17:12:25 +00:00
|
|
|
May be used multiple times.
|
2016-07-03 11:41:33 +00:00
|
|
|
--verbose Emit log output.
|
2016-09-11 16:51:51 +00:00
|
|
|
--version, -v Show tool version.
|
|
|
|
--help, -h Show this screen.
|
2016-07-03 11:41:33 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Here's a sample run; we start a TLS echo server, then connect to it with
|
|
|
|
openssl and tlsclient:
|
|
|
|
|
|
|
|
```
|
|
|
|
$ ./tlsserver --certs test-ca/rsa/end.fullchain --key test-ca/rsa/end.rsa -p 8443 echo &
|
|
|
|
$ echo hello world | openssl s_client -ign_eof -quiet -connect localhost:8443
|
|
|
|
depth=2 CN = ponytown RSA CA
|
|
|
|
verify error:num=19:self signed certificate in certificate chain
|
|
|
|
hello world
|
|
|
|
^C
|
|
|
|
$ echo hello world | ./tlsclient --cafile test-ca/rsa/ca.cert -p 8443 localhost
|
|
|
|
hello world
|
|
|
|
^C
|
|
|
|
```
|
|
|
|
|
2016-06-19 16:42:57 +00:00
|
|
|
# License
|
|
|
|
|
|
|
|
Rustls is distributed under the following three licenses:
|
|
|
|
|
|
|
|
- Apache License version 2.0.
|
|
|
|
- MIT license.
|
|
|
|
- ISC license.
|
|
|
|
|
|
|
|
These are included as LICENSE-APACHE, LICENSE-MIT and LICENSE-ISC
|
|
|
|
respectively. You may use this software under the terms of any
|
|
|
|
of these licenses, at your option.
|
|
|
|
|