tiny.reticulum.destination

1pub const Limits = struct {2    name_bytes_max: u16,3};

1pub const NameError = error{2    DotInAppName,3    DotInAspect,4    NameTooLong,5    OutputTooSmall,6};

1/// Which of four kinds of party a destination stands for, two bits wide: one2/// identity, a group that shares one key, a plain destination whose payload3/// travels unsealed, or a link, following Reticulum@1.5.04/// RNS/Destination.py:62-67.5pub const Type = enum(u2) {6    single = 0,7    group = 1,8    plain = 2,9    link = 3,10};

1/// Writes the dotted name into `output` and returns it: the application name,2/// then each aspect after a dot, then the identity hash in lowercase hex after3/// another dot when the caller passes one, so a caller shows a person the full4/// name of a destination (*expanded name*), following Reticulum@1.5.05/// RNS/Destination.py:96-112. The call returns `error.DotInAppName` or6/// `error.DotInAspect` for a label holding a dot, `error.NameTooLong` when the7/// name passes the caller's byte maximum, and `error.OutputTooSmall` when8/// `output` is shorter than the name.9pub fn expandName(10    limits: Limits,11    app: []const u8,12    aspects: []const []const u8,13    identity_hash: ?[reticulum.hash.truncated_bytes]u8,14    output: []u8,15) NameError![]u8 {16    const layout = try plan(limits, app, aspects, identity_hash != null);17    if (output.len < layout.expanded_bytes) return error.OutputTooSmall;18    var cursor = writeBase(app, aspects, output);19    std.debug.assert(cursor == layout.base_bytes);20    if (identity_hash) |identity| {21        const encoded = std.fmt.bytesToHex(identity, .lower);22        append(output, &cursor, ".");23        append(output, &cursor, &encoded);24    }25    std.debug.assert(cursor == layout.expanded_bytes);26    return output[0..cursor];27}

1/// Returns the first 16 bytes of one digest taken over the name hash followed2/// by the identity hash, and over the name hash alone when the caller passes no3/// identity, so a sender works out the 16-byte address to put in a packet4/// header from the name and the owner's identity hash, following5/// Reticulum@1.5.0 RNS/Destination.py:116-130. Folding the owner's identity6/// hash in gives two parties using the same dotted name two different7/// addresses. The call returns `error.DotInAppName`, `error.DotInAspect`, or8/// `error.NameTooLong` on the same terms as expanding a name.9pub fn hash(10    limits: Limits,11    app: []const u8,12    aspects: []const []const u8,13    identity_hash: ?[reticulum.hash.truncated_bytes]u8,14) NameError![reticulum.hash.truncated_bytes]u8 {15    const name_hash = try nameHash(limits, app, aspects);16    var hasher = reticulum.hash.Hasher.init();17    hasher.update(&name_hash);18    if (identity_hash) |identity| hasher.update(&identity);19    return hasher.finalTruncated();20}

1/// Returns the first 10 bytes of the SHA-256 digest of the dotted name (*name2/// hash*), with no identity bytes in it, so a caller works out the ten bytes an3/// announce publishes for a name, the same for every owner of that name,4/// following Reticulum@1.5.0 RNS/Destination.py:120. The call returns5/// `error.DotInAppName`, `error.DotInAspect`, or `error.NameTooLong` on the6/// same terms as expanding a name.7pub fn nameHash(8    limits: Limits,9    app: []const u8,10    aspects: []const []const u8,11) NameError![reticulum.hash.name_bytes]u8 {12    _ = try plan(limits, app, aspects, false);13    var hasher = reticulum.hash.Hasher.init();14    hasher.update(app);15    for (aspects) |aspect| {16        hasher.update(".");17        hasher.update(aspect);18    }19    return hasher.finalName();20}

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 four3//! 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, without7//! being told where that party is attached. That name has to fit in a packet8//! capped at 500 bytes, beside everything else a header carries. A node has to9//! 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 to12//! repeat in every header. A name anyone can compute is a name anyone can13//! claim, unless the owner's key material goes into it. A party that wants to14//! be found has to say so out loud, and any node that hears it has to be able15//! to check the claim without asking anyone.16//!17//! The subtree follows Reticulum 1.5.0, the reference implementation, pinned to18//! one upstream commit by the package README and the generated conformance19//! corpus. What it takes is the naming rule of Reticulum@1.5.020//! RNS/Destination.py:96-130, the four kinds of Reticulum@1.5.021//! RNS/Destination.py:62-67, the announce payload of Reticulum@1.5.022//! RNS/Destination.py:244-304, and the encryption dispatch of Reticulum@1.5.023//! RNS/Destination.py:596-665. The package generates destination and announce24//! vectors from that release and replays them in tests, so each of those claims25//! is checkable from this tree.26//!27//! The address a header carries for a party (a *destination*) is the first 1628//! bytes of one digest over a 10-byte hash of the dotted name and, for a party29//! with a single owner, a 16-byte hash of the owner's public key, so working30//! out the address takes the dotted name and the owner's public key and nothing31//! 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 be33//! presented under another address. Checking an announcement recomputes the34//! address from the announce's own name hash and public key and compares it35//! against the address the packet was sent to. The list of names a node answers36//! for is carved out of caller storage, and a duplicate or a full list is37//! refused before the list changes. The subtree names its pieces: the four38//! kinds, the naming rule and its hashes, announcements, the ciphers, and the39//! registry.40//!41//! - *destination type*: which of the four kinds of party a packet addresses, a42//!   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 a45//!   destination's announced name takes.46//! - *identity hash*: the first 16 bytes of the SHA-256 digest of an owner's 6447//!   public key bytes, which names the owner inside a destination name.4849const naming = @import("name.zig");5051pub const Type = @import("type.zig").Type;52pub const Limits = naming.Limits;53pub const NameError = naming.NameError;54pub const expandName = naming.expandName;55pub const nameHash = naming.nameHash;56pub const hash = naming.hash;57pub const announce = @import("announce.zig");58pub const cipher = @import("cipher.zig");59pub const registry = @import("registry.zig");

1pub const destination = @import("destination/root.zig");