Skip to content

Chapter 10 — Security Reference

This chapter describes Stolo's security architecture for administrators and security reviewers: the cryptography, the identity model, what is and isn't protected, and how to harden deployments.

10.1 Cryptographic foundation

Stolo's transport security comes from Reticulum (RNS) and the LXMF message layer — established, publicly auditable cryptographic networking used far beyond Stolo. Stolo does not implement its own cryptography.

Function Primitive
Identity keys 512-bit Curve25519 keysets: X25519 (256-bit) for key exchange + Ed25519 (256-bit) for signatures
Key exchange ECDH on Curve25519, keys derived with HKDF
Message encryption Ephemeral AES keys per link/packet (AES-CBC with PKCS7; token format authenticated with HMAC-SHA256)
Signatures Ed25519 (64-byte signatures)
Hashing SHA-256 / SHA-512

End-to-end encryption

Every Stolo message — text, attachments, voice, reactions, GPS telemetry, group messages — is end-to-end encrypted to the recipient's public key. Group messages are individually encrypted per member (fan-out), so groups inherit the same guarantees. Relay and transport nodes forward ciphertext; they cannot read message content, even the Stolo Gateway.

Forward secrecy

Message keys are ephemeral: links negotiate fresh ECDH keys per session, and single-packet deliveries use per-packet ephemeral keys against the recipient's rotating announced ratchet key. Compromise of a device's long-term key does not retroactively decrypt past traffic captured off the air.

Metadata

  • Reticulum packets carry no source addresses — an observer of mesh traffic cannot see who originated a packet.
  • Announces (presence/discovery) are visible to the mesh by design and include the announcing identity's public key, display name, and optional telemetry if position sharing is enabled. Administrators controlling their radio footprint should review the discovery and GPS settings (Chapter 12).
  • Delivery confirmations are cryptographic proofs from the recipient's device.

10.2 Identity and key storage

  • Each device auto-generates its identity keypair on first launch. Private keys never leave the device — there is no cloud escrow, no account recovery, and no central directory.
  • On desktop/relay platforms the device keyset is stored at ~/.gridx/device.identity with owner-only file permissions (0600, in a 0700 directory), enforced at every startup. On mobile it lives in the app's sandboxed container.
  • Organization keysets (Chapter 8) are separate files under Stolo's identity storage; the org's private key exists only on devices where an administrator placed it.
  • Backups: possession of the profile directory is possession of the identity — it can decrypt that device's traffic and impersonate it. Back it up only to media you'd trust with the device itself. There is currently no in-app key rotation; replacing an identity means resetting the profile (Chapter 14).

10.3 Inbound message authentication and the trust gate

Delivery of an inbound message requires both:

  1. A valid Ed25519 signature binding the message to the claimed sender identity — a message whose signature does not validate is never delivered on a trust grant (it is quarantined, unverified), and forged reactions are dropped outright; and
  2. A positive trust decision: trusted sender → deliver; member of a trusted org → deliver; otherwise quarantine (or drop, under strict mode).

Additional inbound hardening:

  • Group authorization — forged group invites (wrong claimed owner, or not actually listing the recipient) and forged member evictions are rejected.
  • Bounded quarantine — per-message (8 MB), per-sender (20), and global (500 messages / 128 MB) caps prevent unknown senders from filling the disk; entries expire after 7 days.
  • Attachment containment — inbound attachments are size-capped (16 MB), stored under locally derived filenames (never sender-chosen paths), with an independent path-containment check on every write and an allowlist of file extensions (unlisted types are neutralized to .bin).
  • Decode bounds — received images are decoded within fixed memory bounds to defeat decompression bombs.

10.4 Local attack surface

  • The engine's control channel is a WebSocket bound to loopback only (127.0.0.1:4848) and gated by a random per-boot 256-bit token (written 0600 to the profile directory, compared in constant time). Nothing off-device can connect; on-device, only processes able to read the token file can drive the engine.
  • The command channel is input-hardened: malformed frames, wrong-typed fields, and handler errors produce structured error responses without crashing the engine.
  • Data at rest is not encrypted by Stolo. The message database, media, and keys live together in the profile directory in plaintext (mobile platforms add their own container encryption at the OS level). See hardening below.

10.5 Hardening checklist

For phones and tablets:

  • ☐ Enforce a device passcode and OS-level encryption (default on modern iOS/Android) — this is the at-rest protection for the message store.
  • ☐ Enable Strict mode on fielded devices nobody monitors (Chapter 7).
  • ☐ Review whether discovery publishing and GPS sharing are appropriate for your radio footprint.

For desktop and Raspberry Pi relay nodes:

  • ☐ Use a dedicated, single-user OS account; the profile directory (~/.gridx) and its token file are the keys to the node.
  • ☐ Enable full-disk encryption where message confidentiality at rest matters.
  • ☐ Ensure OpenSSL-backed Python cryptography is installed (the engine logs its crypto backend at startup; prefer openssl, PyCA over the pure-Python fallback).
  • ☐ Change the WiFi hotspot SSID/passphrase from the sample values when deploying the Pi hotspot image (Chapter 11).
  • ☐ Restrict physical access to relay nodes; USB ports auto-provision radio hardware.
  • ☐ For segmented/private meshes, configure IFAC network name + passphrase on your interfaces (Chapter 12) so foreign Reticulum nodes cannot join your links.

10.6 What Stolo does not do

For clarity in security reviews:

  • No cloud storage of messages or keys; no server-side account data. The Stolo Gateway relays ciphertext only.
  • No remote wipe (v1). Physical device control and OS-level device management remain your controls.
  • No in-app key rotation (v1); identity lifetime is the install's lifetime.
  • Vendor verification badges assert software provenance, not operator identity, and gate nothing (Chapter 8).