Magic-Wormhole: communicate a secret easily

The problem

Here is a common scenario we have all run into: you need to communicate some piece of secret information, say a password, to another person. Perhaps it’s on-boarding a new colleague, or to allow access for a partner. But you don’t want to compromise this secret by transmitting it over an insecure channel, such as a plain email. You could use encrypted email, but unless you have it already setup, that’s another non-trivial procedure to go through. Cloud-based solutions such as Dropbox are not encrypted and require you to trust the service.

Magic-Wormhole offers a simple solution to this problem, illustrated by a reference to the great xkcd. It allows to easily create a short-term secure channel that exists just long enough for the actual secret to be transmitted. The only requirements are for each participant to install the tool and to be able to communicate with each other directly, for example over the phone. Imagine two wizards pronouncing the same magic spell, and a wormhole appearing between them. 🙂

Simple example

Once the tool is installed, the sender runs:

$ wormhole send --text MY-SECRET-PASSWORD
Sending text message (18 Bytes)
Wormhole code is: 3-passenger-watchword
On the other computer, please run:

wormhole receive 3-passenger-watchword

The system responds with the “magic formula”, in this case 3-passenger-watchword. The sender then communicates it to the receiver, perhaps over the phone.

As suggested in the output above, the receiver then runs:

$ wormhole receive 3-passenger-watchword

That’s it!


When sending, Magic-Wormhole generates a simple code, then executes a Password-authenticated key agreement protocol to generate a strong key. The whole exchange then uses this key to encrypt the transmitted data. The idea is that the short duration of the channel limits the attack window.

As you can read on the project page, Magic-Wormhole can do more than this simple example suggests:

  • Users can exchange arbitrarily-sized files.
  • Instead of a single file, users can exchange whole directories.
  • Optionally using Tor increases the anonymity of the exchanges.
  • There is an API available for specific needs and integration into apps.

The system relies on a couple of services (“rendez-vous server” and “transit relay”) to act as mediators between the participants. By default, the tool uses services hosted by the project, but for more reliability and security, you can install them on your own premises.

Interestingly, while the original project is developed in Python, a Go port and a Rust port have since appeared.

The next time you find yourselves with the need to transfer a secret with minimal hassle, give Magic-Wormhole a try, it might just be what you were looking for!

— Christian