tiny.reticulum.identity

1/// A view of 64 public bytes the caller already holds, which hashes and checks2/// signatures where the bytes lie. The view copies nothing, so the bytes it3/// points at have to outlive it.4pub const BorrowedPublic = struct {5    bytes: *const KeyBytes,67    pub fn fromBytes(bytes: *const KeyBytes) BorrowedPublic {8        return .{ .bytes = bytes };9    }1011    pub fn toBytes(self: BorrowedPublic) KeyBytes {12        return self.bytes.*;13    }1415    /// Returns the first 16 bytes of the SHA-256 digest of the 64 public bytes,16    /// which names the identity inside a destination name, following17    /// Reticulum@1.5.0 RNS/Identity.py:784-786.18    pub fn hash(self: BorrowedPublic) [reticulum.hash.truncated_bytes]u8 {19        return reticulum.hash.truncated(self.bytes[0..key_bytes]);20    }2122    /// Returns whether an Ed25519 signature over a message checks out under the23    /// identity's signing half, following Reticulum@1.5.0 RNS/Identity.py:925.24    /// Public bytes that form no valid Ed25519 point give false.25    pub fn validate(self: BorrowedPublic, signature: [64]u8, message: []const u8) bool {26        const signing = Ed25519.PublicKey.fromBytes(27            self.bytes[half_bytes..key_bytes].*,28        ) catch return false;29        const encoded = Ed25519.Signature.fromBytes(signature);30        encoded.verify(message, signing) catch return false;31        return true;32    }33};

1/// The 64 private bytes behind one identity, an X25519 secret followed by an2/// Ed25519 seed, following Reticulum@1.5.03/// RNS/Identity.py:59-62,624,727,737-754. The public bytes, the identity hash,4/// and every signature derive from these. The value holds the bytes inline, so5/// a copy is a second copy of the secret, and the caller that wants them gone6/// keeps one instance and erases it.7pub const Private = struct {8    bytes: KeyBytes,910    pub fn fromBytes(bytes: KeyBytes) Private {11        return .{ .bytes = bytes };12    }1314    pub fn zero(self: *Private) void {15        std.crypto.secureZero(u8, &self.bytes);16    }1718    pub fn toBytes(self: *const Private) KeyBytes {19        return self.bytes;20    }2122    pub fn publicBytes(self: *const Private) KeyBytes {23        const encryption = X25519.recoverPublicKey(self.bytes[0..half_bytes].*) catch24            unreachable;25        const signing = Ed25519.KeyPair.generateDeterministic(26            self.bytes[half_bytes..key_bytes].*,27        ) catch unreachable;28        var result: KeyBytes = undefined;29        result[0..half_bytes].* = encryption;30        result[half_bytes..key_bytes].* = signing.public_key.toBytes();31        return result;32    }3334    pub fn public(self: *const Private) Public {35        return Public.fromBytes(self.publicBytes());36    }3738    pub fn hash(self: *const Private) [reticulum.hash.truncated_bytes]u8 {39        return reticulum.hash.truncated(&self.publicBytes());40    }4142    pub fn sign(self: *const Private, message: []const u8) [64]u8 {43        const signing = Ed25519.KeyPair.generateDeterministic(44            self.bytes[half_bytes..key_bytes].*,45        ) catch unreachable;46        const signature = signing.sign(message, null) catch unreachable;47        return signature.toBytes();48    }49};

