AtlatestRepositorysigil-noise
1# sigil-noise
2
3Transport-independent [Noise XX](https://noiseprotocol.org/noise.html) sessions
4for Sigil, using `Noise_XX_25519_ChaChaPoly_SHA256`. The primitives come from
5`sigil-crypto` and its existing mbedTLS dependency.
6
7This is an experimental implementation. It is not yet integrated with Slate's
8node transports. Native conformance tests do not establish browser/WASM entropy
9safety or authenticate a Noise key as an existing Slate node identity.
11## Build and test
13Use Sigil 0.22 and sigil-crypto 0.17.0 or a compatible release containing
14the X25519 and ChaCha20-Poly1305 bindings:
16```sh
17sigil deps install
18sigil test --sgl
19```
21Tests cover RFC 7748 and RFC 8439 in `sigil-crypto`, Noise-C handshake and
22transport vectors here, and rejection of tampering, replay, invalid state
23transitions, oversized messages, and the reserved final nonce.
25## API
27```scheme
28(import (sigil crypto)
29 (sigil noise))
31;; Provision/persist static keys in the application. Never reuse an ephemeral.
32(define i (make-noise-handshake 'initiator (random-bytes 32) #u8()))
33(define r (make-noise-handshake 'responder (random-bytes 32) #u8()))
35(noise-read-message! r (noise-write-message! i #u8()))
36(noise-read-message! i (noise-write-message! r #u8()))
37(noise-read-message! r (noise-write-message! i #u8()))
39;; Both peers now report completion. In a real application, authenticate
40;; noise-peer-static-key against a trusted identity here; handshake completion
41;; alone does not establish who the peer is. The handshake hash is available
42;; for binding application authentication to this particular session.
43(define send-side (noise-split! i))
44(define receive-side (noise-split! r))
46(noise-decrypt! receive-side (noise-encrypt! send-side #u8(1 2 3)))
47;; => #u8(1 2 3)
49(noise-close! send-side)
50(noise-close! receive-side)
51```
53`noise-write-message!` returns one complete handshake message and
54`noise-read-message!` returns its payload. All payloads, prologues, keys and
55messages are bytevectors. `noise-handshake-complete?` becomes true after the
56third message. `noise-peer-static-key` and `noise-handshake-hash` return copies
57and are available only after completion. `noise-split!` works once and returns
58a transport owning independent send/receive keys and counters.
60Handshake payloads must not trigger trusted application actions before peer
61authentication. In particular, the first XX message and its payload are sent in
62cleartext. XX does not authenticate an identity without an application trust
63check. Applications must also choose an unambiguous protocol-specific prologue.
65Provide reliable, ordered message delivery and framing outside this library.
66Noise messages are at most 65,535 bytes; transport plaintext is at most 65,519
67bytes. Larger application frames need a bounded fragmentation protocol. Wire
68headers outside the encrypted record are not authenticated by this API; put
69security-relevant metadata inside the plaintext or bind it through the prologue.
70Do not share a session concurrently between threads, copy/serialize its state,
71or retry a write after losing the returned message. Reconnect with a fresh
72handshake if ordering or delivery is uncertain.
74Operations raise on invalid input, incorrect phase, or authentication failure.
75A handshake/transport operation failure closes that session. Closing is
76idempotent. Closing a handshake after splitting does not close its separately
77owned transport. The caller must close each owner it retains.
79Only XX with this exact algorithm suite is supported. No negotiation, PSKs,
80fallback, 0-RTT, rekey API, or socket integration is provided. Internal
81constructors accept fixed ephemerals/nonces solely for conformance testing;
82applications must use the public module.
84## Key lifetime
86Session state is held in closures so ordinary printing does not expose keys.
87Owned buffers are overwritten when replaced or closed, and handshake private
88keys are dropped on completion. Native scratch buffers are zeroized before
89being freed. Sigil's garbage collector may copy managed bytevectors, and HKDF
90creates managed intermediates: this does **not** guarantee secure erasure of
91all key material. Hardened native secret storage is a separate prerequisite
92for applications requiring that guarantee. Browser/WASM secure entropy must be
93validated before enabling this implementation there.
95The test vector extracted from Noise-C is attributed in THIRD-PARTY-NOTICES.