/quinn

Futures-based QUIC implementation in Rust

Primary LanguageRustApache License 2.0Apache-2.0

Quinn

Documentation Crates.io Build status codecov Chat License: MIT License: Apache 2.0

Quinn is an implementation of the QUIC transport protocol undergoing standardization by the IETF. It is suitable for experimental use. The implementation is split up into the state machine crate quinn-proto which performs no I/O internally and can be tested deterministically, and a high-level tokio-compatible API in quinn. See quinn/examples/ for usage.

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
  • Uses rustls for all TLS operations and ring for cryptography

Status

  • QUIC draft 17 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

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.