Protocol/API/Library Introduction¶
The magic-wormhole (Python) distribution provides several things: an
executable tool (“bin/wormhole”), an importable library
(import wormhole
), the URL of a publicly-available Mailbox Server,
and the definition of a protocol used by all three.
The executable tool provides basic sending and receiving of files,
directories, and short text strings. These all use wormhole send
and
wormhole receive
(which can be abbreviated as wormhole tx
and
wormhole rx
). It also has a mode to facilitate the transfer of SSH
keys. This tool, while useful on its own, is just one possible use of
the protocol.
The wormhole
library provides an API to establish a bidirectional
ordered encrypted record pipe to another instance (where each record is
an arbitrary-sized bytestring). This does not provide file-transfer
directly: the “bin/wormhole” tool speaks a simple protocol through this
record pipe to negotiate and perform the file transfer.
wormhole/cli/public_relay.py
contains the URLs of a Mailbox Server
and a Transit Relay which I provide to support the file-transfer tools,
which other developers should feel free to use for their applications as
well. I cannot make any guarantees about performance or uptime for these
servers: if you want to use Magic Wormhole in a production environment,
please consider running a server on your own infrastructure (just run
wormhole-server start
and modify the URLs in your application to
point at it).
The Magic-Wormhole Protocol¶
There are several layers to the protocol.
At the bottom level, each client opens a WebSocket to the Mailbox Server, sending JSON-based commands to the server, and receiving similarly-encoded messages. Some of these commands are addressed to the server itself, while others are instructions to queue a message to other clients, or are indications of messages coming from other clients. All these messages are described in “server-protocol.md”.
These inter-client messages are used to convey the PAKE protocol exchange, then a “VERSION” message (which doubles to verify the session key), then some number of encrypted application-level data messages. “client-protocol.md” describes these wormhole-to-wormhole messages.
Each wormhole-using application is then free to interpret the data
messages as it pleases. The file-transfer app sends an “offer” from the
wormhole send
side, to which the wormhole receive
side sends a
response, after which the Transit connection is negotiated (if
necessary), and finally the data is sent through the Transit connection.
“file-transfer-protocol.md” describes this application’s use of the
client messages.
The wormhole
API¶
Application use the wormhole
library to establish wormhole
connections and exchange data through them. Please see the API
docs for a complete description of this interface.