git clone warner-magic-wormhole_-_2017-05-16_23-46-10.bundle -b master
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-sizedfiles and directories) from one computer to another. The two endpoints areidentified by using identical "wormhole codes": in general, the sendingmachine generates and displays the code, which must then be typed into thereceiving machine.
The codes are short and human-pronounceable, using a phonetically-distinctwordlist. The receiving side offers tab-completion on the codewords, sousually only a few characters must be typed. Wormhole codes are single-useand do not need to be memorized.
```% wormhole send README.mdSending 7924 byte file named 'README.md'On the other computer, please run: wormhole receiveWormhole code is: 7-crossover-clockwork
Sending (<-10.0.1.43:58988)..100%|=========================| 7.92K/7.92K [00:00<00:00, 6.02MB/s]File sent.. waiting for confirmationConfirmation received. Transfer complete.```
% wormhole receiveEnter receive wormhole code: 7-crossover-clockworkReceiving file (7924 bytes) into: README.mdok? (y/n): yReceiving (->tcp:10.0.1.43:58986)..100%|===========================| 7.92K/7.92K [00:00<00:00, 120KB/s]Received file written to README.md
$ pip install magic-wormhole
On Debian/Ubuntu systems, you may first need
apt-get install python-pipbuild-essential python-dev libffi-dev libssl-dev. On Fedora it's
dnfinstall python-pip python-devel libffi-devel openssl-devel gcc-c++libtool redhat-rpm-config. On OS-X, you may need to install
xcode-select --install to get GCC. On Windows, python2 may workbetter than python3. On older systems,
pip install --upgrade pip maybe necessary to get a version that can compile all the dependencies.
If you get errors like
fatal error: sodium.h: No such file or directory onLinux, either use
SODIUM_INSTALL=bundled pip install magic-wormhole, or tryinstalling the
libsodium-devel package. These work arounda bug in pynacl which gets confused when the libsodium runtime is installed(e.g.
libsodium13) but not the development package.
Developers can clone the source tree and run
tox to run the unit tests onall supported (and installed) versions of python: 2.7, 3.3, 3.4, 3.5, and3.6.
- Moving a file to a friend's machine, when the humans can speak to eachother (directly) 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 isuncomfortable for transferring long-term secrets because flash memory is hardto erase. Copying files with ssh/scp is fine, but requires previousarrangements and an account on the target machine, and how do you bootstrapthe account? Copying files through email first requires transcribing an emailaddress in the opposite direction, and is even worse for secrets, becauseemail is unencrypted. Copying files through encrypted email requiresbootstrapping a GPG key as well as an email address. Copying files throughDropbox is not secure against the Dropbox server and results in a large URLthat must be transcribed. Using a URL shortener adds an extra step, revealsthe full URL to the shortening service, and leaves a short URL that can beguessed by outsiders.
Many common use cases start with a human-mediated communication channel, suchas IRC, IM, email, a phone call, or a face-to-face conversation. Some ofthese are basically secret, or are "secret enough" to last until the code isdelivered and used. If this does not feel strong enough, users can turn onadditional verification that doesn't depend upon the secrecy of the channel.
The notion of a "magic wormhole" comes from the image of two distant wizardsspeaking the same enchanted phrase at the same time, and causing a mysticalconnection to pop into existence between them. The wizards then throw booksinto the wormhole and they fall out the other side. Transferring filessecurely should be that easy.
wormhole tool uses PAKE "Password-Authenticated Key Exchange", a familyof cryptographic algorithms that uses a short low-entropy password toestablish a strong high-entropy shared key. This key can then be used toencrypt data.
wormhole uses the SPAKE2 algorithm, due to Abdalla andPointcheval.
PAKE effectively trades off interaction against offline attacks. The only wayfor a network attacker to learn the shared key is to perform aman-in-the-middle attack during the initial connection attempt, and tocorrectly guess the code being used by both sides. Their chance of doing thisis inversely proportional to the entropy of the wormhole code. The default isto use a 16-bit code (use --code-length= to change this), so for each use ofthe tool, an attacker gets a 1-in-65536 chance of success. As such, users canexpect to see many error messages before the attacker has a reasonable chanceof success.
The program does not have any built-in timeouts, however it is expected thatboth clients will be run within an hour or so of each other. This makes thetool most useful for people who are having a real-time conversation already,and want to graduate to a secure connection. Both clients must be leftrunning until the transfer has finished.
The wormhole library requires a "Rendezvous Server": a simple WebSocket-basedrelay that delivers messages from one client to another. This allows thewormhole codes to omit IP addresses and port numbers. The URL of a publicserver is baked into the library for use as a default, and will be freelyavailable until volume or abuse makes it infeasible to support. Applicationswhich desire more reliability can easily run their own relay and configuretheir clients to use it instead. Code for the Rendezvous Server is includedin the library.
The file-transfer commands also use a "Transit Relay", which is anothersimple server that glues together two inbound TCP connections and transfersdata on each to the other. The
wormhole send file mode shares the IPaddresses of each client with the other (inside the encrypted message), andboth clients first attempt to connect directly. If this fails, they fall backto using the transit relay. As before, the host/port of a public server isbaked into the library, and should be sufficient to handle moderate traffic.
The protocol includes provisions to deliver notices and error messages toclients: if either relay must be shut down, these channels will be used toprovide information about alternatives.
wormhole send [args] --text TEXT
wormhole send [args] FILENAME
wormhole send [args] DIRNAME
wormhole receive [args]
Both commands accept additional arguments to influence their behavior:
--code-length WORDS: use more or fewer than 2 words for the code
--verify: print (and ask user to compare) extra verification string
wormhole module makes it possible for other applications to use thesecode-protected channels. This includes Twisted support, and (in the future)will include blocking/synchronous support too. See docs/api.md for details.
The file-transfer tools use a second module named
wormhole.transit, whichprovides an encrypted record-pipe. It knows how to use the Transit Relay aswell as direct connections, and attempts them all in parallel.
TransitReceiver are distinct, although once theconnection is established, data can flow in either direction. All data isencrypted (using nacl/libsodium "secretbox") using a key derived from thePAKE phase. See
src/wormhole/cli/cmd_send.py for examples.
This library is released under the MIT license, see LICENSE for details.
This library is compatible with python2.7, 3.3, 3.4, 3.5, and 3.6 . Itis probably compatible with py2.6, but the latest Twisted (>=15.5.0) isnot.
Upload date: 2015-02-10
- 2017-05-16 23:46:10
- Internet Archive Python library 1.5.0
- iagitup - v1.0