AtlatestRepositorysigil-noise
sigil-noise / treeREADME.md
1
# sigil-noise3
Transport-independent [Noise XX](https://noiseprotocol.org/noise.html) sessions4
for Sigil, using `Noise_XX_25519_ChaChaPoly_SHA256`. The primitives come from5
`sigil-crypto` and its existing mbedTLS dependency.7
This is an experimental implementation. It is not yet integrated with Slate's8
node transports. Native conformance tests do not establish browser/WASM entropy9
safety or authenticate a Noise key as an existing Slate node identity.11
## Build and test13
Use Sigil 0.22 and sigil-crypto 0.17.0 or a compatible release containing14
the X25519 and ChaCha20-Poly1305 bindings:16
```sh17
sigil deps install18
sigil test --sgl19
```21
Tests cover RFC 7748 and RFC 8439 in `sigil-crypto`, Noise-C handshake and22
transport vectors here, and rejection of tampering, replay, invalid state23
transitions, oversized messages, and the reserved final nonce.25
## API27
```scheme28
(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, authenticate40
;; noise-peer-static-key against a trusted identity here; handshake completion41
;; alone does not establish who the peer is. The handshake hash is available42
;; 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 and54
`noise-read-message!` returns its payload. All payloads, prologues, keys and55
messages are bytevectors. `noise-handshake-complete?` becomes true after the56
third message. `noise-peer-static-key` and `noise-handshake-hash` return copies57
and are available only after completion. `noise-split!` works once and returns58
a transport owning independent send/receive keys and counters.60
Handshake payloads must not trigger trusted application actions before peer61
authentication. In particular, the first XX message and its payload are sent in62
cleartext. XX does not authenticate an identity without an application trust63
check. Applications must also choose an unambiguous protocol-specific prologue.65
Provide reliable, ordered message delivery and framing outside this library.66
Noise messages are at most 65,535 bytes; transport plaintext is at most 65,51967
bytes. Larger application frames need a bounded fragmentation protocol. Wire68
headers outside the encrypted record are not authenticated by this API; put69
security-relevant metadata inside the plaintext or bind it through the prologue.70
Do not share a session concurrently between threads, copy/serialize its state,71
or retry a write after losing the returned message. Reconnect with a fresh72
handshake if ordering or delivery is uncertain.74
Operations raise on invalid input, incorrect phase, or authentication failure.75
A handshake/transport operation failure closes that session. Closing is76
idempotent. Closing a handshake after splitting does not close its separately77
owned transport. The caller must close each owner it retains.79
Only XX with this exact algorithm suite is supported. No negotiation, PSKs,80
fallback, 0-RTT, rekey API, or socket integration is provided. Internal81
constructors accept fixed ephemerals/nonces solely for conformance testing;82
applications must use the public module.84
## Key lifetime86
Session state is held in closures so ordinary printing does not expose keys.87
Owned buffers are overwritten when replaced or closed, and handshake private88
keys are dropped on completion. Native scratch buffers are zeroized before89
being freed. Sigil's garbage collector may copy managed bytevectors, and HKDF90
creates managed intermediates: this does **not** guarantee secure erasure of91
all key material. Hardened native secret storage is a separate prerequisite92
for applications requiring that guarantee. Browser/WASM secure entropy must be93
validated before enabling this implementation there.95
The test vector extracted from Noise-C is attributed in THIRD-PARTY-NOTICES.