Quinn
Quinn is an implementation of the QUIC transport protocol undergoing
standardization by the IETF. It is suitable for experimental use. This repository
contains the following crates:
quinncontains a high-level async API based on tokio, see
quinn/examples/ for
usage. This will be used by most Rust developers. (Basic benchmarks are included.)quinn-protocontains a deterministic state machine of the protocol which performs
no I/O internally and is suitable for use with custom event loops (and potentially
a C or C++ API).quinn-h3contains an implementation of HTTP 3 and QPACK. It is split internally
in a deterministatic state machine and a tokio-based high-level async API.benchcontains some extra benchmarks without any framework.interopcontains tooling that helps the Quinn team run interoperability tests.
Quinn is the subject of a RustFest Paris (May 2018) presentation; you can
also get the slides (and the animation about head-of-line
blocking). Video of the talk is available on YouTube. Since this
presentation, Quinn has been merged with quicr, another Rust implementation.
All feedback welcome. Feel free to file bugs, requests for documentation and
any other feedback to the issue tracker.
Quinn was created and is maintained by Dirkjan Ochtman and Benjamin Saunders.
Features
- Simultaneous client/server operation
- Ordered and unordered reads for improved performance
- Works on stable Rust, tested on Linux, macOS and Windows
- Pluggable cryptography, with a standard implementation backed by
rustls and ring
Status
- QUIC draft 24 with TLS 1.3
- Cryptographic handshake
- Stream data w/ flow control and congestion control
- Connection close
- Stateless retry
- Explicit congestion notification
- Migration
- 0-RTT data
- Session resumption
- HTTP over QUIC
Usage Notes
Buffers
A Quinn endpoint corresponds to a single UDP socket, no matter how many
connections are in use. Handling high aggregate data rates on a single endpoint
can require a larger UDP buffer than is configured by default in most
environments. If you observe erratic latency and/or throughput over a stable
network link, consider increasing the buffer sizes used. For example, you could
adjust the SO_SNDBUF and SO_RCVBUF options of the UDP socket to be used
before passing it in to Quinn. Note that some platforms (e.g. Linux) require
elevated privileges or modified system configuration for a process to increase
its UDP buffer sizes.
Certificates
By default, Quinn clients validate the cryptographic identity of servers they
connect to. This prevents an active, on-path attacker from intercepting
messages, but requires trusting some certificate authority. For many purposes,
this can be accomplished by using certificates from Let's Encrypt
for servers, and relying on the default configuration for clients.
For some cases, including peer-to-peer, trust-on-first-use, deliberately
insecure applications, or any case where servers are not identified by domain
name, this isn't practical. Arbitrary certificate validation logic can be
implemented by enabling the dangerous_configuration feature of rustls and
constructing a Quinn ClientConfig with an overridden certificate verifier by
hand.
When operating your own certificate authority doesn't make sense, rcgen
can be used to generate self-signed certificates on demand. To support
trust-on-first-use, servers that automatically generate self-signed certificates
should write their generated certificate to persistent storage and reuse it on
future runs.
Running the Examples
$ cargo run --example server ./
$ cargo run --example client https://localhost:4433/Cargo.toml
This launches a HTTP 0.9 server on the loopback address serving the current
working directory, with the client fetching ./Cargo.toml. By default, the
server generates a self-signed certificate and stores it to disk, where the
client will automatically find and trust it.
Development
The quinn-proto test suite uses simulated IO for reproducibility and to avoid
long sleeps in certain timing-sensitive tests. If the SSLKEYLOGFILE
environment variable is set, the tests will emit UDP packets for inspection
using external protocol analyzers like Wireshark, and NSS-compatible key logs
for the client side of each connection will be written to the path specified in
the variable.