Threat Model
The relay that connects your machines is treated as an attacker for everything it carries. This page states what that attacker cannot do, which model or test checks each statement, what is not protected, and what the relay still sees. Each measured number names its setup and its limits.
The attacker
For the data of a session, the attacker is the relay: its operator, every relay and replica a session crosses, the links between them, the network around them and anything they store. It can read, change, replay, reorder, drop and inject every message it carries, issue itself certificates for its own domain, and run machines of its own on the same relay. It does not hold the keys that stay on your machines: the organisation's root, the issuer's key and each machine's own key.
The relay is trusted for nothing about secrecy or authenticity. It is relied on for availability only: a hostile relay can always delay or refuse a session, and nothing on this page says otherwise.
The scope is the network layer: machine identity in an organisation, the end-to-end encrypted sessions between enrolled machines, direct paths, revocation, peer-to-peer transfers with a key file, and capability addresses.
Architecture
| Part | Where it runs | What it holds |
|---|---|---|
| Organisation root | The owner's machine, offline from the relay | The root key. It certifies the issuer and signs root rotations, with a separate recovery key. |
| Issuer | One machine of the owner's | The issuer key. It enrols machines from single-use tokens, renews their certificates and publishes the revocation list. |
| Enrolled machine | Every machine of the organisation | Its own key and certificate, its groups, the root's fingerprint (delivered by your own provisioning, never by the relay) and the current revocation list. |
| Relay | nfltr's hosted service, or a machine of yours | Accounts and routing. It passes sessions between machines that each keep one outgoing connection to it, and it carries the enrolment, renewal and revocation messages, which it cannot forge. |
A session between two enrolled machines is a TLS 1.3 session from end to end, inside a stream the relay carries. Each end checks the other's certificate against the organisation's root, the name it asked for, the certificate's expiry and the revocation list, and the serving end admits only the groups the service names. When the two ends can reach each other and neither has turned direct paths off, the same session moves to a direct UDP connection between them under the same certificates, and returns to the relay when that path fails.
What is proven
Two kinds of model are checked on every change. A symbolic model of each end-to-end path, checked with ProVerif, gives the attacker above every relay and the keys of a rogue enrolled machine, a revoked one and an expired one. State-machine models, checked with TLA+, cover enrolment, revocation, moving the issuer and the direct path. Each model also contains planted mistakes (skip the certificate check, accept a key from the relay, fall back to plain on the relay's word), and each mistake must make a proof fail: 88 such mistakes in the symbolic models and 58 in the state-machine models of this scope.
| Path | Proven against a hostile relay |
|---|---|
| Session between enrolled machines, through the relay | The bytes a client sends reach only the service of the machine it named, and both ends agree on the session. A rogue, revoked or expired machine is refused at the client and at the service. Only machines of the service's groups are admitted. An end the application sees as clean is the other end's clean close: a relay that cuts a session shows as a reset, never as a complete transfer. A group dial reaches only a service a machine of that group publishes. There is no downgrade to plain on the relay's word. |
| The same session on a direct path | What the client sends on a direct connection reaches only the agent of that session; the two ends agree on both the session key and the direct connection's key; the agent binds a direct connection only to the session's own client; no other machine's certificate is taken, wherever the relay pointed the client. A group dial cannot be moved to another instance. |
| Streams on a direct path | Bytes arrive in order, none is lost, and a stream goes only to the peer that proved the session, never to an address the relay chose. When the direct path dies, the relayed path carries the session on. |
| Enrolment | Only names the issuer issued are accepted; tokens are single use and bound to their name; a revoked machine is refused, also after it tries to renew; a root rotation needs the recovery key. |
| Revocation | A bounded time after a revoke, no machine that verifies holds a session with the revoked machine, whatever revocation lists the relay delivered, an older list replayed included. |
| Moving the issuer | The issuer key reaches only the new machine; the root key never leaves the owner's machine, also after the new machine is compromised. |
| Peer-to-peer transfers with a key file on both ends | Secrecy and authenticity of the data, media included. |
| Capability addresses | Secrecy both ways; a session goes only to the key the address pins; admission needs the address's secret; a relay that sees an address's server key and its sessions cannot produce another address's pin; the direct path keeps the same pin. |
TLS 1.3 and SSH are not proven again: each is taken as an authenticated channel to whoever holds the key the other end checked, as their published analyses show. What the models prove is how each end learns and checks the other's key.
From the models to the code
A model is only as good as its match with the code. Every field a model binds (a name, a certificate, a token, a key) has a binding test: it takes an honest message, changes that one field as a relay could, and requires the code to refuse it. There are 32 such rows in this scope. The enrolment and peer-to-peer models list no such fields yet, so their match with the code rests on ordinary tests. The state-machine models also check traces: the code's own tests record their steps, and every recorded step must be a step of the model.
What is not proven or not protected
- Availability. A hostile relay can delay, drop or refuse any session, and withhold a revocation list or a root rotation.
- A withheld revocation. A machine reads the revocation list again on its own: a relay that withholds the push delays a revoke until that fresh read, up to 10 minutes, and up to the list's one-hour life if it withholds every read.
- First use. The root's fingerprint and a machine's token are only as good as the way they reached the machine. A fingerprint read from anything the relay shows protects nothing.
- A stolen issuer key, within its groups, until its certificate ends after 30 days or the root rotates.
- SSH host certificates of a revoked machine, until the certificate ends (at most 24 hours): OpenSSH reads no revocation list.
- Peer-to-peer without a key file. The relay hands out the keys and can sit in the middle; only comparing fingerprints on both machines detects it.
- Share links against a hostile relay. A relay can be issued a certificate for its own domain, so a share link is protected end to end only when the sharing machine holds a certificate of its own for the link's host name.
- Model bounds. Each state-machine model is checked for small constants (a few machines, a few messages, short certificate lives), and the direct-path model leaves revocation to the enrolment model, since a direct connection carries the same certificates.
- Not modelled: two agents on one machine serving the same organisation name; the keys of a capability address link two addresses that share a server key.
What every relay sees
| The relay sees | The relay does not see |
|---|---|
| The account, each machine's name and groups, which machine opens a session to which service, when, for how long, and how many bytes in each direction; each machine's address toward the relay, and its public UDP address when the machine asks the relay for it before a direct path; that a session asked for a direct path and when it fell back. | The bytes of an end-to-end encrypted session, on either path; the addresses the two ends exchange for a direct path (they travel inside the session's TLS); keys that stay on your machines. |
| The plaintext of tunnels and sessions run with end-to-end encryption off, and of share links whose machine holds no certificate of its own for the link's host name. | The content of peer-to-peer transfers with a key file. |
On a direct path, each end learns the other's public address and port and its LAN addresses. Direct paths are on by default in organisation mode; off (direct: false, --direct=off, nfltr config set-direct off) is the opt-out, and hides the machine's addresses from its peers.
Revocation
Revoking a machine (nfltr org revoke <name> where the issuer runs) publishes a new revocation list. The relay carries it to every machine, each end checks its open sessions against it, and the session with the revoked machine ends, on the relay or on a direct path. Once the new list has reached an end, that end refuses every new session with the revoked machine.
Evidence: a revoked machine's live session
- Setup
- The NAT lab: Linux containers (Docker) on one 16-core Linux build machine, November 16, 2026, the released v2.1.67 code, the relay built from it. Two client networks behind NAT routers (cone and cone, so a direct path forms), a private relay, the issuer in a container of its own. Each run enrols a fresh machine and holds a session that sends a line every 100 ms and reads its echo, then runs
nfltr org revokewhere the issuer runs. The time is from just before the revoke to the session's end as the client reports it. Four variants, 20 runs each over two runs of the lab: the client revoked through the relay, the client revoked on a direct path, the serving machine revoked on a direct path, and a group-dialled direct session with its client revoked (p50 0.13 s, max 0.15 s). - Numbers
- Through the relay: cut in 20 of 20 runs, p50 0.13 s, max 0.17 s. On a direct path, the client revoked: p50 0.12 s, max 0.17 s. On a direct path, the serving machine revoked: p50 0.13 s, max 0.17 s. Every new session after the revoke refused: 80 of 80 runs, the first new session already refused in each.
- Reproduce
- (a) With the released binaries: enrol two machines as the Organisations guide does, hold a
nfltr cat pipesession open to a service of the other machine, runnfltr org revoke <name>where the issuer runs, and time the session's end. (b) Our check, in the closed nfltr repository, runs the lab and judges each run by its exit code:make conformance-direct-evidence. - Limits
- One machine's containers: the relay and both ends are a network bridge apart, so the time is the issuer's publication, the relay's push and each end's check, with no network distance; a real network adds the round trips from the issuer to the relay and from the relay to the end. A relay that withholds the push delays the cut until the end's own fresh read (see above). The build machine ran other jobs at the same time (load average 7 to 9 on 16 cores). Twenty runs per variant show no tail.
Measured: direct and relayed sessions
Evidence: the same session, direct and through the relay
- Setup
- The same NAT lab and machine as the revocation runs (Linux containers on one 16-core build machine, November 16, 2026, v2.1.67), the routers cone and cone. One end runs a perf sink, the other
nfltr cat perfagainst it, end-to-end encrypted, 10 s per run, one upload session, once on a direct path and once through the relay, with the client's router unshaped and shaped to 50 Mbit/s. Five runs of each; the numbers are their medians. The round trip is timed on a second channel of the same session, idle before the upload and every 100 ms during it. - Numbers
- Round trip, idle, p50: direct 0.66 ms, relayed 0.94 ms. Round trip under load on a 50 Mbit/s link, p50: direct 72 ms, relayed 88 ms. Throughput: direct 47.5 Mbit/s, relayed 47.6 Mbit/s. Bytes through the relay for a direct session: 11 kB of the 60.6 MB sent. Client CPU per MB at 50 Mbit/s: direct 23 ms, relayed 1.6 ms.
- Reproduce
- (a) With the released binaries: with direct paths on (the default in organisation mode), serve a perf sink on one enrolled machine (
nfltr cat serve <name> --perf) and runnfltr cat perf <machine>.<agent>/<name> --jsonfrom the other, once with--directand once with--relayed. (b) Our check, in the closed nfltr repository, runs the lab's perf campaign in rounds:make conformance-direct-evidence-perf. - Limits
- One machine's containers, so the unshaped round trip is a bridge's, with no network distance, and unshaped throughput is bound by the machine's CPU (a median of 1.6 Gbit/s on either path, varying from 1.4 to 2.6 Gbit/s with the other jobs it ran, load average 7 to 11 on 16 cores); on the shaped link both paths fill the link and the round trip under load is the router's queue. The CPU figures are at 50 Mbit/s: a direct path costs the client more CPU per byte: unshaped 5.0 against 1.9 ms per MB, and on macOS loopback 3.4 against 0.7 ms. A pair whose router maps each destination to a new port (symmetric) stays on the relay, as designed. Five runs are no distribution tail.
Measured: an appliance in a customer's network
A vendor's appliance runs Postgres at a customer's site, behind the customer's NAT router, listening on its own loopback only. The vendor's support laptop, behind another NAT router, reaches it through the relay or on a direct path. One scripted run checks each claim by an exit code or a JSON event the commands print.
Evidence: a support laptop, an appliance's Postgres and the relay
- Setup
- Linux containers (Docker) on one 16-core Linux build machine, November 16, 2026, three runs at one commit, the relay built from it. The appliance (Postgres 17.6, listening on 127.0.0.1 only, and
nfltr upserving it aspg: {tcp: 5432, e2ee: true, allow_group: [support], direct: true}) behind one NAT router, the support laptop behind another (both cone), a private relay, the issuer in a container of its own, and a third machine of the vendor's in group ops. Every machine enrols withnfltr org joinfrom a single-use token; the laptop runspsqlthroughnfltr cat forward. - Numbers
- In each of 3 runs: the appliance's only TCP listeners are on loopback; the machine outside group support is refused (exit 10); with
--directthe session's path is direct 0.13 to 0.15 s after it began and the query answers; with--direct=offa 392 kB answer (a marker row 8000 times) comes through the relay, both sessions end-to-end encrypted by their open event; a capture on the relay's interface during that query holds about 406 kB from the appliance's router and 408 kB toward the laptop's, and the marker's bytes 0 times;nfltr org revokeof the laptop ends its held directpsqlsession 0.07 to 0.10 s later, the first new session is refused (exit 10) and a newpsqlconnection fails;nfltr org audit --verifychecks the issuer's log, which names the three enrolments and the revoke. A run takes about 70 s, 48 s of it building and starting the lab. - Reproduce
- (a) With the released binaries: enrol the appliance and the laptop as the Organisations guide does, serve Postgres on the appliance with the
pgline above in itsnfltr upfile, runnfltr cat forward <machine>.<agent>/pg --listen 127.0.0.1:15432 --direct --log-format jsonon the laptop andpsql -h 127.0.0.1 -p 15432; capture on the relay withtcpdumpwhile it runs; thennfltr org revoke <laptop>where the issuer runs andnfltr org audit --verify. (b) Our check, in the closed nfltr repository, runs all of it and judges each step by its exit code:make demo-appliance. - Limits
- One machine's containers, so the times have no network distance (a real network adds the round trips between the issuer, the relay and each end). The capture is the relay's network interface: the connections to the relay are TLS themselves, so the capture shows what an observer of the relay's network sees; that the relay process cannot read the session rests on the session's end-to-end encryption (its open event) and the models above, not on the capture. Three runs show no distribution tail. The build machine ran other jobs at the same time (load average 9 to 13 on 16 cores).
Next
- Organisations: enrolment, groups, direct paths and revocation, step by step.
- End-to-end encryption: each encrypted path and how to verify it.