Magic Wormhole is a small open-source tool, originally written by Brian Warner, for moving a file or a short message directly between two computers. The sender runs a command and gets a code. The receiver types that code into their own copy of the tool. The two programs find each other, agree on a strong encryption key, and transfer the file end-to-end encrypted. When it finishes, the code stops working.
The workflow is deliberately human. The code is not a 40-character token you paste, it is a number and two words drawn from a fixed list, short enough to read over the phone or type from memory. That design decision is what makes the tool pleasant, and it is exactly the decision that should worry a security-minded reader. A short, low-entropy secret is normally an invitation to guess.
The Problem a Short Code Creates
Think about what the code has to do. It is the only shared secret between two machines that have never spoken before. If the tool simply used the code as a password to derive an encryption key, an eavesdropper who captured the handshake could sit offline and try every possible code against it until the traffic decrypted. With only a few thousand possibilities in a two-word code, that search finishes in seconds.
A naive design has to choose between two bad options: make the code long and ugly so it resists offline guessing, or keep it short and accept that it is weak. Magic Wormhole refuses that trade by using a different kind of cryptography for the exchange.
The danger of a weak password is offline guessing, where an attacker tests billions of candidates against captured data with no one watching. A PAKE removes that ability. Each guess costs the attacker one live, interactive attempt, and a wrong guess simply aborts the connection.
What a PAKE Actually Does
The mechanism is a Password-Authenticated Key Exchange, or PAKE. Magic Wormhole uses one called SPAKE2. A PAKE is a protocol that takes a shared low-entropy secret, the wormhole code, and produces a shared high-entropy encryption key, without ever sending the code or anything an eavesdropper can test offline.
The property that makes this work is the one worth internalizing. In a correct PAKE, an attacker who watches the entire exchange learns nothing that lets them check a guess at the password later. The only way to test whether a given code is correct is to actively participate in a fresh handshake using that guess. Guess wrong and the protocol fails; you learn only that this one guess was wrong, and you have to start over online. There is no captured transcript to grind against in a data center.
This is the same family of protocol behind SRP and the more modern OPAQUE, which let a server verify a password without ever seeing it. Magic Wormhole applies the idea to a peer-to-peer setting where the shared secret is a throwaway code rather than a stored password.
How the Transfer Flows
A few supporting pieces make the connection happen:
- The rendezvous server is a lightweight meeting point. Both sides connect to it and use the numeric prefix of the code as a channel identifier to find each other. It relays the PAKE handshake messages but never learns the encryption key, so it cannot read the file.
- The word list is the same even and odd PGP word list used for reading byte values aloud, chosen so the words are phonetically distinct and hard to mishear.
- Direct connection or transit relay. After the key is established, the tool tries to open a direct encrypted connection between the two machines for the bulk data. If a firewall or NAT prevents that, it falls back to a transit relay that forwards the already-encrypted bytes without being able to decrypt them.
The result is that the two servers involved see only ciphertext and routing metadata. The plaintext exists on the sender's machine and the receiver's machine, and nowhere in between.
Where It Fits, and Where It Does Not
Magic Wormhole is at its best for a one-time, interactive transfer between two people who can exchange a short code over a channel they trust, a voice call, a signal message, sitting side by side. Because the code is single-use and the security leans on a live handshake, it is a poor fit for asynchronous drops where the recipient is not online, or for publishing something to many people.
| Tool | Best when |
|---|---|
| Magic Wormhole | Both parties online now, one file, code shared over a trusted channel. Interactive and quick. |
| OnionShare | Anonymous drop over Tor, recipient can fetch later, sender wants to hide their address. See our OnionShare guide. |
| Syncthing | Ongoing, continuous sync of folders between your own devices. See Syncthing. |
One caution worth stating plainly: the security of the whole exchange rests on the channel you use to communicate the code. If an attacker can intercept and substitute the code before the receiver uses it, they can insert themselves as a live participant, which is the one attack a PAKE cannot rule out on its own. Read the code to the other person over a channel you already trust, and confirm they got the same words you sent.
The Broader Lesson
Magic Wormhole is a clean demonstration of a principle broader than one utility: usability and strong cryptography are not opposed when the protocol is chosen well. A short code feels weak because most systems that use short codes are weak. The PAKE changes the underlying rules so that a memorable secret carries the same practical safety as a long random one, as long as nobody can guess it online in a handful of tries.
That is the same instinct behind good passphrase design and behind Haven's own approach to keys: derive strong material on the device, keep the human-facing surface simple, and never let a convenience choice quietly weaken the cryptography underneath it.