Expand description
In reality, there is no one “Magic Wormhole” protocol. What makes Wormhole work is a handful of different protocols and handshakes, layered on another and weaved together. This allows other applications to build upon the parts they want and then add new ones special to their needs.
At the core, there is a rendezvous server with a message box that allows clients to connect to and perform a PAKE. Protocol wise, this is split into the “client-server” part (connect to a server, allocate nameplates, send and receive messages) and a “client-client” part (do a key exchange).
Two clients that are connected to each other need to know beforehand how to communicate with each other once the connection is established.
This why they have an AppID. The protocol they use to talk to each other is bound to the AppID. Clients with different AppIDs cannot communicate.
Magic Wormhole is known for its ability to transfer files. This is implemented in the transfer module, which builds upon the wormhole
protocol and thus requires a Wormhole.
As an alternative to file transfer, there is the forwarding module, which allows to forward arbitrary TCP connections over the Wormhole/Transit tunnel.
Transferring large amounts of data should not be done over the rendezvous server. Instead, you have to set up a transit
connection. A transit is little more than an encrypted TcpConnection. If a direct connection between both clients is not possible,
a relay server will transparently connect them together. Transit is used by the file transfer for example, but any other AppID protocol
might make use of it as well.
Modules§
- forwarding
- Client-to-Client protocol to forward TCP connections
- rendezvous
- Implementation of the Client-to-Server part
- transfer
- Client-to-Client protocol to organize file transfers
- transit
- Connect two sides via TCP, no matter where they are
- uri
- Custom magic wormhole URI scheme
Structs§
- AppConfig
- Wormhole configuration corresponding to an uppler layer protocol
- AppID
- Newtype wrapper for application IDs
- Code
- A wormhole code à la 15-foo-bar
- Generic
Key Deprecated - A generic key purpose for ad-hoc subkeys or if you don’t care.
- Key
- The symmetric encryption key used to communicate with the other side.
- Mailbox
Connection - Establishing Wormhole connection
- Nameplate
- Wormhole codes look like 4-purple-sausages, consisting of a number followed by some random words. This number is called a “Nameplate”.
- Parse
Nameplate Error - An error occurred when parsing a nameplate: Nameplate is not a number.
- Password
- Wormhole codes look like 4-purple-sausages, consisting of a number followed by some random words.
This number is called a “Nameplate”, the rest is called the
Password - Wormhole
- A wormhole is an open connection to a peer via the rendezvous server.
- Wormhole
Key - The type of main key of the Wormhole
- Wormhole
Welcome Deprecated - The result of the client-server handshake
Enums§
- Mood
- The close command accepts an optional “mood” string: this allows clients to tell the server (in general terms) about their experiences with the wormhole interaction. The server records the mood in its “usage” record, so the server operator can get a sense of how many connections are succeeding and failing. The moods currently recognized by the Mailbox server are:
- Parse
Code Error - An error occurred parsing the string as a valid wormhole mailbox code
- Parse
Password Error - This is a compromise. Generally we want to be wordlist-agnostic here. But we can’t ignore that the PGP wordlist is the most common wordlist in use.
- Wormhole
Error - An error occurred in the wormhole connection
Traits§
- KeyPurpose
- Marker trait to give encryption keys a “purpose”, to not confuse them