1/// The 64 public bytes of one identity, an X25519 public key followed by an2/// Ed25519 public key, following Reticulum@1.5.03/// RNS/Identity.py:59-62,730-735,766-778. The value holds the bytes inline, so4/// a copy is a second copy, and the caller that wants them gone keeps one5/// instance and erases it.6pub const Public = struct {7    bytes: KeyBytes,89    pub fn fromBytes(bytes: KeyBytes) Public {10        return .{ .bytes = bytes };11    }1213    pub fn zero(self: *Public) void {14        std.crypto.secureZero(u8, &self.bytes);15    }1617    pub fn toBytes(self: *const Public) KeyBytes {18        return self.bytes;19    }2021    pub fn borrowed(self: *const Public) BorrowedPublic {22        return BorrowedPublic.fromBytes(&self.bytes);23    }2425    pub fn hash(self: *const Public) [reticulum.hash.truncated_bytes]u8 {26        return self.borrowed().hash();27    }2829    pub fn validate(self: *const Public, signature: [64]u8, message: []const u8) bool {30        return self.borrowed().validate(signature, message);31    }32};

1pub const KeyBytes = [key_bytes]u8;

1/// 64 bytes, the width of a Reticulum key value, which holds an X25519 half2/// followed by an Ed25519 half, following Reticulum@1.5.03/// RNS/Identity.py:59-62.4pub const key_bytes: usize = 64;

1//! The key material behind one Reticulum address and everything that material2//! does: name itself, sign, check a signature, seal a payload for a peer, open3//! what arrives, and roll a short-lived key forward. An address on this network4//! is a hash over a dotted name and the owner's public key, so the keys here5//! make an address reachable by its owner alone.6//!7//! Whoever holds these bytes has to be the only party that can read what is8//! addressed to the name and the only one that can sign for it. The code runs9//! where memory is fixed before the program starts, so key values are plain10//! arrays and every store takes its size from the caller. A node also has to11//! remember what it learned about other parties from their announcements, under12//! the same fixed memory.13//!14//! Key bytes that travel by value leave copies the owner has no way to reach,15//! so erasing one copy leaves the rest. One key pair that never changes leaves16//! every message ever addressed to it readable once those bytes leak. The17//! sender picks which of a party's keys it encrypts to, so the receiver has to18//! work out which one was used before it can read anything.19//!20//! The subtree follows Reticulum 1.5.0, the reference implementation, pinned to21//! one upstream commit by the package README and the generated conformance22//! corpus. What it takes is the key layout of Reticulum@1.5.023//! RNS/Identity.py:59-62, the encryption transcript of Reticulum@1.5.024//! RNS/Identity.py:804-836, the decryption order of Reticulum@1.5.025//! RNS/Identity.py:849-907, and the rotation rule of Reticulum@1.5.026//! RNS/Destination.py:206-243. The package generates identity vectors from that27//! release and replays them in tests, so each of those claims is checkable from28//! this tree.29//!30//! A party's key material, private or public (*identity*), is one 64-byte value31//! the caller owns, and a caller that needs the bytes gone keeps a single32//! instance and erases it in place. A third form borrows 64 public bytes the33//! caller already holds, so checking a received announcement needs no copy of34//! the key out of the payload. The short-lived keys a party has published35//! (*rotating keys*) live newest first in one block of caller storage, which is36//! zeroed when it is taken and again when it is handed back. Decryption walks37//! the rotating keys a party keeps after it stops publishing them (*retained38//! keys*) in the order the caller gave, falls back to the identity key, and39//! reports which retained key opened the message. Every shared secret and40//! derived key is erased before the call that made it returns. The subtree41//! names its pieces: the key pairs, encryption and decryption, rotating keys42//! and the ring that holds them, and what the node remembers about other43//! parties.4445const key = @import("key.zig");46const ratchet_module = @import("ratchet.zig");4748pub const Private = key.Private;49pub const Public = key.Public;50pub const BorrowedPublic = key.BorrowedPublic;51pub const key_bytes = key.key_bytes;52pub const KeyBytes = key.KeyBytes;53pub const Rotating = @import("rotating.zig").Rotating;54pub const cipher = @import("cipher.zig");55pub const ratchet = ratchet_module;56pub const Ratchet = ratchet_module.Ratchet;57pub const Ring = ratchet_module.Ring;58pub const Seconds = ratchet_module.Seconds;59pub const known = @import("known.zig");

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