AtlatestRenderedmarkdown
Readme

sigil-noise

Transport-independent Noise XX sessions for Sigil, using Noise_XX_25519_ChaChaPoly_SHA256. The primitives come from sigil-crypto and its existing mbedTLS dependency.

This is an experimental implementation. It is not yet integrated with Slate's node transports. Native conformance tests do not establish browser/WASM entropy safety or authenticate a Noise key as an existing Slate node identity.

Build and test

Use Sigil 0.22 and sigil-crypto 0.17.0 or a compatible release containing the X25519 and ChaCha20-Poly1305 bindings:

sigil deps install
sigil test --sgl

Tests cover RFC 7748 and RFC 8439 in sigil-crypto, Noise-C handshake and transport vectors here, and rejection of tampering, replay, invalid state transitions, oversized messages, and the reserved final nonce.

API

(import (sigil crypto)
        (sigil noise))

;; Provision/persist static keys in the application. Never reuse an ephemeral.
(define i (make-noise-handshake 'initiator (random-bytes 32) #u8()))
(define r (make-noise-handshake 'responder (random-bytes 32) #u8()))

(noise-read-message! r (noise-write-message! i #u8()))
(noise-read-message! i (noise-write-message! r #u8()))
(noise-read-message! r (noise-write-message! i #u8()))

;; Both peers now report completion. In a real application, authenticate
;; noise-peer-static-key against a trusted identity here; handshake completion
;; alone does not establish who the peer is. The handshake hash is available
;; for binding application authentication to this particular session.
(define send-side (noise-split! i))
(define receive-side (noise-split! r))

(noise-decrypt! receive-side (noise-encrypt! send-side #u8(1 2 3)))
;; => #u8(1 2 3)

(noise-close! send-side)
(noise-close! receive-side)

noise-write-message! returns one complete handshake message and noise-read-message! returns its payload. All payloads, prologues, keys and messages are bytevectors. noise-handshake-complete? becomes true after the third message. noise-peer-static-key and noise-handshake-hash return copies and are available only after completion. noise-split! works once and returns a transport owning independent send/receive keys and counters.

Handshake payloads must not trigger trusted application actions before peer authentication. In particular, the first XX message and its payload are sent in cleartext. XX does not authenticate an identity without an application trust check. Applications must also choose an unambiguous protocol-specific prologue.

Provide reliable, ordered message delivery and framing outside this library. Noise messages are at most 65,535 bytes; transport plaintext is at most 65,519 bytes. Larger application frames need a bounded fragmentation protocol. Wire headers outside the encrypted record are not authenticated by this API; put security-relevant metadata inside the plaintext or bind it through the prologue. Do not share a session concurrently between threads, copy/serialize its state, or retry a write after losing the returned message. Reconnect with a fresh handshake if ordering or delivery is uncertain.

Operations raise on invalid input, incorrect phase, or authentication failure. A handshake/transport operation failure closes that session. Closing is idempotent. Closing a handshake after splitting does not close its separately owned transport. The caller must close each owner it retains.

Only XX with this exact algorithm suite is supported. No negotiation, PSKs, fallback, 0-RTT, rekey API, or socket integration is provided. Internal constructors accept fixed ephemerals/nonces solely for conformance testing; applications must use the public module.

Key lifetime

Session state is held in closures so ordinary printing does not expose keys. Owned buffers are overwritten when replaced or closed, and handshake private keys are dropped on completion. Native scratch buffers are zeroized before being freed. Sigil's garbage collector may copy managed bytevectors, and HKDF creates managed intermediates: this does not guarantee secure erasure of all key material. Hardened native secret storage is a separate prerequisite for applications requiring that guarantee. Browser/WASM secure entropy must be validated before enabling this implementation there.

The test vector extracted from Noise-C is attributed in THIRD-PARTY-NOTICES.