Crocodile Beta
English
Download

How it works

How Crocodile keeps your conversations yours

A tour of the architecture and the protocol in plain words. Each chapter starts with the idea; open “Under the hood” for the technical details.

Chapter 1

Four kinds of players

Crocodile splits the work so that the parts that see your words are the people you're talking to, and the parts run by strangers never do.

Your app

Holds your keys, encrypts everything you send and decrypts what you receive. Your message history lives here and nowhere else.

Knows: Everything you send and receive: it's yours.

The host

In each voice room or space, one member's app is elected to pass the encrypted traffic on to the others. It's a member like any other.

Knows: Members' IP addresses and who's speaking, never what's said.

Coordination servers

Volunteer-run switchboards: they keep profiles and spaces, say who's online and pick hosts. They link up into one network.

Knows: Profiles, memberships and who's online, never what's said.

The directory

A phone book of coordination servers, so new apps know where to start. It knows nothing about people.

Knows: Only the list of servers.

Chapter 2

Your account is a key, not a password

When you install Crocodile, your app makes a random secret, 32 bytes long, on your computer. From it come two keys: one to sign what you publish and one to receive encrypted messages. Your user ID is a fingerprint of the signing key.

Because the ID is calculated from the key, a server can't swap in a different key and pretend to be you. There's no password to steal and no reset that a support desk could be tricked into. The secret is shown to you once as a recovery key, and stays on your devices, encrypted with your system's keychain.

Under the hood
  • The 32-byte seed yields an Ed25519 signing key and an X25519 encryption key. The user ID is the first 26 characters of base32(SHA-256(signing public key)).
  • Each device publishes a signed device record with a prekey bundle (X25519 + ML-KEM-768) that rotates weekly. Old prekey secrets are deleted after a grace period.
  • Safety numbers let two people compare keys out of band, as in other secure messengers.
  • Local data (identity, prekeys, history) is encrypted at rest with a key protected by the operating system's keychain.

Chapter 3

Finding the fastest server

Your app downloads the list of coordination servers from the directory, measures how long each takes to answer, and connects to the quickest. The runner-up waits on standby, so if your server goes away your app switches over immediately.

Before anything else, the server proves who it is and your app and the server agree on keys for that connection. From then on even the metadata they exchange is encrypted, on top of HTTPS, so it works safely on a home server too.

Under the hood
  • The directory lists each server signed by that server, with its address obfuscated. Apps check the signature before using an entry.
  • The server's signed hello carries a fresh hybrid key-exchange offer (X25519 + ML-KEM-768). The app checks it against the key in the directory, answers and signs the transcript. Every frame after that is AES-256-GCM encrypted and padded.
  • Servers also answer STUN on two ports, so apps can learn their public address and NAT type without asking Google or Cloudflare.

Chapter 4

Servers that can't lie about you

Your profile, the spaces you create, their invites and who's a member are small records signed by whoever wrote them. Servers store and share them, and every server and every app checks the signatures. A server can refuse to pass a record on, but it can't change one or make one up.

Coordination servers find each other and form a mesh. Each record is kept by a few servers chosen by a hash, and they copy changes to each other, so the network keeps working when any one server goes down.

Under the hood
  • Records: profile, sealed friends list, space, invite, member, device and note. Each has an author who may write it; validation (signature, authority, last-writer-wins version) is identical on servers and clients.
  • Friend lists are encrypted for their owner's devices only, and friend requests travel as sealed notes that don't name their sender, so servers don't learn who's friends with whom.
  • Each record is owned by the first few servers on a consistent-hash ring for its shard. Owners replicate writes, catch up with sequence cursors and hand records over when servers join or leave.

Chapter 5

A friend hosts, a backup waits

When people join a voice room or open a space, the coordination server looks at everyone's connection (how open their network is, their upload speed, their computer, whether they're on battery) and elects the best-placed member as host. The next best is the backup.

Everyone connects to the host's app, which passes on the encrypted audio. To keep things light, it forwards the loudest few speakers to each listener. It never has the audio in the clear on its way through: it just moves sealed packets around.

If the host leaves or becomes unreachable, the backup takes over and everyone reconnects to it, usually before anyone notices.

Under the hood
  • The host runs a small SFU (selective forwarding unit) inside its app. Each member opens one WebRTC connection to it, with one upstream audio track, five downstream speaker slots and a data channel.
  • Speaker slots are assigned by the RFC 6464 audio-level header (“last-N”), with rewritten sequence numbers so each slot stays one continuous stream.
  • Offers and answers are signed with identity keys over the session, epoch, both IDs and the DTLS fingerprint, so a coordination server can't put itself in the middle.
  • Every host change bumps an epoch number; stale offers are ignored. Members who can't reach the host report it, and once half agree, the backup takes over.

Chapter 6

Encryption in layers

