Magic Wormhole is a small tool by Brian Warner for getting things from one computer to another. Its interface is deliberately human. There are no accounts, no public keys to exchange in advance, no links to paste. One side offers a file, the tool prints a short code, and the other side types that code to receive it. The whole trust model rests on one channel a machine cannot easily forge: a person's voice, saying three short tokens to another person they recognize.
That sounds too flimsy to be secure. A code with that little entropy should be trivial to guess. The reason it is not comes down to the cryptographic primitive underneath, and it is worth understanding because the same idea shows up anywhere humans need to bootstrap strong keys from something weak.
The Code Has Two Parts
A wormhole code looks like 7-crossover-clockwork. The leading number is a channel identifier, called a nameplate. It tells a small introduction server, the rendezvous server, which mailbox the two sides should meet in. The number is not secret. Anyone can see it, and that is fine.
The words after it are the secret. They are drawn from a fixed wordlist, the same even-and-odd PGP wordlist designed so that two words are unlikely to be confused when spoken. Those words, and only those words, are the shared password that the two sides feed into the key exchange. The sender's tool generates the whole code and the receiver types it in, so the secret only ever exists in two places: the two endpoints, and the mouth and ear of the humans relaying it.
The number routes the connection and can be public. The words are the secret and must travel over a channel the attacker does not control, which is why you say them aloud rather than send them over the same network. Separating routing from secrecy is what lets the secret stay short.
SPAKE2: Turning a Weak Secret Into a Strong Key
The engine that makes this safe is a password-authenticated key exchange, or PAKE. Magic Wormhole uses one called SPAKE2. A PAKE is a specific and slightly magical class of protocol: two parties who share a low-entropy password can end up with a strong, random session key, in a way that reveals nothing useful to an eavesdropper and gives an active attacker only a single online guess at the password.
Contrast that with the naive approach of hashing the password and sending the hash. An eavesdropper who captures that exchange can take it offline and try billions of candidate passwords per second against it. A three-word code would fall in moments. SPAKE2 is built specifically so there is nothing to take offline. The messages exchanged do not let an observer test password guesses at all. This is the same reason we favor OPAQUE-style authentication over sending a password hash to a server.
A password-authenticated key exchange converts an offline attack, where the adversary can guess as fast as their hardware allows, into an online attack, where every guess costs one live interaction and is immediately visible. The property that makes short codes viable
Mechanically, SPAKE2 is a Diffie-Hellman key agreement with the password blended into the exchanged values using fixed public constants. If both sides used the same password, the math cancels out and they compute an identical shared key. If they used different passwords, they compute different keys and the transfer simply fails to confirm. There is no partial credit and no leakage. If the two derived keys do not match, the protocol aborts before any file data moves.
What an Attacker Actually Gets
Picture an adversary sitting on the network, watching the rendezvous server, seeing every message. They know the nameplate number because it is public. What they do not have is the words. Their only avenue is to try to be the receiver before the real one shows up, guessing the words to impersonate the far end.
- One guess, then they are caught. A wrong guess produces a non-matching key, the honest party's transfer fails to confirm, and the attempt is over. The mailbox is single use.
- No offline grinding. The captured traffic contains nothing that lets them test candidate codes on their own hardware. Every attempt requires a live round with an honest party.
- Detection is built in. A failed confirmation tells the honest user something went wrong, which is a signal to stop and try again with a fresh code.
This is why the code can be short. The security does not come from the code being hard to guess in a vacuum. It comes from the code only being guessable one interaction at a time, against a target who will notice the failure. The PAKE is doing the heavy lifting the entropy cannot.
After the Handshake: Moving the Bytes
Once both sides hold a matching session key, the introduction is done and the rendezvous server has served its purpose. The actual file is encrypted with that session key and sent over a separate transit path. The tool first tries to open a direct connection between the two machines. When a direct path is not reachable, because of firewalls or network address translation, it falls back to a transit relay that forwards the encrypted stream without being able to read it. The relay sees ciphertext and connection metadata, never contents.
This division of labor is clean. A tiny rendezvous server handles the low-bandwidth introduction. Bulk data flows directly or through a dumb relay. No component in the middle ever holds a key capable of decrypting the file, which is the same principle behind well-designed secure file sharing and metadata-conscious tools like OnionShare.
Where the Trust Really Lives
The security of a wormhole transfer reduces to one human question: did the words reach the right person over a channel the attacker could not tamper with? If you read the code aloud to someone whose voice you recognize, that condition holds and the cryptography does the rest. If you paste the code into a chat that an adversary controls, they can race to receive the file first, and no amount of clever mathematics saves you, because you handed the secret to the wrong party.
That is not a weakness of the design so much as an honest boundary of it. Magic Wormhole solves the cryptographic problem completely and hands the remaining human problem back to you plainly: protect the words. It is a small, sharp example of a pattern worth recognizing everywhere in security. The strongest protocol still has an edge where a person decides who to trust, and the whole system is only as sound as that decision.