Chapter 8 — Organizations & Vendor Verification¶
8.1 What an organization is¶
An organization (org) is a publisher identity — a cryptographic keypair that represents a team, company, or agency rather than a single device. Orgs solve the fleet problem: instead of every operator individually trusting every other device, you trust the organization once, and every device verified as a member of that org delivers messages directly.
Membership is cryptographic. A device that publishes under an org includes a signed membership claim in its announces — a signature by the org's key over that specific device's identity. Peers verify the signature before treating the device as an org member; a device cannot simply claim an org.
Orgs are managed under Settings → Network → Organizations.
8.2 Roles an org can have on a device¶
| Role | Meaning |
|---|---|
| Member / trusted org | You track the org's identity hash and (optionally) trust it. Trusting it delivers messages from all verified members. |
| Primary publisher | This device belongs to the org and signs its announces with the org's keyset. Exactly one org can be primary publisher per device, and it must have its keyset on the device. |
8.3 Managing organizations¶
From Settings → Network → Organizations:
- Join with hash — paste the org's 32-character identity hash (share this freely; it contains no secrets). The org starts untrusted; toggle Trusted explicitly once you're confident of the hash's provenance.
- Create new — generates a fresh org keyset on this device. Your own orgs are trusted automatically.
- Import keyset — import an existing org keyset file (exactly 64 bytes: the org's private keys). Handle keyset files like passwords — they let any holder sign membership claims for that org.
- Make primary publisher — designate a keyset-holding org as the identity this device publishes under. Requires an engine restart. Clear primary reverses it.
- Trusted toggle per org — grants/revokes fleet-wide inbound trust.
- Remove — stops tracking the org (refused while it is the primary publisher). Deleting a keyset file only ever touches files inside Stolo's identity storage.
The org list also drives a device tree in Settings → Network, grouping discovered devices under their verified orgs (with an UNAFFILIATED bucket).
If orgs exist but none is trusted, the Settings screen warns: incoming messages will be quarantined until at least one identity is trusted.
Operational recipes¶
Provision a fleet under one org:
- On an admin device, Create new org (or import your org keyset).
- Set it as primary publisher on each fleet device (import the keyset there), restart the engine.
- On every device that should hear the fleet, Join with hash using the org's hash and mark it Trusted.
- Optionally enable Strict mode on fielded devices so only the trusted org (and explicit trusted peers) can reach them.
Trust a partner agency: obtain their org hash out-of-band, Join with hash, mark Trusted. No keysets change hands.
8.4 Vendor verification ("genuine Stolo")¶
Independently of org trust, peers wear a vendor badge describing the app's provenance:
| Badge | Meaning |
|---|---|
| STOLO · VERIFIED | The peer's announce carries a valid vendor device certificate — the device was provisioned by Stolo. The certificate is bound to that specific device's identity, so it cannot be copied to another device. |
| STOLO | The peer announces the Stolo protocol tag but has no verified certificate. |
| UNKNOWN NODE | No Stolo mark seen — a foreign or older Reticulum node. |
Important: the vendor badge is a statement about the software, never about the operator. It is not a trust grant and it gates nothing — trust and blocking (Chapter 7) remain the access controls. Use the badge as a provenance signal when deciding whether to trust an unknown device.
Installing a vendor certificate¶
Certificates are issued by Stolo for a specific device identity and contain no secrets. To install one: Settings → Identity → Vendor certificate → Install vendor certificate, choose the certificate file, and confirm. Re-issuance is supported — installing a new certificate replaces the old one. Peers upgrade the device's badge to STOLO · VERIFIED live, as soon as they hear the next announce.