magic-wormhole/docs/introduction.md

# 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.