magic-wormhole/README.md

# Magic Wormhole

Get things from one computer to another, safely.

This package provides a library and a command-line tool named `wormhole`,
which makes it possible to get short pieces of text (and arbitrary-sized
files) from one computer to another. The two endpoints are identified by
using identical "wormhole codes": in general, the sending machine generates
and displays the code, which must then be typed into the receiving machine.

The codes are short and human-pronounceable, using a phonetically-distinct
wordlist. The receiving side offers tab-completion on the codewords, so
usually only a few characters must be typed. Wormhole codes are single-use
and do not need to be memorized.

## Motivation

* Moving a file to a friend's machine, when the humans can speak to each
  other but the computers cannot
* Delivering a properly-random password to a new user via the phone
* Supplying an SSH public key for future login use

Copying files onto a USB stick requires physical proximity, and is
uncomfortable for transferring secrets because flash memory is hard to erase.
Copying files with ssh/scp is fine, but requires previous arrangements and an
account on the target machine, and how do you bootstrap the account? Copying
files through email first requires transcribing an email address in the
opposite direction, and is even worse for secrets, because email is
unencrypted. Copying files through encrypted email requires bootstrapping a
GPG key as well as an email address. Copying files through Dropbox is not
secure against the Dropbox server and results in a large URL that must be
transcribed.

Many common use cases start with a human-mediated communication channel, such
as IRC, IM, email, a phone call, or a face-to-face converation. Some of these
are basically secret, or are "secret enough" to last until the code is
delivered and used. If this does not feel strong enough, users can turn on
additional verification that doesn't depend upon the secrecy of the channel.

The notion of a "magic wormhole" comes from the image of two distant wizards
speaking the same phrase at the same time, and causing a connection to be
established between them. Transferring files securely should be that easy.

## Design

The `wormhole` tool uses PAKE "Password-Authenticated Key Exchange", a family
of cryptographic algorithms that uses a short low-entropy password to
establish a strong high-entropy shared key. This key can then be used to
encrypt data. `wormhole` uses the SPAKE2 algorithm, due to Abdalla and
Pointcheval[1].

PAKE effectively trades off interaction against offline attacks. The only way
for a network attacker to learn the shared key is to perform a
man-in-the-middle attack during the initial connection attempt, and to
correctly guess the code being used by both sides. Their chance of doing this
is inversely proportional to the entropy of the wormhole code. The default
(which can be changed) uses 16-bit codes, so for each use of the tool, an
attacker gets a 1-in-65536 chance of success. As such, users can expect to
see many error messages before the attacker has a reasonable chance of
success.

## Timing

At present, the two clients must be run within about 3 minutes of each other,
as they will stop waiting after that time. This makes the tool most useful
for people who are having a real-time conversation already, and want to
graduate to a secure connection.

Future releases should increase that to several hours. This will enable a
mode in which two humans can decide on a code phrase offline, by choosing a
channel number and a few random words, and then go back home to their
computers later and begin the wormhole process. (This mode is already
supported, but is not currently easy to use because the two users must type
the phrases within three minutes of each other).

## Relays

The wormhole library requires a "Rendezvous Server": a simple relay that
delivers messages from one client to another. This allows the wormhole codes
to omit IP addresses and port numbers. The URL of a public server is baked
into the library for use as a default, and will be freely available until
volume or abuse makes it infeasible to support. Applications which desire
more reliability can easily run their own relay and configure their clients
to use it instead. Code for the Rendezvous Server is included in the library.

The file-transfer commands also use a "Transit Relay", which is another
simple server that glues together two inbound TCP connections and transfers
data on each to the other. The `wormhole send-file` mode shares the IP
addresses of each client with the other (inside the encrypted message), and
both clients first attempt to connect directly. If this fails, they fall back
to using the transit relay. As before, the host/port of a public server is
baked into the library, and should be sufficient to handle moderate traffic.

The protocol includes provisions to deliver notices and error messages to
clients: if either relay must be shut down, these channels will be used to
provide information about alternatives.

## CLI tool

* `wormhole send-text TEXT`
* `wormhole receive-text`
* 
* `wormhole send-file FILENAME`
* `wormhole receive-file`

All four commands accept:

* `--relay-url URL` : override the rendezvous server URL
* `--transit-helper tcp:HOST:PORT`: override the Transit Relay
* `--code-length WORDS`: use more or fewer than 2 words for the code
* `--verify` : add extra verification

## Library

The `wormhole` module makes it possible for other applications to use these
code-protected channels. This includes blocking/synchronous support and
async/Twisted support, both for a symmetric scheme. The main module is named
`wormhole.blocking.transcribe`, to reflect that it is for
synchronous/blocking code, and uses a PAKE mode whereby one user transcribes
their code to the other. (internal names may change in the future).

The file-transfer tools use a second module named
`wormhole.blocking.transit`, which provides an encrypted record-pipe. It
knows how to use the Transit Relay as well as direct connections, and
attempts them all in parallel. `TransitSender` and `TransitReceiver` are
distinct, although once the connection is established, data can flow in
either direction. All data is encrypted (using nacl/libsodium "secretbox")
using a key derived from the PAKE phase. See
`src/wormhole/scripts/cmd_send_file.py` for examples.

## License, Compatibility

This library is released under the MIT license, see LICENSE for details.

This library is intended to be compatible with python2.6, 2.7, 3.3, and 3.4,
although proper tests have not yet been implemented.

It depends upon the SPAKE2, pynacl, requests, and argparse libraries. To run
a relay server or use the async support, you must also install Twisted.


#### footnotes

[1]: http://www.di.ens.fr/~pointche/Documents/Papers/2005_rsa.pdf "RSA 2005"