DOCSEARCHbyAlgolia
Submit Docs

s2n-quic Documentation

repository·main·Indexed 23 days ago

https://github.com/aws/s2n-quic

A high-performance, highly configurable Rust implementation of the IETF QUIC protocol. It features a provider-based architecture, support for CUBIC and BBRv2 congestion control, and Datagram Packetization Layer Path Maximum Transmission Unit Discovery (DPLPMTUD) for jumbo frame support. The project includes the s2n-codec internal crate for safe encoding/decoding and a dcQUIC Wireshark plugin for packet dissection.

Tokens
27.2K
Snippets
60
Records
179
Agent score
80%

What's inside s2n-quic

  1. Overview of s2n-quic-crypto

    main

    The s2n-quic-crypto crate provides abstractions over libcrypto operations specifically required for implementing the QUIC protocol.

    WARNING: This crate is not intended for general-purpose use outside of the s2n-quic project. The interface is not guaranteed to be stable.

  3. Overview of quic-transport components

    main

    The quic-transport module provides the core runtime components for QUIC data transmission. It is composed of three primary abstractions:

    • Streams: Used for transferring data between client and server. Multiple streams can be multiplexed over a single connection.
    • Connections: Represents the logical connection between two peers.
    • Endpoints: The entry point into the QUIC stack on a host, responsible for the low-level receiving and sending of UDP packets.

    Note: This is an internal crate used by s2n-quic. The API is currently unstable and is not intended for direct use by external consumers.

  5. Integrate rustls as an s2n-quic TLS provider

    main
    The s2n-quic-rustls crate provides an integration layer that allows you to use rustls as the TLS provider for s2n-quic. This enables s2n-quic to leverage the security and performance characteristics of the rustls library for QUIC connections.

  6. Use s2n-events for boilerplate event generation

    main

    s2n-events is a library designed to be consumed by an event generation program within a project. It automates the creation of boilerplate code for event types and traits based on project-specific configuration.

    Instead of manually implementing complex event requirements, you can use a generator (like the event-generator crate found in this repository) to scan Rust files for event definitions and generate a single, audited, and IDE-friendly Rust file containing:

    • Subscriber trait implementations (including on_{event_name} callbacks).
    • Publisher trait implementations.
    • Event trait implementations.
    • #[non_exhaustive] attributes to ensure forward compatibility.
    • Builder types for constructing events externally.
    • Logic for forwarding events to child-subscribers.
    • Integration with built-in subscribers (e.g., tracing, serde).
    • Test subscriber counters.

  9. Integrate s2n-tls as an s2n-quic TLS provider

    main
    The s2n-quic-tls crate provides the integration layer required to use s2n-tls as the TLS provider within the s2n-quic ecosystem. This allows s2n-quic implementations to leverage the security and performance of s2n-tls for QUIC connection security.

  10. Use s2n-quic-tls-default for platform-aware TLS selection

    main
    The s2n-quic-tls-default crate provides a mechanism to automatically select the default TLS provider for s2n-quic based on the capabilities and support of the current platform. Use this crate when you want to ensure optimal TLS provider selection without manually configuring specific providers for different operating systems or environments.

  11. Understand how incoming streams are processed and validated

    main

    When a new stream is accepted, the following lifecycle occurs:

    1. Acceptance: The acceptor calls accept() up to 2x the per-worker stream queue capacity. Streams are enqueued into a queue (capacity is the application-configured backlog, typically SOMAXCONN, divided by the number of workers). If the queue overflows, more recent sockets are retained.
    2. Worker Assignment: Streams are assigned to "worker slots". If slots overflow, the acceptor decides whether to evict an existing worker or keep the new stream based on the estimated sojourn time (clamped between 1 and 5 seconds).
    3. Credential Derivation: Workers attempt to read a prelude packet to derive stream credentials. If credentials cannot be derived (UnknownPathSecret), an UnknownPathSecret secret control packet is sent to the stream, resulting in an UnknownPathSecret error or a Send error.

    Replay Detection Behavior:

    • DefaultBehavior: Replay detection is not performed by the acceptor. It is deferred to the application when it attempts to decrypt the first packet (the InitialPacket).
    • SocketBehavior: Replay detection is performed by the acceptor because the separate process lacks access to the path secret map. Replay detection errors are sent back to the client over UDP, and the TCP stream is closed (typically with a ConnectionReset).

  12. Understand unreliable datagrams vs stream data

    main

    In s2n-quic, you can choose between two types of data transmission:

    • Stream data: The preferred method for application data. It supports flow control and automatic packet retransmission during packet loss.
    • Unreliable datagrams (RFC 9221): Data that is NOT retransmitted upon packet loss. This is suitable for use cases like audio or video streaming where individual packet loss is acceptable.

    Key constraints for datagrams:

    • No fragmentation/assembly: Users are responsible for ensuring datagrams fit within the available packet space. If a datagram is too large, it will be automatically dropped.
    • Queue behavior: In the default implementation, if the receiving queue is full, old datagrams are dropped in favor of new ones from the peer.
    • Transmission priority: The default sending functionality alternates between draining the stream queue and the datagram queue. Datagrams are sent when the stream queue is empty, and vice versa.