Skip to main content

hiss_macros/
lib.rs

1//! Proc-macro companion to the [`hiss`](https://docs.rs/hiss) crate.
2//!
3//! This crate provides exactly one macro, [`noise!`](macro@noise): it
4//! takes a Noise handshake pattern written in the notation of the
5//! [Noise specification](https://noiseprotocol.org/noise.html) and a
6//! concrete suite, and generates a pair of documented, sans-io,
7//! type-state handshake state machines for it.
8//!
9//! Use it through the `hiss` crate, which re-exports it as `hiss::noise!`
10//! — the generated code references `::hiss` paths
11//! and needs that crate in scope.
12
13mod codegen;
14mod parse;
15
16use proc_macro::TokenStream;
17use syn::parse_macro_input;
18
19/// Generate a sans-io Noise handshake from its pattern, written in the
20/// notation of the Noise specification.
21///
22/// # Syntax
23///
24/// ```text
25/// noise! {
26///     /// Doc comments become the docs of the generated pattern type.
27///     pub IKpsk1<X25519, ChaChaPoly, Blake2b> {
28///         <- s
29///         ...
30///         -> e, es, s, ss, psk
31///         <- e, ee, se
32///     }
33/// }
34/// ```
35///
36/// The three angle-bracketed types are the suite — the DH curve, AEAD
37/// cipher, and hash, e.g. `hiss::noise::{X25519, ChaChaPoly, Blake2b}`.
38/// They must be concrete: that is what lets every handshake message be
39/// a fixed-size `[u8; N]` computed at compile time. Lines before `...`
40/// are pre-messages (keys known before the handshake); lines after it
41/// are the handshake messages. A pattern with no pre-messages (`NN`,
42/// `XX`, …) simply omits the `...`.
43///
44/// A handshake message line may end with a bracketed byte length —
45/// `-> e, es, s, ss [12]` — declaring a fixed-size **application
46/// payload** carried in that message's tail (Noise sanctions a payload
47/// on every handshake message; the suffix is this DSL's one extension
48/// to the specification's notation, whose tables leave payloads
49/// implicit).
50///
51/// # What is generated
52///
53/// For a pattern named `P` the macro emits, at the invocation site:
54///
55/// * `struct P` — the pattern marker, implementing `hiss`'s `Pattern`
56///   and `Protocol` traits, with `P::MSG1_SIZE`, `P::MSG2_SIZE`, …
57///   consts giving the exact wire size of every handshake message;
58/// * one constructor per role — `P::initiator(provider, prologue, …)` /
59///   `P::responder(provider, prologue, …)`, whose extra parameters are
60///   exactly the pre-message keys the pattern requires of that role —
61///   and then **one method per handshake message**
62///   (`write_message_1`, `read_message_2`, …), each taking exactly the
63///   key material its tokens consume. One state type per message per
64///   role, generic only over the crypto provider; calling messages out
65///   of order is a compile error. Keys the handshake has established —
66///   the ephemerals, the peer's revealed static identity — are
67///   observable through accessors (`remote_static()`, …) generated
68///   only on the states where the key is guaranteed present;
69/// * a compile-time assertion of `hiss`'s `WellFormed` guard, so a
70///   pattern violating Noise §7.3 (a DH over a key not yet transmitted,
71///   a re-sent key, a never-keyed cipher) fails to build.
72///
73/// The generated states perform **no I/O**: `write_message_N` returns
74/// the finished message as a `[u8; P::MSGn_SIZE]`, and `read_message_N`
75/// borrows the incoming `&[u8; P::MSGn_SIZE]` for the duration of the
76/// call. Framing and transporting the messages is the caller's job.
77///
78/// For a message declared with a `[N]` payload suffix, the writer takes
79/// `payload: &[u8; N]` as its last parameter (the payload is the tail)
80/// and the reader returns the recovered `[u8; N]` by value alongside
81/// the next state; `MSGn_SIZE` grows by exactly `N`. Whether the
82/// payload is encrypted is **positional** — it depends on whether the
83/// cipher is keyed when that message's tail closes — and the generated
84/// method docs state the concrete property ("encrypted to …" vs
85/// "travels in the clear") per message.
86///
87/// PSKs are plain `&Psk` parameters. When a *received* message reveals
88/// the peer's static (`s`) before its `psk` token — IKpsk1's signature
89/// move — an additional `read_message_N_with` variant is generated
90/// whose PSK parameter is a lookup closure over the just-revealed
91/// identity, for deployments that select a per-peer PSK (or reject
92/// unknown peers) at exactly that point.
93///
94/// Every other *received* message that reveals the peer's static gets a
95/// `read_message_N_with` variant whose closure receives the
96/// just-revealed identity and returns `Ok(())` to accept the peer, or
97/// an error (e.g. `HandshakeError::PeerRejected`) to abort. The closure
98/// fires as soon as the static is decrypted, **before** the message's
99/// remaining DH tokens are computed: on the final message a role
100/// receives (XX's, X's, or IX's last) that is the last moment before
101/// the handshake completes into a `Transport`; on an earlier message
102/// (IK's first) it rejects an unwanted peer before spending further
103/// provider work. (A read with a PSK lookup keeps that form instead:
104/// the lookup closure is already the identity hook.)
105///
106/// # Example
107///
108/// The worked example — an `IKpsk1` ceremony, both roles in one program,
109/// the PSK lookup keyed on the identity msg1 reveals, and the transports
110/// that come out of it — is a doctest that compiles and runs. It hangs
111/// off `hiss`'s re-export of this macro, [`hiss::noise!`], and so sits
112/// further up that page.
113///
114/// It is there rather than here because a doctest can only exercise
115/// generated code where the runtime types are, and this crate cannot
116/// depend on `hiss` — `hiss` depends on this one. Two runnable programs
117/// in the repository cover the same ground: `examples/quickstart.rs`
118/// (`XX`, both roles in one process) and
119/// `examples/tcp_ikpsk1_ceremony.rs` (this pattern, over a socket).
120///
121/// Each type this macro generates also carries its own walkthrough: a
122/// `# Usage` section, per role, written against that pattern's messages
123/// — and likewise a doctest that compiles, provided the suite is
124/// written as `hiss::noise`'s own type names (`X25519`, `X448`, `P256`,
125/// `ChaChaPoly`, `AesGcm`, `Blake2b`, `Blake2s`, `Sha256`, `Sha512`) or
126/// as paths starting `hiss::`. Any other spelling still gets the
127/// walkthrough, as an uncompiled sketch.
128///
129/// [`hiss::noise!`]: https://docs.rs/hiss/latest/hiss/macro.noise.html
130#[proc_macro]
131pub fn noise(input: TokenStream) -> TokenStream {
132    let input = parse_macro_input!(input as parse::NoiseInput);
133    codegen::expand(&input).into()
134}