Documentation
How it works
This page describes what Crypto and Gotham actually do. Each section opens in plain language, then gives the technical detail for anyone who wants to check: protocols, formats, architecture decisions. The code of the Gotham network is public and can be read; the app’s code is not. Anything that is not yet in service is flagged as such.
01
End-to-end encryption
Only you and the person you write to can read your messages. Not us, not the operator of a server, not anyone listening on the network. That holds today, on every platform.
In detail: every session starts with an X3DH key exchange, a method that lets two devices build a shared secret together without ever sending it. The session then runs under the Double Ratchet: the key changes with every message. Crypto adds header-key rotation: at every ratchet step the frame’s own technical markers change too, not just the content key. Someone recording all the traffic therefore cannot group the frames of one conversation after the fact.
Forward secrecy
Message keys are used once, then discarded. Seizing a device tomorrow does not decrypt the traffic captured yesterday.
Post-compromise security
If an attacker gets hold of a key, the next exchange injects fresh randomness and heals the session. To keep reading, the attacker has to stay present continuously, and that continued presence is detectable.
Identities you can verify and revoke
Every pair of correspondents shares a safety number: a string of digits you compare over another channel, in person or by voice, to be sure you are talking to the right person (the Signal model). If a contact’s identity key changes, the application shows it and resets the session. Never silently.
An identity key can be rotated or revoked. A burned key terminates the live sessions that depend on it. It is not merely noted somewhere as invalid.
Post-quantum: the exact scope
A future quantum computer could break part of the cryptography in use today. The foundation already includes a hybrid ML-KEM-768 encapsulation, combined with X25519, on the application session, the one that protects your messages. Since version 2.3.0 that layer can no longer be silently stripped out of the negotiation: an intermediary who removed it makes the exchange fail instead of downgrading it. It does not cover the transport: every hop between relays relies on classical cryptography, since per-hop protection does not fit a packet’s 2048-byte budget. This is a migration under way, not a product that is "already post-quantum everywhere", and we refuse to write it any other way.
02
Transport anonymity: the Gotham network
Encryption protects what a message says. It hides neither its existence, nor its size, nor the fact that you wrote to a given person at a given time. Those traces, the metadata, often say as much as the content. Gotham is the network we are building to hide them: a mix network, where messages bounce from relay to relay and no relay ever sees both ends of the same route.
Where we stand today. That network does not route yet. To build a route, the application requires a different operator at every step of the route, so at least three operators independent of one another: it refuses, by construction, two relays it cannot prove belong to different people. Today every relay is run by one person, the project's author. The directory is already signed by three separate authorities, two of which must agree to admit a relay — but all three belong to that same person. The quorum protects against a single leaked authority key, not against one operator declaring their own relays to all three. This is not a matter of how many machines or address ranges there are. In the meantime your messages go through a mailbox, described in the next section: the relay operator can therefore see which IP addresses are exchanging, and when. The application states this plainly, under the label "Mailbox only". The content stays end-to-end encrypted in every case.
What follows describes the protocol as implemented, and the protection it will bring once enough independent relays are in service.
Onion routing (Sphinx)
Each message is wrapped in several layers of encryption, one per relay. A relay opens only its own layer and learns only the next step; it does know which step of the route it is at, and how many steps that route has, because the hop number travels in the clear. Every packet is exactly the same size, 2048 bytes, with a 384-byte header, and crosses up to five relays. An observer distinguishes neither the real length, nor the type, nor the recipient of a message. Each relay re-wraps the packet: what goes in and what comes out do not look alike.
LIONESS payload
The content is encrypted in wide blocks: flipping a single bit destroys the whole block. A relay therefore cannot slip a discreet mark into a packet in order to recognise it further down the path.
Delays and cover traffic (Loopix)
Each relay holds the packet for a random amount of time, drawn in advance by the sender. In parallel the client continuously emits decoy messages, on a random schedule of their own. A real send leaves on the same stream as the decoys: its timing does not give it away.
Sealed sender
The first relay on the path does not know which account is writing. Taking control of that relay does not yield the user list. The hop number does tell it, however, that its peer is a sender and not another relay: sealed sender hides who is writing, not the fact that the peer is writing.
Enforced path diversity
The client refuses two consecutive steps that belong to the same operator or to the same block of IP addresses (a /16 prefix in IPv4, /48 in IPv6), and it further refuses an entry and an exit under the same operator. A relay whose operator label is not proven never counts as a different operator. An actor controlling an entire data centre would therefore never hold both ends of one path. This is the rule that keeps the network from routing today: it demands three independent operators, and there is only one. We would rather not route at all than route badly. One caveat, which we write down rather than leave out: that operator label is currently declared by the relay itself and signed as-is by the authority, and it is one of the two findings still open in our register.
The anonymity of a mix network depends on how many independent relays are actually in service. It is an operational property, built one relay at a time, not a checkbox. It is not yet achieved. The exact limits are documented in the threat model.
03
Mailboxes and retrieval
When the person you write to is offline, the message has to wait somewhere. It waits in a mailbox: a server that holds the encrypted message until they come and collect it.
The mailbox is addressed by an identifier that says nothing about its owner and that changes with every directory epoch. It holds only encrypted blobs, all the same size. The host can read neither the content, nor the sender’s name, nor the recipient’s.
Each mailbox is guarded by a proof of possession: you have to prove you hold the recipient’s private key to touch it. Without that key a third party can neither read the mail nor delete it remotely: a collection is destructive, so it is reserved for whoever holds the key. What the host can do, however: lose or destroy the mail it holds. That shows up as a non-delivery, not as a leak.
Retrieval is designed to run through the Gotham network, using single-use reply blocks (SURBs): a return path prepared in advance by the recipient, which lets them collect their mail without handing their IP address to the host. The mechanism exists in the protocol. But as long as the network does not route, retrieval happens directly: the host sees the IP address that comes to collect the mail, and the time it does so. This is the most important limitation of the current version.
Rendezvous transport
Most consumer connections (4G, 5G, home routers) cannot accept an incoming connection: the operator shares one public address between thousands of subscribers. A machine in that situation can still host a relay, without opening a single port, by making the connection itself towards a rendezvous point. This is what makes a volunteer relay network genuinely deployable, beyond data-centre servers alone. The mechanism is specified in our B3 technical document.
04
Network governance
An anonymity network is only as good as its relay list. Anyone who can slip their own machines into it, or make you believe only a handful are left, takes back with one hand what the rest of the system protects with the other. That list is therefore treated as an attack target in its own right.
Signed directory, no rollback
The relay list is cryptographically signed (Ed25519) and the key that verifies that signature is pinned in the application. An authentic but stale list cannot be replayed to artificially shrink the choice of routes. Since version 2.4.1 that key can be replaced without a new binary: the authority publishes the chain of its successors, each link signed by both the old key and the new one. No rotation has taken place in production yet.
Admission by several voices
A relay must be attested by several independent authorities — two out of three must agree — before it becomes usable, so that no single key decides alone what the network is made of, ours included. The mechanism already runs in production on three separate hosts: leaking or compromising a single authority key is no longer enough to forge the network. But all three authorities belong to the same person today; protection against one operator declaring their own relays to all three will only come with authorities run by third parties.
Tamper-proof enrolment
When a relay enrols, its proof of possession covers the whole exchange, not just its key. An attacker on the network path cannot rewrite the declared address or operator in passing. Registration itself is locked behind a token issued by the authority’s operator.
Bounded exposed surfaces
Every network-facing entry point has an anti-replay cache, a rate limit and a memory cap. Flooding a server to make it unavailable is treated as an attack class, not as an operational hazard.
05
Data at rest
Everything the application keeps on your machine, messages, contacts and keys, is stored encrypted. Without your password, a recovered disk or a copied backup teaches nobody anything.
The local database is encrypted with SQLCipher. Its key is derived from your password by Argon2id, a deliberately slow and memory-hungry function that makes trying passwords one by one very expensive, dedicated hardware included.
A password change happens in one piece: the application takes a snapshot of the database, rewrites it with the new key, then destroys that snapshot once the new version is validated. The snapshot stays encrypted under the old password for the duration of the operation — that is what makes a power cut mid-way recoverable — and if it cannot be destroyed, the application writes that in its log instead of passing over it in silence.
06
Audio calls
Voice is end-to-end encrypted and never travels directly from one device to the other: it goes through a relay server. Your correspondent therefore does not see your IP address, and you do not see theirs.
What you should know. That relay is operated by us today. Its operator hears nothing of the conversation, but does see both IP addresses and the time you spoke. Calls do not go through the Gotham network and therefore do not get the anonymity Gotham aims for. If the mere fact of having called someone exposes you, take that into account.
On the technical side, the call engine is native, written in Rust, with no embedded browser WebRTC. Opus codec, real-time capture and playback, packet-loss concealment.
Relay-only by default
No direct connection between the two devices: no participant sees the other’s IP address. There is no "optimised" mode that would quietly degrade that.
Signed relay configuration
The application receives the media-relay list signed by the authority, and verifies that signature before using it. An attacker on the network path cannot appoint itself as the relay to capture the stream.
Two media relays per call
The stream is split across two distinct relay servers, so that no single operator sees both ends of one call. The split works, but both servers are ours for now: in practice, one operator does see both ends. That separation only takes on its full meaning the day an independent third party runs one of them.