Skip to main content

Module crypto

Module crypto 

Source
Expand description

Ed25519 message authentication for gossip broadcasts (design §6.3, FPT_ITT.1).

SWIM membership traffic (foca’s postcard-coded pings/acks) is left alone; this layer wraps only the GossipMessage custom broadcasts — the payloads that announce new signed artifacts and drive bundle propagation. Those are the messages that carry a trust decision (“epoch N exists for this scope”), so those are the ones that must be attributable to a known fleet member.

§Wire framing

A signed broadcast is [TAG][64-byte Ed25519 signature over payload][payload] where payload is the exact JSON GossipMessage bytes an unsigned node would emit. Legacy (unsigned) payloads are raw JSON and therefore always begin with { (0x7B); the SIGNED_TAG byte (0x01) can never collide with that, so a receiver can tell signed from unsigned without a version handshake. The signature travels with the message, so a relaying node re-broadcasts the original signer’s signature — every hop verifies the origin, not the last hop.

§Rollout policy

gossip.auth_mode selects the inbound policy explicitly. required (default) needs a local identity_key, trusts the named origins in peer_identities (a single-node deployment may trust only its own key), and drops unsigned, unknown, and forged broadcasts. permissive is the documented rollout mode: it accepts unsigned legacy broadcasts while the fleet still contains unsigned nodes, but verifies every signed frame against the provisioned identities — an unknown or forged signature is rejected in both modes, including when no identities are provisioned at all. Legacy peer_keys is rejected at startup because a key list cannot authorize node identities.

Structs§

GossipSigner
Signs outbound gossip broadcasts with this node’s identity key.
GossipVerifier
Verifies inbound gossip broadcasts against a set of trusted Ed25519 keys bound to node names, under the explicit AuthMode policy.

Enums§

GossipCryptoError
Error loading or configuring gossip authentication.
VerifyOutcome
Result of checking an inbound broadcast frame.

Constants§

SIGNED_TAG
Wire tag for a signed broadcast frame. Chosen so it can never collide with a legacy raw-JSON payload, which always starts with { (0x7B).

Functions§

load_authentication
Load the authentication material implied by config: the outbound signer (when an identity_key is configured) and the always-present inbound verifier for the configured AuthMode (F09).
load_signing_key
Load an Ed25519 PKCS#8 private key. Accepts PEM (-----BEGIN PRIVATE KEY-----) or raw DER, chosen by sniffing for the PEM armor.
load_verifying_key
Load an Ed25519 SPKI public key. Accepts PEM (-----BEGIN PUBLIC KEY-----) or raw DER.