mirror of https://github.com/ctz/rustls
285 lines
12 KiB
Markdown
285 lines
12 KiB
Markdown
<p align="center">
|
|
<img width="460" height="300" src="https://raw.githubusercontent.com/rustls/rustls/main/admin/rustls-logo-web.png">
|
|
</p>
|
|
|
|
<p align="center">
|
|
Rustls is a modern TLS library written in Rust.
|
|
</p>
|
|
|
|
# Status
|
|
|
|
Rustls is used in production at many organizations and projects. We aim to maintain
|
|
reasonable API surface stability but the API may evolve as we make changes to accomodate
|
|
new features or performance improvements.
|
|
|
|
We have a [roadmap](ROADMAP.md) for our future plans. We also have [benchmarks](BENCHMARKING.md) to
|
|
prevent performance regressions and to let you evaluate rustls on your target hardware.
|
|
|
|
If you'd like to help out, please see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
[](https://github.com/rustls/rustls/actions/workflows/build.yml?query=branch%3Amain)
|
|
[](https://codecov.io/gh/rustls/rustls/)
|
|
[](https://docs.rs/rustls/)
|
|
[](https://discord.gg/MCSB76RU96)
|
|
|
|
## Changelog
|
|
|
|
The detailed list of changes in each release can be found at
|
|
https://github.com/rustls/rustls/releases.
|
|
|
|
# Documentation
|
|
|
|
https://docs.rs/rustls/
|
|
|
|
# Approach
|
|
|
|
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 by default.
|
|
|
|
## Current functionality (with default crate features)
|
|
|
|
* TLS1.2 and TLS1.3.
|
|
* ECDSA, Ed25519 or RSA server authentication by clients.
|
|
* ECDSA, Ed25519 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.
|
|
* ChaCha20-Poly1305 bulk encryption ([RFC7905](https://tools.ietf.org/html/rfc7905)).
|
|
* ALPN support.
|
|
* SNI support.
|
|
* Tunable fragment size 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](https://tools.ietf.org/html/rfc5077)).
|
|
* TLS1.3 resumption via tickets or session storage.
|
|
* TLS1.3 0-RTT data for clients.
|
|
* TLS1.3 0-RTT data for servers.
|
|
* Client authentication by clients.
|
|
* Client authentication by servers.
|
|
* Extended master secret support ([RFC7627](https://tools.ietf.org/html/rfc7627)).
|
|
* Exporters ([RFC5705](https://tools.ietf.org/html/rfc5705)).
|
|
* OCSP stapling by servers.
|
|
|
|
## Non-features
|
|
|
|
For reasons [explained in the manual](https://docs.rs/rustls/latest/rustls/manual/_02_tls_vulnerabilities/index.html),
|
|
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.
|
|
* TLS 1.2 protocol compression.
|
|
* Discrete-log Diffie-Hellman.
|
|
* Automatic protocol version downgrade.
|
|
* Using CA certificates directly to authenticate a server/client (often called "self-signed
|
|
certificates"). _Rustls' default certificate verifier does not support using a trust anchor as
|
|
both a CA certificate and an end-entity certificate in order to limit complexity and risk in
|
|
path building. While dangerous, all authentication can be turned off if required --
|
|
see the [example code](https://github.com/rustls/rustls/blob/992e2364a006b2e84a8cf6a7c3eaf0bdb773c9de/examples/src/bin/tlsclient-mio.rs#L318)_.
|
|
|
|
There are plenty of other libraries that provide these features should you
|
|
need them.
|
|
|
|
### Platform support
|
|
|
|
While Rustls itself is platform independent, by default it uses
|
|
[`ring`](https://crates.io/crates/ring) for implementing the cryptography in
|
|
TLS. As a result, rustls only runs on platforms
|
|
supported by `ring`. At the time of writing, this means 32-bit ARM, Aarch64 (64-bit ARM),
|
|
x86, x86-64, LoongArch64, 32-bit & 64-bit Little Endian MIPS, 32-bit PowerPC (Big Endian),
|
|
64-bit PowerPC (Big and Little Endian), 64-bit RISC-V, and s390x. We do not presently
|
|
support WebAssembly.
|
|
For more information, see [the supported `ring` target platforms][ring-target-platforms].
|
|
|
|
By providing a custom instance of the [`crypto::CryptoProvider`] struct, you
|
|
can replace all cryptography dependencies of rustls. This is a route to being portable
|
|
to a wider set of architectures and environments, or compliance requirements. See the
|
|
[`crypto::CryptoProvider`] documentation for more details.
|
|
|
|
Specifying `default-features = false` when depending on rustls will remove the
|
|
dependency on *ring*.
|
|
|
|
Rustls requires Rust 1.61 or later.
|
|
|
|
[ring-target-platforms]: https://github.com/briansmith/ring/blob/2e8363b433fa3b3962c877d9ed2e9145612f3160/include/ring-core/target.h#L18-L64
|
|
[crypto::CryptoProvider]: https://docs.rs/rustls/latest/rustls/crypto/trait.CryptoProvider.html
|
|
|
|
# Example code
|
|
|
|
Our [examples] directory contains demos that show how to handle I/O using the
|
|
[`stream::Stream`] helper, as well as more complex asynchronous I/O using [`mio`].
|
|
If you're already using Tokio for an async runtime you may prefer to use
|
|
[`tokio-rustls`] instead of interacting with rustls directly.
|
|
|
|
The [`mio`] based examples are the most complete, and discussed below. Users
|
|
new to Rustls may prefer to look at the simple client/server examples before
|
|
diving in to the more complex MIO examples.
|
|
|
|
[examples]: examples/
|
|
[`stream::Stream`]: https://docs.rs/rustls/latest/rustls/struct.Stream.html
|
|
[`mio`]: https://docs.rs/mio/latest/mio/
|
|
[`tokio-rustls`]: https://docs.rs/tokio-rustls/latest/tokio_rustls/
|
|
|
|
## Client example program
|
|
The MIO client example program is named `tlsclient-mio`. The interface looks like:
|
|
|
|
```tlsclient-mio
|
|
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 /.
|
|
|
|
If --cafile is not supplied, a built-in set of CA certificates
|
|
are used from the webpki-roots crate.
|
|
|
|
Usage:
|
|
tlsclient-mio [options] [--suite SUITE ...] [--proto PROTO ...] [--protover PROTOVER ...] <hostname>
|
|
tlsclient-mio (--version | -v)
|
|
tlsclient-mio (--help | -h)
|
|
|
|
Options:
|
|
-p, --port PORT Connect to PORT [default: 443].
|
|
--http Send a basic HTTP GET request for /.
|
|
--cafile CAFILE Read root certificates from CAFILE.
|
|
--auth-key KEY Read client authentication key from KEY.
|
|
--auth-certs CERTS Read client authentication certificates from CERTS.
|
|
CERTS must match up with KEY.
|
|
--protover VERSION Disable default TLS version list, and use
|
|
VERSION instead. May be used multiple times.
|
|
--suite SUITE Disable default cipher suite list, and use
|
|
SUITE instead. May be used multiple times.
|
|
--proto PROTOCOL Send ALPN extension containing PROTOCOL.
|
|
May be used multiple times to offer several protocols.
|
|
--no-tickets Disable session ticket support.
|
|
--no-sni Disable server name indication support.
|
|
--insecure Disable certificate verification.
|
|
--verbose Emit log output.
|
|
--max-frag-size M Limit outgoing messages to M bytes.
|
|
--version, -v Show tool version.
|
|
--help, -h Show this screen.
|
|
```
|
|
|
|
Some sample runs:
|
|
|
|
```
|
|
$ cargo run --bin tlsclient-mio -- --http mozilla-modern.badssl.com
|
|
HTTP/1.1 200 OK
|
|
Server: nginx/1.6.2 (Ubuntu)
|
|
Date: Wed, 01 Jun 2016 18:44:00 GMT
|
|
Content-Type: text/html
|
|
Content-Length: 644
|
|
(...)
|
|
```
|
|
|
|
or
|
|
|
|
```
|
|
$ cargo run --bin tlsclient-mio -- --http expired.badssl.com
|
|
TLS error: InvalidCertificate(Expired)
|
|
Connection closed
|
|
```
|
|
|
|
## Server example program
|
|
The MIO server example program is named `tlsserver-mio`. The interface looks like:
|
|
|
|
```tlsserver-mio
|
|
Runs a TLS server on :PORT. The default PORT is 443.
|
|
|
|
`echo' mode means the server echoes received data on each connection.
|
|
|
|
`http' mode means the server blindly sends a HTTP response on each
|
|
connection.
|
|
|
|
`forward' means the server forwards plaintext to a connection made to
|
|
localhost:fport.
|
|
|
|
`--certs' names the full certificate chain, `--key' provides the
|
|
RSA private key.
|
|
|
|
Usage:
|
|
tlsserver-mio --certs CERTFILE --key KEYFILE [--suite SUITE ...] [--proto PROTO ...] [--protover PROTOVER ...] [options] echo
|
|
tlsserver-mio --certs CERTFILE --key KEYFILE [--suite SUITE ...] [--proto PROTO ...] [--protover PROTOVER ...] [options] http
|
|
tlsserver-mio --certs CERTFILE --key KEYFILE [--suite SUITE ...] [--proto PROTO ...] [--protover PROTOVER ...] [options] forward <fport>
|
|
tlsserver-mio (--version | -v)
|
|
tlsserver-mio (--help | -h)
|
|
|
|
Options:
|
|
-p, --port PORT Listen on PORT [default: 443].
|
|
--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).
|
|
--key KEYFILE Read private key from KEYFILE. This should be a RSA
|
|
private key or PKCS8-encoded private key, in PEM format.
|
|
--ocsp OCSPFILE Read DER-encoded OCSP response from OCSPFILE and staple
|
|
to certificate. Optional.
|
|
--auth CERTFILE Enable client authentication, and accept certificates
|
|
signed by those roots provided in CERTFILE.
|
|
--crl CRLFILE ... Perform client certificate revocation checking using the DER-encoded
|
|
CRLFILE. May be used multiple times.
|
|
--require-auth Send a fatal alert if the client does not complete client
|
|
authentication.
|
|
--resumption Support session resumption.
|
|
--tickets Support tickets.
|
|
--protover VERSION Disable default TLS version list, and use
|
|
VERSION instead. May be used multiple times.
|
|
--suite SUITE Disable default cipher suite list, and use
|
|
SUITE instead. May be used multiple times.
|
|
--proto PROTOCOL Negotiate PROTOCOL using ALPN.
|
|
May be used multiple times.
|
|
--verbose Emit log output.
|
|
--version, -v Show tool version.
|
|
--help, -h Show this screen.
|
|
```
|
|
|
|
Here's a sample run; we start a TLS echo server, then connect to it with
|
|
`openssl` and `tlsclient-mio`:
|
|
|
|
```
|
|
$ cargo run --bin tlsserver-mio -- --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 | cargo run --bin tlsclient-mio -- --cafile test-ca/rsa/ca.cert -p 8443 localhost
|
|
hello world
|
|
^C
|
|
```
|
|
|
|
# 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.
|
|
|
|
# Project Membership
|
|
|
|
- Joe Birr-Pixton ([@ctz], Project Founder - full-time funded by [Prossimo])
|
|
- Dirkjan Ochtman ([@djc], Co-maintainer)
|
|
- Daniel McCarney ([@cpu], Co-maintainer - full-time funded by [Prossimo])
|
|
- Josh Aas ([@bdaehlie], Project Management)
|
|
|
|
[@ctz]: https://github.com/ctz
|
|
[@djc]: https://github.com/djc
|
|
[@cpu]: https://github.com/cpu
|
|
[@bdaehlie]: https://github.com/bdaehlie
|
|
[Prossimo]: https://www.memorysafety.org/initiative/rustls/
|
|
|
|
# Code of conduct
|
|
|
|
This project adopts the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct).
|
|
Please email rustls-mod@googlegroups.com to report any instance of misconduct, or if you
|
|
have any comments or questions on the Code of Conduct.
|