flare.tls.rustls_quic

The Rust crate is not built; the reactor should treat this as a configuration error (not a per-packet failure). The build_rustls.sh activation script wired into pixi's [activation.scripts] auto-builds the crate on pixi install; this carrier exists for the rare path where activation didn't run (e.g. a bare mojo invocation outside a pixi shell).

Construct an acceptor from the supplied config.

Does not raise on FFI rejection: the carrier always constructs (with _opaque_handle == 0 on failure) so the reactor can surface the rustls last-error message via :class:RustlsQuicError rather than a partial-construction half-state.

Release a per-connection rustls session previously produced by :func:flare.tls._rustls_quic_ffi._do_accept through the acceptor's pinned library handle.

NULL is a no-op. Used by :class:flare.quic.server.QuicListener to drop every session in its slab from inside the listener's destructor without sub-field access on self.tls_acceptor._lib (which Mojo's deinit ordering rule forbids).

Create a new per-connection session bound to the client's Destination Connection ID.

The reactor calls this once per connection after parsing the first Initial packet. The DCID is required because the rustls binding uses it (via the QUIC transport parameters extension) to bind initial-secret derivation to the per-connection identity (RFC 9001 §5.2).

Build a connector from a trust-anchor PEM bundle + ALPN list.

ca_pem is a PEM bundle of trusted roots; for a loopback link to flare's own server, pass that server's self-signed cert (a self-signed leaf is its own root). Does not raise on PEM-parse failure -- the carrier constructs with a 0 handle and :meth:connect surfaces the rustls last-error -- so a configuration mistake is one clear error at connect time, not a partial-construction half-state. Raises only on an invalid ALPN list (empty or >255-byte protocol).

Build a connector trusting the operating system's CA bundle (loaded at runtime via rustls-native-certs) instead of a PEM. use_system_roots distinguishes this overload from the PEM constructor. Mirrors the PEM path: a 0 handle (no native roots found / none usable) is surfaced at :meth:connect time, not at construction. Raises only on an invalid ALPN list.

Build a connector trusting the OS CA bundle (rustls-native-certs) -- the public-internet h3 client path where there is no PEM to ship. Equivalent to the use_system_roots=True constructor; provided as a named factory for an ergonomic call site.

Release a per-connection session through the connector's pinned library handle (mirror of :meth:RustlsQuicAcceptor.free_session). NULL is a no-op.

Open a client-role session against server_name (SNI).

transport_params is the client's encoded QUIC transport parameters (empty is accepted for the handshake-only path; the QUIC client driver fills the real blob). The returned :class:RustlsQuicSession drives the client handshake through the same feed/take CRYPTO + AEAD + header thunks the server session uses; the first take_crypto(INITIAL) drains the ClientHello.

Build a session carrier with a NULL handle. Every FFI-touching method raises on a NULL handle.

Useful for testing the level machine + DCID round-trip without a real acceptor; the production path uses :meth:RustlsQuicAcceptor.accept.

Internal: wrap a real Rust-side Box<Session>* that :meth:RustlsQuicAcceptor.accept just produced.

Each session gets its own OwnedDLHandle so the .so refcount stays high until the session drops; on Linux the -z nodelete link flag is the additional belt-and-suspenders pin.

Feed inbound CRYPTO frame bytes at level.

The reactor calls this after dispatching a CRYPTO frame out of a packet at the matching encryption level. The data buffer is a contiguous chunk; the rustls side reassembles fragments internally.

Drain pending outbound CRYPTO frame bytes at level.

Returns an empty list when no bytes are pending. The reactor packages the result into CRYPTO frames inside packets at the matching encryption level.

Whether the 1-RTT keys are derived. Returns False on a NULL session (test path) or while handshaking; True after rustls flips into the application-keyed state.

ALPN identifier the rustls side picked.

Returns the negotiated identifier from the ALPN list passed at config time (e.g. "h3"). The reactor uses this to dispatch to the H3 server vs an alternative application protocol over QUIC.

The peer's raw quic_transport_parameters extension bytes (RFC 9000 §7.4), or an empty list if rustls has not yet surfaced them.

rustls only exposes these once the carrying handshake flight has been processed (the server's params reach the client after EncryptedExtensions; the client's reach the server after the ClientHello). Poll after the handshake completes for a stable result, then decode with :func:flare.quic.transport_params.decode_transport_parameters to apply the peer's flow-control and CID limits. Returns an empty list on a NULL session (test path).

Current outbound encryption level. Useful for tests confirming the level machine compiles.

Whether rustls has installed per-level keys at the given encryption level (2 = Handshake, 3 = 1-RTT).

Initial-level keys never flow through rustls's KeyChange (they derive from the connection ID per RFC 9001 §5.2 and the flare side runs Initial AEAD through :class:flare.quic.crypto.OpenSslQuicCrypto), so this returns False for level 0. The reactor polls :meth:have_keys after every :meth:take_crypto pump to learn when to install Handshake / 1-RTT keys onto the owning :class:flare.quic.server.QuicConnection.

NULL session handles (the test-only constructor path) return False without raising.

Capture rustls's 0-RTT (EarlyData) keys into the session, if available (RFC 9001 §4.1; wraps Connection::zero_rtt_keys()).

On the client this returns True right after :meth:RustlsQuicConnector.connect IFF the connector's session store held a ticket for the SNI (a resumed connection) and early data is enabled; on the server it returns True once the resumed ClientHello has been fed and 0-RTT was accepted. After True, the :data:QuicEncryptionLevel.EARLY_DATA AEAD + header thunks encrypt/decrypt 0-RTT packets. Returns False on a NULL session (test path) or when rustls has no 0-RTT keys for this connection (the common first-flight case).

Whether the server signalled it will process the client's 0-RTT data (RFC 8446 §4.2.10; client-role only).

A False after the handshake completes means the server rejected early data and the client must replay it in 1-RTT. Returns False on a NULL session or for the server role.

Encrypt payload in place at level via rustls's Keys.local.packet.encrypt_in_place (RFC 9001 §5.3).

header is the QUIC packet header (used as AEAD AAD); the returned tag is the 16-byte authentication tag the caller appends to the on-wire packet. Raises if the FFI rejects (e.g. keys not yet installed at level); the rustls error text is in :func:_do_last_error.

Verify + strip the AEAD tag from payload in place at level via rustls's Keys.remote.packet.decrypt_in_place (RFC 9001 §5.3).

Returns the plaintext length (always len(payload) - 16 for the AEAD-GCM / ChaCha20-Poly1305 suites rustls speaks); raises if rustls rejects the tag (the typical wrong-keys- at-this-level symptom).

Open a 1-RTT payload in place under the header's key phase bit (RFC 9001 sec 6.3). Returns 1 when the peer started a key update and the keys rotated, else 0; raises on failure.

Start a 1-RTT key update (RFC 9001 sec 6.1); returns the new key phase bit.

Apply QUIC header protection (RFC 9001 §5.4) to the packet's first byte + packet-number bytes via rustls's Keys.local.header.encrypt_in_place.

sample MUST be a 16-byte slice of the encrypted payload (4 bytes past the start of the packet-number field). first_byte_addr / pn_addr are raw pointer values (as Int) so the caller can keep the byte cells on the stack and let rustls write through.

Remove QUIC header protection (RFC 9001 §5.4) from the packet's first byte + packet-number bytes via rustls's Keys.remote.header.decrypt_in_place. Same sample contract as :meth:header_encrypt.