PyCon 2016 in Portland, Or
hills next to breadcrumb illustration

Wednesday 1:10 p.m.–1:40 p.m.

Magic Wormhole: Simple Secure File Transfer

Brian Warner

Audience level:


"magic-wormhole" is a simple tool to move files from one computer to another, like "scp" but without the setup. By telling the recipient just a few secret words, the file is safely encrypted and delivered directly to the correct machine. The talk will explain the security mechanics, the cryptography (NaCl and SPAKE2), and how to use the underlying open-source library in your own applications.


The **magic-wormhole** tool (`pip install magic-wormhole`) is designed to be the easiest possible way to get a file or directory safely from one computer to another. All other common tools (email, HTTP server upload, shared network drives, Dropbox-like services, Airdrop, USB drives) either involve more typing, reveal the file to more people than necessary, or allow outsiders to corrupt the file in transit. It's made for two people to use: one running `wormhole send`, the other running `wormhole receive`. They might be sitting next to each other, talking by telephone, or chatting through IRC. It works a bit like `scp`, except: - the sender doesn't specify a target hostname - the receiver doesn't need to authorize a public key ahead of time - the two machines don't need to be on the same network The program generates a short "invitation code", consisting of a few simple words. The sender speaks or sends this single-use code to the recipient, who types it into their own machine. This gives the two programs enough information to find each other and negotiate the transfer details. A cryptographic algorithm called "PAKE" (Password-Authenticated Key Exchange) allows the two sides to generate a strong encryption key from this (weak) secret invitation code. The wormhole program attempts to transfer the encrypted file through a direct connection between the two computers, but if this fails (e.g. when they are on different NAT-protected networks), it will fall back to relaying the data through a central server. The magic-wormhole [project]( includes a library with a simple API, so you can use this same functionality in your own client-side applications. When signing up a new user, rather than having them dictate a (weak) password to the server, why not have the server "invite" them with a wormhole code? The setup process is easier (nothing to memorize), and the security is way better. This talk will introduce the tool, describe the network architecture, explain the cryptographic techniques, and dive into the library API.