lib/reticulum/src/destination/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! How a party is named on a Reticulum mesh and everything that name carries:
 2 //! building the name, cutting it down to the address a header holds, the four
 3 //! kinds of party a name can stand for, the announcement that publishes a name,
 4 //! the ciphers each kind uses, and the list of names one node answers for.
 5 //!
 6 //! A sender has to reach a party by a name it can work out for itself, without
 7 //! being told where that party is attached. That name has to fit in a packet
 8 //! capped at 500 bytes, beside everything else a header carries. A node has to
 9 //! know which names it answers for, in memory fixed before the program starts.
10 //!
11 //! A name a person can read runs to dozens of bytes, which is too much to
12 //! repeat in every header. A name anyone can compute is a name anyone can
13 //! claim, unless the owner's key material goes into it. A party that wants to
14 //! be found has to say so out loud, and any node that hears it has to be able
15 //! to check the claim without asking anyone.
16 //!
17 //! The subtree follows Reticulum 1.5.0, the reference implementation, pinned to
18 //! one upstream commit by the package README and the generated conformance
19 //! corpus. What it takes is the naming rule of Reticulum@1.5.0
20 //! RNS/Destination.py:96-130, the four kinds of Reticulum@1.5.0
21 //! RNS/Destination.py:62-67, the announce payload of Reticulum@1.5.0
22 //! RNS/Destination.py:244-304, and the encryption dispatch of Reticulum@1.5.0
23 //! RNS/Destination.py:596-665. The package generates destination and announce
24 //! vectors from that release and replays them in tests, so each of those claims
25 //! is checkable from this tree.
26 //!
27 //! The address a header carries for a party (a *destination*) is the first 16
28 //! bytes of one digest over a 10-byte hash of the dotted name and, for a party
29 //! with a single owner, a 16-byte hash of the owner's public key, so working
30 //! out the address takes the dotted name and the owner's public key and nothing
31 //! else. The signed packet a party sends to make itself known (an *announce*)
32 //! signs bytes that open with that address, so the same signed bytes cannot be
33 //! presented under another address. Checking an announcement recomputes the
34 //! address from the announce's own name hash and public key and compares it
35 //! against the address the packet was sent to. The list of names a node answers
36 //! for is carved out of caller storage, and a duplicate or a full list is
37 //! refused before the list changes. The subtree names its pieces: the four
38 //! kinds, the naming rule and its hashes, announcements, the ciphers, and the
39 //! registry.
40 //!
41 //! - *destination type*: which of the four kinds of party a packet addresses, a
42 //!   single identity, a group sharing one key, a plain unencrypted destination,
43 //!   or a link.
44 //! - *name hash*: the first 10 bytes of a SHA-256 digest, the width a
45 //!   destination's announced name takes.
46 //! - *identity hash*: the first 16 bytes of the SHA-256 digest of an owner's 64
47 //!   public key bytes, which names the owner inside a destination name.
48 
49 const naming = @import("name.zig");
50 
51 pub const Type = @import("type.zig").Type;
52 pub const Limits = naming.Limits;
53 pub const NameError = naming.NameError;
54 pub const expandName = naming.expandName;
55 pub const nameHash = naming.nameHash;
56 pub const hash = naming.hash;
57 pub const announce = @import("announce.zig");
58 pub const cipher = @import("cipher.zig");
59 pub const registry = @import("registry.zig");