Everything is encrypted on your device before it leaves, and only the people in the conversation have the keys. Here is what happens to a message on its way out.

One message, four layers

Your app signs the message so others can prove it came from you, pads it so its length gives nothing away, encrypts it with a key only the conversation's members have, and sends it through a connection that is itself encrypted. Anyone in between sees only scrambled bytes of a standard size.

Ready for quantum computers

Keys are exchanged with a hybrid of X25519, a proven classic method, and ML-KEM-768, the new post-quantum standard. An attacker would have to break both. That matters because someone could record encrypted traffic today and wait for a quantum computer to decrypt it later.

Keys that move on

Each member's key turns like a ratchet: after every message it's replaced by the next one in a chain that only goes forward, and the old one is deleted. Someone who steals a key today can't read yesterday's messages. Every 30 minutes, and whenever someone leaves, everyone starts a fresh chain from new random keys, so a stolen key stops working soon too.

Voice, frame by frame

Your voice is encrypted in small frames, about fifty a second, right after the microphone and before it reaches the network. A frame that can't be encrypted is dropped, never sent in the clear. Voice uses a constant bitrate, so the size of the packets doesn't reveal what you're saying.

Under the hood
  • Pairwise secrets (sender-key distribution, history sync, device linking, server channels) combine X25519 and ML-KEM-768 (FIPS 203) through HKDF-SHA256.
  • Sender keys have two HKDF chains: the text chain advances after every message, the audio chain every 30 seconds. Keys are replaced every 30 minutes and on leave, and only sent to devices whose membership the app verified itself from signed records.
  • Voice: an Encoded Transform worker encrypts each Opus frame with AES-256-GCM and an authenticated SFrame-style trailer (key ID, generation, counter).
  • Text: author-signed (Ed25519), Padmé-padded, encrypted with the text chain.
  • Sealed boxes to a device use its current prekey and are signed by the sender, so even messages for offline devices get forward secrecy.

Chapter 7

When a direct connection isn't possible

Some networks, such as strict office or university firewalls, block direct connections between computers. Crocodile tells you when that happens, and you can choose to let a coordination server relay your traffic.

The relay passes on packets that are already end-to-end encrypted: it sees their size and timing, but not what's inside. Permission lasts an hour at a time and is renewed only while it's still needed.

Under the hood
  • The relay is standard TURN (RFC 5766) on the coordination server's UDP port, with short-lived credentials. Servers cap how many people may use it.
  • On connecting, the app checks its network against two STUN ports and classifies it as open, limited (symmetric NAT) or blocked, and offers the relay when needed.
  • Each connection records four steps (offer, answer, network path, encrypted channel), so when something fails the app can say where.

Chapter 8

Messages that find their way

No server keeps your history, so Crocodile's apps hand messages to each other. Here's what happens when you write to someone who's offline.

  1. It waits with you

    The message goes into your app's outbox and shows a small clock.

  2. They come online

    As soon as both of you are online, your app hands it over, sealed to their device.

  3. Confirmed

    Their app confirms receipt and the clock disappears. Members who missed messages in a space catch up from the host and the backup.

  4. Or use the mailbox

    Optionally, a server holds direct messages for up to 7 days, sealed per device so it can't read them, and deletes them once delivered.

Chapter 9

Adding a computer

Your new computer shows a short code. Type it into a computer where you're already signed in, then check that both screens show the same six-digit security code. If they match, your account is sent across, encrypted, and the new device is in.

The security code covers the keys of both devices, so if anyone tried to swap one in between, the codes would differ and you'd know.

Glossary

The terms you'll meet in security write-ups, in a sentence or two each.

End-to-end encryption
Only the sender and the recipients have the keys. Whatever carries the message in between, servers included, sees only scrambled data.
Peer-to-peer
Apps connect to each other directly instead of through a central server.
Post-quantum cryptography
Encryption designed to resist future quantum computers, which could break the methods most of the internet uses today. ML-KEM is the standard published by NIST in 2024.
Forward secrecy
Stealing a key today doesn't unlock past messages, because the keys used for them were deleted.
Post-compromise security
After a key is stolen, fresh random keys soon lock the thief out again. In Crocodile that happens within 30 minutes, or right away when someone leaves.
Digital signature
A mathematical seal made with a private key. Anyone can check it with the public key, and nobody without the private key can forge it.
NAT, STUN and TURN
Home routers hide computers behind one public address (NAT). STUN helps apps find their public address so they can connect directly; TURN relays traffic when they can't.
SFU
A selective forwarding unit passes audio from each speaker to each listener without mixing or decoding it. In Crocodile it runs in the host's app.
Metadata
Data about a conversation rather than its content: who talks to whom, when, and how much. Crocodile encrypts content completely and reduces metadata, but servers still see some.

Read the full architecture document