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. Every claim is verifiable in the source code. 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 on the application session, the one that protects your messages. It does not yet cover every hop of the Gotham network. 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 knows the whole path.
Where we stand today. That network does not route yet. To build a route, the application requires relays in at least three distinct network address ranges, run by different operators. There are only two so far. 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. 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.
Enforced path diversity
The client refuses any route whose entry and exit belong to the same operator, or to the same block of IP addresses (a /16 prefix in IPv4, /48 in IPv6). An actor controlling an entire data centre would never hold both ends of one path. This is the rule that keeps the network from routing today: it demands three distinct blocks, and the network covers only two. We would rather not route at all than route badly.
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. 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 it is impossible to read the mail, and equally impossible to delete it. A hostile host cannot quietly disappear a user’s messages.
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 two 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.
Admission by several voices
A relay must be attested by several independent authorities before it becomes usable, so that no single key decides alone what the network is made of, ours included. The mechanism is written and tested; it takes effect as authorities run by third parties come into place.
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.
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 purges the old version once the new one is validated. At no point does a copy readable with the old password exist.
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.