lib/reticulum/src/conformance/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! Generated by `lib/reticulum/build/generate` with `rns==1.5.0`.
 2 //! The upstream source is Reticulum commit `e32d4df754a7b87b1bf1bb0d08675d12ff505ae6`.
 3 //! Hand edits are lost.
 4 //!
 5 //! The files in this directory record what Reticulum 1.5.0, the Python
 6 //! reference implementation, did when it was given fixed inputs: the bytes it
 7 //! sent, the decisions it made about each input, and the second at which each
 8 //! step happened. The package's tests feed the same inputs through the Zig port
 9 //! and compare its output with the recorded output field by field. The
10 //! directory holds nine files, one per area: hashing, destination names, tokens
11 //! with key derivation and padding, identities, packets, announces, interface
12 //! access codes, transport, and links, and this file imports all nine. Package
13 //! builds read the checked-in files and never install or run the reference.
14 //!
15 //! A port of a network protocol has to talk to nodes that run other people's
16 //! programs, so every byte it sends and every packet it accepts or refuses has
17 //! to match the original program. The direct check of that match is the
18 //! original's own output: both programs get the same inputs, and what comes out
19 //! is compared byte for byte.
20 //!
21 //! The reference is Python and builds its byte layouts from slices of hashes
22 //! and packets, so the port has to reproduce each slice exactly. For example,
23 //! the ten random bytes of an announce are the first five bytes of a random
24 //! hash followed by the clock as five big-endian bytes. The reference draws
25 //! fresh random bytes for every key, initialization vector and announce, so two
26 //! runs produce different bytes unless those random bytes are fixed in advance.
27 //! The reference reads a wall clock with fractional seconds and writes it into
28 //! announces, round-trip times and keepalive deadlines, and the port counts
29 //! time in whole seconds. The reference also sleeps, runs work on threads, and
30 //! waits a random fraction of a second before it rebroadcasts an announce, and
31 //! none of that replays step by step.
32 //!
33 //! The package README and the header of every corpus file pin the reference to
34 //! upstream commit `e32d4df754a7b87b1bf1bb0d08675d12ff505ae6`. The generator
35 //! refuses any installed release other than 1.5.0, and it runs the reference
36 //! with its own built-in cryptography by hiding the separate `cryptography`
37 //! package from it. Each corpus file names the reference lines its records take
38 //! from, in the form `Reticulum@1.5.0 RNS/<file>.py:<lines>`, and the tests
39 //! that replay the records carry the same form in their names.
40 //!
41 //! The generator replaces the reference's source of random bytes with a stream
42 //! derived from one fixed string (`tiny-reticulum-conformance-rns-1.5.0`), its
43 //! *seed*: SHA-256 over that string and an eight-byte big-endian counter, one
44 //! digest after another. Each named record (a *vector*) holds the random bytes
45 //! the reference drew for it, so a test hands the port the same bytes. The
46 //! generator runs the reference on a stand-in clock that starts at
47 //! 1,700,000,000, reads whole seconds, and moves only when the generator sets
48 //! it, and each vector records the second of each step, its *recorded clock*.
49 //! The generator sets the reference's random rebroadcast delay to zero, runs
50 //! its threads inline, stops it wherever it would sleep, turns any logged
51 //! warning into an error, and moves its periodic housekeeping so far into the
52 //! future that the housekeeping never runs, so every run takes the same path or
53 //! stops. The generator's stand-in network interfaces set neither
54 //! `AUTOCONFIGURE_MTU` nor `FIXED_MTU`, so every link request carries three
55 //! bytes that ask for the 500-byte MTU, and a transport node cuts those bytes
56 //! off before it passes the request on. The keepalive is recorded at the first
57 //! whole second at or after the reference's keepalive deadline, and the
58 //! generator also runs the reference one second earlier and confirms that
59 //! nothing is sent there. The port derives a link's responder key and the
60 //! initialization vector of its round-trip report from the random bytes the
61 //! caller hands each step, using HKDF, and the generator derives the same bytes
62 //! and hands them to the reference in place of the random bytes the reference
63 //! would draw, so those bytes follow the port's convention. The generator's
64 //! `--check` mode regenerates every file into a scratch directory and fails,
65 //! naming the files, when any of them differs by a byte, so the checked-in
66 //! corpus stays the generator's own output.
67 //!
68 //! - *verdict*: the outcome the reference reported for one input, either true
69 //!   or false or a short name such as `invalid-code` or `tagless`.
70 
71 pub const announce = @import("announce.zig");
72 pub const destination = @import("destination.zig");
73 pub const hash = @import("hash.zig");
74 pub const ifac = @import("ifac.zig");
75 pub const identity = @import("identity.zig");
76 pub const link = @import("link.zig");
77 pub const packet = @import("packet.zig");
78 pub const token = @import("token.zig");
79 pub const transport = @import("transport.zig");