Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 3,938 Commits
.cargo		.cargo
.github		.github
bench		bench
docs		docs
fuzz		fuzz
perf		perf
quinn-proto		quinn-proto
quinn-udp		quinn-udp
quinn		quinn
.codecov.yml		.codecov.yml
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE-APACHE		LICENSE-APACHE
LICENSE-MIT		LICENSE-MIT
README.md		README.md
codecov.yml		codecov.yml
deny.toml		deny.toml
rustfmt.toml		rustfmt.toml

Repository files navigation

Quinn is a pure-Rust, async-compatible implementation of the IETFQUIC transport protocol.The project was founded byDirkjan Ochtman andBenjamin Saunders as a side project in 2018, and has seen more than30 releases since then. If you're using Quinn in a commercial setting, please considersponsoring the project.

Features

Simultaneous client/server operation
Ordered and unordered stream reads for improved performance
Works on stable Rust, tested on Linux, macOS and Windows
Pluggable cryptography, with a standard implementation backed byrustls andring
Application-layer datagrams for small, unreliable messages
Future-based async API
Minimum supported Rust version of 1.74.1

Overview

quinn: High-level async API based on tokio, seeexamples for usage. This will be used by most developers. (Basic benchmarks are included.)
quinn-proto: Deterministic state machine of the protocol which performsno I/O internally and is suitable for use with custom event loops (and potentially a C or C++ API).
quinn-udp: UDP sockets with ECN information tuned for the protocol.
bench: Benchmarks without any framework.
fuzz: Fuzz tests.

Getting Started

Examples

$ cargo run --example server ./$ cargo run --example client https://localhost:4433/Cargo.toml

This launches an HTTP 0.9 server on the loopback address serving the currentworking directory, with the client fetching./Cargo.toml. By default, theserver generates a self-signed certificate and stores it to disk, where theclient will automatically find and trust it.

Links

Talk atRustFest Paris (May 2018) presentation;slides;YouTube
Usageexamples
Guidebook

Usage Notes

Click to show the notes

Buffers

A Quinn endpoint corresponds to a single UDP socket, no matter how manyconnections are in use. Handling high aggregate data rates on a single endpointcan require a larger UDP buffer than is configured by default in mostenvironments. If you observe erratic latency and/or throughput over a stablenetwork link, consider increasing the buffer sizes used. For example, you couldadjust theSO_SNDBUF andSO_RCVBUF options of the UDP socket to be usedbefore passing it in to Quinn. Note that some platforms (e.g. Linux) requireelevated privileges or modified system configuration for a process to increaseits UDP buffer sizes.

Certificates

By default, Quinn clients validate the cryptographic identity of servers theyconnect to. This prevents an active, on-path attacker from interceptingmessages, but requires trusting some certificate authority. For many purposes,this can be accomplished by using certificates fromLet's Encryptfor servers, and relying on the default configuration for clients.

For some cases, including peer-to-peer, trust-on-first-use, deliberatelyinsecure applications, or any case where servers are not identified by domainname, this isn't practical. Arbitrary certificate validation logic can beimplemented by enabling thedangerous_configuration feature ofrustls andconstructing a QuinnClientConfig with an overridden certificate verifier byhand.

When operating your own certificate authority doesn't make sense,rcgencan be used to generate self-signed certificates on demand. To supporttrust-on-first-use, servers that automatically generate self-signed certificatesshould write their generated certificate to persistent storage and reuse it onfuture runs.

Contribution

All feedback welcome. Feel free to file bugs, requests for documentation andany other feedback to theissue tracker.

The quinn-proto test suite uses simulated IO for reproducibility and to avoidlong sleeps in certain timing-sensitive tests. If theSSLKEYLOGFILEenvironment variable is set, the tests will emit UDP packets for inspectionusing external protocol analyzers like Wireshark, and NSS-compatible key logsfor the client side of each connection will be written to the path specified inthe variable.

The minimum supported Rust version for published releases of ourcrates will always be at least 6 months old at the time of release.