Crate slither 

A WireGuard-shaped Noise-over-UDP packet layer carrying a QUIC-shaped reliable frame layer.

slither seals every datagram with an IK handshake over P-256 / ChaCha20-Poly1305 / BLAKE2b (driven entirely through hiss), gates initiations behind a keyed-BLAKE2b mac1, and carries streams, messages and unreliable datagrams inside the sealed plaintext with flow control, RFC 9002 loss recovery and congestion control. Connections roam across address changes, rekey by ratchet, and are accepted in stages, so an application can inspect a peer’s claimed identity before spending a second DH on it — a ladder climbed in a loop, not once per connection: accept() is drained for the lifetime of the endpoint, by diallers and responders alike (§6.5, documentation obligation #6). slither is #![forbid(unsafe_code)]; every Noise and curve operation goes through hiss, and no RustCrypto crate appears in the graph.

Quickstart

Two halves, taken one at a time. examples/echo.rs in the repository is the full program — both halves in one process, with an echo back — run it with cargo run --example echo.

Both start from the same one-time declaration: a crypto suite, which every slither type is generic over. Declare it once, anywhere in your crate (channel!):

use slither::prelude::*;

slither::channel! { pub MySuite<P256, ChaChaPoly, Blake2b>; }

That one line is the whole import surface for what follows — prelude carries the golden path, hiss’s three suite types included, and everything else keeps one spelling at its module (slither::error::ReadError, slither::constants::NO_ERROR).

1. Listen

Bind a socket, build an endpoint, and answer whoever arrives.

let me: SoftwareIdentity<MySuite> = SoftwareIdentity::generate(rng())?;
println!("my key: {:?}", me.public_static()); // the dialler needs this, out of band
let sock = tokio::net::UdpSocket::bind("0.0.0.0:51820").await?;
let ep = Endpoint::builder().identity(me).wire(sock).build();
// Answering is a ladder: inspect the claim, then let the peer prove it.
// accept() is a loop for the endpoint's lifetime.
while let Some(intro) = ep.accept().await {
    let claimed = intro.read_identity().await?;   // 1 DH — still just a claim
    let conn = claimed.authenticate().await?      // proven ...
        .accept().await?;                          // ... and connected
    println!("got: {:?}", conn.recv_message().await?);
}

2. Dial

The answerer’s static key reached you out of band — slither never learns one from the wire.

let me: SoftwareIdentity<MySuite> = SoftwareIdentity::generate(rng())?;
let sock = tokio::net::UdpSocket::bind("0.0.0.0:0").await?;
let ep = Endpoint::builder().identity(me).wire(sock).build();
// connect() spends no DH; awaiting Connecting runs the handshake.
let conn = ep.connect("203.0.113.7:51820".parse()?, peer_key)?.await?;
conn.send_message(b"hello").await?;
conn.acked().await?;                              // the peer has it
conn.close(slither::constants::NO_ERROR, b"done").await;

Install

[dependencies]
slither = "0.3"
# `slither::channel!` expands to absolute `::hiss::…` paths, so your
# crate must depend on hiss directly, on the same minor line.
hiss = { version = "0.4", default-features = false }
# slither's driver runs on your runtime; these are the features it uses.
tokio = { version = "1", features = ["rt", "net", "time", "sync", "macros"] }
rand_chacha = "0.10"   # only for `SoftwareIdentity`: it takes your RNG
getrandom = "0.4"      # …and something to seed it from

rand_core must be the 0.10 line hiss names — hiss::rand_core re-exports it. Two rand_core majors in one graph produce an unsatisfiable CryptoRng bound, not a version error. MSRV 1.96.

Features

Nothing is on by default.

Feature	What it adds
test-util	the testutil module, for driving slither in a downstream crate’s tests
sink	Stream / Sink adapters
codec	tokio_util::codec support; implies sink
tower	tower::Service shapes — one bi stream per call

[RATIFIED 2026/08/16 — ruling 225] The tower row read “a tower::Service shape over the message verb”, and that shape cannot work: slither has no request/response correlation on the wire, so a Service over §11 messages would need a request id the transport does not carry — slither would have to invent application framing above its own frame layer to find one. The correlation slither already has is a stream: call() opens one bi stream, finish() ends the request, EOF ends the response. PLAN.md §3.4 is the reasoned statement and it wins; this row and Cargo.toml’s comment were manifest text carrying no argument.

Shape

core::Endpoint / core::Connection   pure state machines, no I/O, no clock
        ↑ poll_output() to Timeout, after every mutating call    (§16.4)
shell: one !Send driver task        owns the cores, owns the Wire (§16.3)
        ↑ handles
compat: AsyncRead/Write · Stream/Sink · Codec · tower            (§16.11)

The cores never read a clock — now: Instant is an argument on every mutating call — and the shell is a single !Send actor run with tokio::task::spawn_local on a current-thread runtime inside a LocalSet. Nothing on that path requires Send, deliberately: a hardware-backed static key (an iOS Secure Enclave SecKey) is not Send, and a transport that demanded it would exclude the case the DH provider seam exists for.

Because the cores are pure and shell::wire::Wire is the only I/O seam, the whole protocol is drivable without a kernel: two endpoints over the in-memory testutil fabric on tokio’s paused clock, with every timer resolving in virtual time.

Before you integrate

Six hazards have no code fix. A consumer meets each one by getting it wrong, so each is stated here as well as at its call site.

1. Reconnecting is close() then dial, not connect() again. connect() to a static that already has a live connection returns ConnectError::AlreadyConnected — §16.1 admits one session per peer static, and the existing connection is what holds it. “Call connect again” is the natural guess and it is wrong: it does not replace the old connection, it does not repair a wedged one, and it leaves the first connection completely untouched.

   An application that wants reconnect now releases the static first and only then dials:

   // Wrong: the static is still LIVE, so this is `AlreadyConnected`
   // and the wedged connection is still there afterwards.
   //
   //     endpoint.connect(addr, peer)?.await
   
   // Right: end the old one, wait for it to be gone, then dial.
   stale.close(slither::constants::NO_ERROR, b"reconnecting").await;
   stale.closed().await;
   drop(stale);
   endpoint.connect(addr, peer)?.await

   The closed().await is not decoration: close() returns once the CLOSE is sealed, and the static is released when the connection’s state is actually dropped (§16.4’s Retired). Dialling before then races the release.

2. Do not punish on evidence a third party can manufacture. Authorise on it; do not punish on it. The rule is one sentence and it reaches three rungs of the handshake, because “an attacker gets an innocent peer banned” is the same hazard at all three.

   • A claimed static is not an authenticated one. The identity read_identity() reveals during a staged accept is an unauthenticated assertion, made before any DH proves possession. Denylisting on it lets an attacker claim any public key in order to get its owner banned.
   • The source address and sender_index are worse, not better. §6.1 forbids durable state keyed on three quantities — the claimed static, the source address, and sender_index — and the two beside the static are the cheaper keys to abuse: a spoofed source costs an attacker no DH at all, needs no knowledge of anyone’s public key, and has no return-routability proof at stage 0. A source-address denylist under the flood §6.3 describes bans spoofed victims. See Intro::source and Intro::sender_index.
   • A proven static does not make the accusation true. AuthError::Replay is delivered after the ss has genuinely proven the static, which is exactly what makes it look like trustworthy evidence about that peer. It is not: one captured initiation lets a third party produce it at will, from any address, against a peer that has done nothing. It reports this initiation is not fresh, never this peer misbehaved.

3. A connection with nothing to say dies — in 25 s, in silence. A connection that has received no authenticated packet since it was installed transmits nothing at all and is torn down at install + DEAD_TIMEOUT (25 s) with ConnectionLost::TimedOut. Connecting ahead of need does not keep a path warm, and this is the single most surprising behaviour for a new consumer.

   What keeps a connection alive is not a knob. §7.5’s keepalive dance is automatic for any connection that has carried traffic: one application message, in one direction, puts the receiver into the state that makes it answer every 10 s, which puts the sender into it, and the pair then sustains itself indefinitely with no configuration anywhere.

   The knob is for the case that leaves out — a link that is mutually idle and must nonetheless stay open, through a NAT binding or a firewall’s idle reaper. Connection::set_persistent_keepalive takes an interval in [1 s, 25 s) and rejects anything outside it rather than clamping. Enabling it on one side is enough: the beacon reaches the peer, and the peer’s automatic half answers.

   A beacon does not defer death, and is not meant to. Both keepalives are marking sends, so they arm the death clock; a connection whose beacons are never answered still ends 25 s after the last authenticated packet it received. Two consecutive lost beacons at the 10 s default is what that costs.

4. Teardown triggers on dropping every handle, not the endpoint. The connection lives as long as any handle to it does, and ends when the last one is dropped — the opposite of the obvious guess, and sensitive to the order your values fall out of scope.

5. Messages and streams do not mix on one connection. Using send_message alongside open_uni on the same connection is a programming error with a defined, loud failure. The safe and unsafe shapes look alike at the call site, which is exactly why it is written down.

6. accept() is a loop for the lifetime of the endpoint, not one call per connection. §6.5 puts it as a SHOULD: “Every application SHOULD treat accept() as a loop for the lifetime of its endpoint — diallers and responders alike.” Accepting once and moving on is the natural shape, and it strands the two cases the protocol expects the next accept() to repair.

   • A lost msg2 leaves a responder holding a connection the peer knows nothing about. msg2 is never retransmitted — every retransmit is a completely fresh initiation (§5.5) — so one dropped msg2 leaves this side with a live, never-confirmed connection while the peer re-offers a fresh Intro every RETRANSMIT_BASE (~5 s) until it gives up at HANDSHAKE_GIVEUP (90 s). No error ever prompts the retry: the first accept() succeeded. Only the next one closes the gap.
   • A restarted peer is the same shape (§6.8). Its reconnection parks as an ordinary Intro against our still-live static, the now-zombie connection keeps running untouched, and nothing tears it down until the replacing accept(). “Restart needs no machinery of its own” is true only because the application is still listening.

   Admitting that fresh Intro is the replacement, by §6.4’s §16.1 guard. Where the connection it displaces is one we accepted — replacement basis Some(t), and the new initiation’s timestamp strictly greater — the install fires ConnectionLost::Replaced on the old connection and the new chain completes. Where it is one we dialled, the basis is None, no initiation can replace it, AcceptError::Stale comes back and §6.8’s restart instead resolves at liveness, at most DEAD_TIMEOUT later. Either way the application side of it is the one instruction: keep accepting.

The spec is the authority

SPEC.md is the authority. Every constant, header layout, frame type and timer in this crate is ratified there, and where the code and the spec disagree the spec is right. The module layout is deliberately one-to-one with the spec’s sections so a reviewer can find the code for a section without searching.

Modules

• prelude — the golden path in one glob: use slither::prelude::*;. The root itself carries only hiss, SessionId, Dir, StreamId and Timestamp; every other name has exactly one spelling, at its module (ruling 278).
• identity — the static-key seam. A consumer implements Identity to put its key behind hardware; SoftwareIdentity is the in-memory default.
• shell — the I/O shell: Endpoint, Connection, the staged accept ladder, the stream handles, and shell::wire::Wire — the datagram seam an application supplies.
• config — endpoint configuration and §16.5’s injected wall clock.
• error — the closed error taxonomy of §18.1, plus ConfigError. Module-only (ruling 278): its ten types are named slither::error::ReadError and are deliberately not in the prelude — bare-minimal code never spells one, since ? into Box<dyn std::error::Error> covers the quickstart.
• packet — §2–§5’s wire: the suite declaration, §6.1’s handshake ladder as a trait, the three headers, mac1 and §3.1’s gate.
• constants — every named constant the spec fixes, one home, with the derived ones re-derived as compile-time assertions.
• compat — §16.11’s composability surface: AsyncRead/AsyncWrite on the stream handles and the two io::Error conversions (ungated), plus Stream/Sink, tokio_util::codec and tower::Service faces behind their features. It adds no verb and no state.
• testutil — the in-memory Network / FlakyWire / FlakyPolicy fabric and the counting DH provider, behind the test-util feature. Attested surface (ruling 60), not a test convention: it is deterministic under a caller-supplied seed, and renaming one of those three types is a protocol revision.
• core — §16.4’s two sans-io state machines. Crate-internal: nothing outside the crate drives them directly.

Re-exports

pub use hiss;

Modules

compat

§16.11’s composability surface: slither’s verbs, in the shapes the async ecosystem consumes.

config

Endpoint configuration, and §16.5’s injected wall clock.

constants

Every named constant SPEC.md fixes, and nothing else.

error

The error taxonomy — SPEC.md §18.1, plus the one type it excludes.

identity

Your static keypair, and the seam that lets it live in hardware.

packet

§2–§5 — the wire: where bytes acquire meaning.

prelude

The golden path in one import.

shell

Everything you call: Endpoint, Connection, the staged accept ladder and the stream handles.

testutil

The kernel-free test fixtures — SPEC.md §16.10, ruling 60.

Macros

channel

Declare a crypto suite over the IK pattern. §2.2.

channel_psk

Declare a crypto suite over the IKpsk1 pattern — msg1’s token block gains a trailing psk. §2.2.

Structs

SessionId

A completed session’s channel binding — hiss’s type, re-exported.

StreamId

§9.1’s wire stream identifier.

Timestamp

§5.2’s initiation timestamp: seconds and nanoseconds since the Unix epoch, the one wall-clock reading in the protocol (§5.3).

Enums

Dir

§9.1’s direction.