From 3f662ea68c61c0dfd89b903e7271267ca2b4209e Mon Sep 17 00:00:00 2001 From: Brian Warner Date: Thu, 9 Apr 2015 23:58:31 -0500 Subject: [PATCH] add proper README --- README.md | 147 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 145 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5c61c13..7ca3deb 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,146 @@ -# magic-wormhole +# Magic Wormhole -get things from one computer to another, safely +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. The current release only includes +blocking/synchronous support, but a future release will include async/Twisted +libraries too. 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). There are distinctive sides: one `Initiator`, and one +`Receiver`. + +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, you must also install Twisted. + + +#### footnotes + +[1]: http://www.di.ens.fr/~pointche/Documents/Papers/2005_rsa.pdf "RSA 2005"