56 lines
2.8 KiB
Markdown
56 lines
2.8 KiB
Markdown
# 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 Rendezvous 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 Rendezvous 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 Rendezvous 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 `api.md` for a complete description of
|
|
this interface.
|