lib/reticulum/src/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! Everything one program needs to reach a named party across a mesh network:
 2 //! the address that names the party, the key material behind that address, the
 3 //! bytes that go on the wire, the ciphers that seal a payload, and the state
 4 //! machine that drives one node of the mesh. That network is Reticulum, in
 5 //! which nodes find each other by broadcasting signed announcements and reach
 6 //! each other over any medium that moves bytes.
 7 //!
 8 //! A party has to stay reachable under one name while the wire under it
 9 //! changes, so the name a sender uses cannot be an interface or a route.
10 //! Whoever holds that name has to be the only one who can read what is sent to
11 //! it and the only one who can sign for it, so the address itself carries the
12 //! guarantee. The code has to run where memory is fixed before the program
13 //! starts, so every store takes its size from the caller and every call works
14 //! in a buffer the caller owns. A port of a protocol that speaks to programs
15 //! written by other people has to be checkable against the original, byte for
16 //! byte.
17 //!
18 //! A name built from an interface, an address, or a route stops naming the
19 //! party as soon as any of them changes, so the sender has no way to find it
20 //! again. One long-lived key pair leaves every message ever sent to it readable
21 //! once those bytes leak. A mesh floods, so the same packet reaches a node by
22 //! more than one route and would be acted on once for each.
23 //!
24 //! The package follows Reticulum 1.5.0, the reference implementation, pinned to
25 //! one upstream commit by the package README and the generated conformance
26 //! corpus. The code takes the wire layouts, the key derivations, the addressing
27 //! rule, and the state machines from the reference, and each declaration names
28 //! the reference file and line range it follows. The package generates a corpus
29 //! of reference bytes and clocks from that release and replays it in
30 //! differential tests, so each of those claims is checkable from this tree.
31 //!
32 //! The 16-byte address a party is reached by (a *destination*) is a truncated
33 //! hash over a dotted name and, for a party with a single owner, that owner's
34 //! public key, so it names the party under whatever interface or route it sits
35 //! behind. The key material behind one address (an *identity*) is two key
36 //! pairs: an X25519 pair that receives encrypted payloads and an Ed25519 pair
37 //! that signs. A party also publishes a short-lived X25519 key (a *rotating
38 //! key*) in its signed announcements and keeps the older ones, so a sender that
39 //! heard a recent announcement encrypts to a key the party will soon stop
40 //! using. Reading and writing a packet work in slices the caller supplies, and
41 //! every store is carved out of caller storage whose length has to equal a
42 //! derived byte count exactly. The node performs no input or output and reads
43 //! no clock, so each step takes the current second from its caller and returns
44 //! records standing for actions the caller performs, such as sending a frame or
45 //! arming a timer (each an *effect*). The package names its parts: the wire
46 //! layouts, what a node does with a packet once it is read, destination
47 //! addressing, identity key material, the symmetric ciphers, carrier frames,
48 //! interface access codes, the node state machine, the shared hash widths, and
49 //! the generated corpus.
50 //!
51 //! - *carrier*: one network interface a node sends and receives frames over,
52 //!   named by a byte index.
53 //! - *access code*: the shared key and code length that authenticate every
54 //!   frame on one carrier, appended on the way out and stripped and checked on
55 //!   the way in.
56 
57 pub const conformance = @import("conformance/root.zig");
58 pub const carrier = @import("carrier/root.zig");
59 pub const crypto = @import("crypto/root.zig");
60 pub const wire = @import("wire/root.zig");
61 pub const destination = @import("destination/root.zig");
62 pub const hash = @import("hash.zig");
63 pub const identity = @import("identity/root.zig");
64 pub const interface = @import("interface/root.zig");
65 pub const node = @import("node/root.zig");
66 pub const packet = @import("packet/root.zig");