Skip to main content

quietquic_proto/
lib.rs

1// SPDX-License-Identifier: 0BSD
2//! Sans-IO core for quietquic.
3//!
4//! This crate performs no I/O, spawns no tasks, requires no async runtime, and
5//! never blocks or parks. The caller owns the socket and the clock and drives
6//! the state machine directly, which makes quietquic embeddable in a
7//! hand-rolled event loop — including the classic Unix reactor that calls
8//! `select()` with a zero timeout and has other work to do between passes.
9//! See `examples/poll_loop.rs` for the reference shape.
10//!
11//! The [`quietquic`](https://docs.rs/quietquic) crate is a thin tokio wrapper
12//! over this core; applications that want async/await should use that instead.
13//!
14//! # Threat model
15//!
16//! A server built on this core emits **zero bytes** in response to any packet
17//! that does not prove possession of a valid pre-shared key. Stated precisely:
18//!
19//! > **A datagram that fails the cloaking pre-filter queues nothing to send.**
20//!
21//! That is structural rather than a property of the caller's control flow.
22//! [`endpoint::Endpoint::handle_datagram`] runs the whole pre-filter — rate
23//! limiter, long-header parse, selector length, PSK selector match, freshness,
24//! anti-replay — and returns before a failing packet reaches quinn-proto at all,
25//! so there is nothing for [`endpoint::Endpoint::poll_transmit`] to hand back
26//! and an embedder cannot reply to an unauthorized peer even by mistake.
27//!
28//! Note what the invariant is *not* keyed on: it is not
29//! "[`outcome::DatagramOutcome::Dropped`] implies nothing was queued". A peer
30//! that has already proved PSK possession can be answered — the reachable case
31//! is a Version Negotiation reply to an authorized peer asking for a QUIC
32//! version we do not speak, which yields `Dropped` *and* a queued transmit. See
33//! [`outcome::DatagramOutcome::Dropped`].
34//!
35//! See the repository's `README.md` (`Threat Model`) for the full, honest
36//! boundaries — this defeats internet-wide scanning and casual DPI, but does
37//! NOT defeat global passive traffic analysis, sophisticated DPI that actively
38//! attempts `Initial` decryption on every flow, or a resource side-channel via
39//! a co-located service.
40
41pub mod config;
42pub mod conn;
43pub mod crypto;
44pub mod endpoint;
45pub mod freshness;
46pub mod initial_keys;
47pub mod outcome;
48pub mod ratelimit;
49pub mod replay;
50pub mod selector;
51pub mod testing;
52pub mod transport;