Early in the protocol a shared secret is established, after which all peer-to-peer traffic is encrypted with keys derived directly from the shared PAKE secret. The section Known Vulnerabilities has more details about failure modes.
If such a guess is successful, one of the two intended peers will notice: their connection will fail, typically with a “crowded” or “scary” error.
This construct allows for human-sized codes to be used while still maintaining high security. Each code is one-time use only , so attackers (e.g. a malicious Mailbox server) get only a single guess when attempting to subvert a connection.
Magic Wormhole exists (at least partly) so more software can use a cryptographic construct called “Password Authenticated Key Exchange” (PAKE), currently using the SPAKE2 variant.
Regardless, in the end a connection is established to pass end-to-end encrypted messages between two peers (and only two peers).
If the peers are on the same LAN, they will communicate directly over the local network. When one peer has a routable, public IP address they will also communicate directly. In case both peers are behind a NAT (or otherwise can only make outbound connections) the “Transit Relay” server is used to relay messages (which are all encrypted) between the peers.
Initial and relatively small messages are sent via the “Mailbox” server. This lets the two peers contact a well-known resource, and send the initial PAKE messages. After establishing this shared key, the peers bootstrap via further messages over the Mailbox. See Client-to-Client Protocol for more details.
Magic Wormhole has several methods to connect peers. A peer uses network “hints” to suggest these ways to the other peer. This allows considerable flexibility and can succeed in many different network conditions.
Magic Wormhole can send any sort of message, though, including messages making up streams – for example, Fowl does exactly this. fowl is built on a feature called “Dilation”; see The Dilation Protocol for more detail.
Traditionally transferring files is hard, even in 2025. The first and most popular “Thing” is a file or directory. For more on this, see the File-Transfer Protocol
... continue reading