Module handshake 

Available on crate feature std only.

Unified Phantom Protocol Handshake

The post-quantum, mutually-authenticated key-establishment state machine. HandshakeClient and HandshakeServer exchange a ClientHello / ServerHello pair that runs a hybrid KEM (X25519 + ML-KEM-768; ECDH-P-256 + ML-KEM-768 under --features fips) and a hybrid signature (Ed25519 + ML-DSA-65) over a single SHA-256 transcript. The signed transcript binds the whole ClientHello plus the build-side PROTOCOL_VARIANT, giving the downgrade / cross-mode resistance of Invariants 7 and 10.

On top of the core exchange the module layers: a stateless cookie + adaptive proof-of-work DoS gate; per-IP reputation-driven difficulty (DOS-2); 0-RTT session resumption with a proof-of-possession binder (HS-03) and one-shot anti-replay (Invariant 9); and optional AEAD-sealed early-data folded into the single ClientHello. HandshakeStage tracks the staged progression (Initial -> ClassicalReady -> Established | Failed).

Structs

ClientHello

Client hello message (initiates handshake).

HandshakeClient

Handshake Client State Machine

HandshakeServer

Handshake Server State Machine

HelloRetryRequest

Hello Retry Request (Server demands PoW or Cookie)

ServerHello

Server hello message (response to ClientHello)

ServerReject

Typed handshake rejection the server returns instead of silently dropping the connection when it structurally cannot satisfy a ClientHello — today, an unknown version. It gives a forward/backward-incompatible peer an actionable signal (the version the server speaks) rather than a bare connection reset.

Enums

HandshakeError

HandshakeResponse

Server response to ClientHello

HandshakeStage

ServerReply

A discriminated server handshake reply (T4.4).

Constants

EARLY_DATA_MAX_LEN

Maximum 0-RTT early-data plaintext, in bytes. The client constructor rejects a larger payload; the server drops an oversized blob and continues as a normal 1-RTT handshake. Caps the work an unauthenticated peer can force before the handshake completes.

PROTOCOL_VARIANTNon-fips

Compile-time protocol-variant tag, baked into every ClientHello (cleartext field) and the signed handshake transcript. Peers reject mismatched variants up front with HandshakeError::ProtocolVariantMismatch; even an attacker who rewrites the cleartext field cannot escape detection because the transcript signature is computed over the build’s own variant.

PROTOCOL_VERSION

The sole protocol version carried in ClientHello.version and bound into the handshake transcript. Pinned to one value — the protocol is not negotiated (pre-1.0, no users). It is a tamper-check anchor and a hook for a future, deliberate version increment.

REJECT_UNSUPPORTED_VERSION

ServerReject::code: the client’s ClientHello.version is one this server does not speak. supported_version carries the version it does speak.

SERVER_REJECT_MARKER

Marker leading a ServerReject body. Reply kind dispatch is by the explicit ServerReply discriminant byte (from_wire), not by this marker — but the marker is a defense-in-depth integrity check inside the reject payload, so a malformed or confusable blob can never be silently mistaken for a genuine reject (see ServerReject::has_marker).

Traits

ZeroRttAntiReplay

Pluggable 0-RTT anti-replay hook — the distributed-deployment seam (A2b).