MagicWormhole

Magic Wormhole is a technology for getting things from one computer to another, safely.

To use it, you must

1. Start a Session with the Rendezvous server, to allow peers to find each other (runClient)
2. Negotiate a shared Nameplate so peers can find each other on the server (allocate, list)
3. Use the shared Nameplate to open a shared Mailbox
4. Use a secret password shared between peers to establish an encrypted connection (withEncryptedConnection)

Once you've done this, you can communicate with your peer via sendMessage and receiveMessage.

The password is never sent over the wire. Rather, it is used to negotiate a session key using SPAKE2, and that key itself is used to derive many per-message keys, so that each message is encrypted using NaCl SecretBox.

This library is a client library for the Rendezvous server and a library for communicating with Magic Wormhole peers.

Client/server

Before you can communicate with a Magic Wormhole peer, you must first find them. The way to do this is to establish a Session with a Magic Wormhole Rendezvous server.

Establishing a session

data Session

Abstract type representing a Magic Wormhole session.

Use runClient to get a Session on the Magic Wormhole Rendezvous server. Once you have a Session, use ping, list, allocate, claim, release, open, and close to communicate with the Rendezvous server.

runClient

Arguments

:: HasCallStack

=> WebSocketEndpoint

The websocket to connect to

-> AppID

ID for your application (e.g. example.com/your-application)

-> Side

Identifier for your side

-> (Session -> IO a)

Action to perform inside the Magic Wormhole session

-> IO a

The result of the action

Run a Magic Wormhole Rendezvous client. Use this to interact with a Magic Wormhole server.

Will throw a ServerError if the server declares we are unwelcome.

newtype AppID

Short string to identify the application. Clients must use the same application ID if they wish to communicate with each other.

Recommendation is to use "$DNSNAME/$APPNAME", e.g. the Python wormhole command-line tool uses lothar.com/wormhole/text-or-file-xfer.

Constructors

AppID Text

Instances

Eq AppID

Methods

(==) :: AppID -> AppID -> Bool

(/=) :: AppID -> AppID -> Bool

Show AppID

Methods

showsPrec :: Int -> AppID -> ShowS

show :: AppID -> String

showList :: [AppID] -> ShowS

ToJSON AppID

Methods

toJSON :: AppID -> Value

toEncoding :: AppID -> Encoding

toJSONList :: [AppID] -> Value

toEncodingList :: [AppID] -> Encoding

FromJSON AppID

Methods

parseJSON :: Value -> Parser AppID

parseJSONList :: Value -> Parser [AppID]

newtype Side

Short string used to differentiate between echoes of our own messages and real messages from other clients.

TODO: This needs to be cleanly encoded to ASCII, so update the type or provide a smart constructor.

Constructors

Side Text

Instances

Eq Side

Methods

(==) :: Side -> Side -> Bool

(/=) :: Side -> Side -> Bool

Show Side

Methods

showsPrec :: Int -> Side -> ShowS

show :: Side -> String

showList :: [Side] -> ShowS

ToJSON Side

Methods

toJSON :: Side -> Value

toEncoding :: Side -> Encoding

toJSONList :: [Side] -> Value

toEncodingList :: [Side] -> Encoding

FromJSON Side

Methods

parseJSON :: Value -> Parser Side

parseJSONList :: Value -> Parser [Side]

generateSide :: MonadRandom randomly => randomly Side

Generate a random Side

Locating the server

Rendezvous servers are implemented as web sockets.

data WebSocketEndpoint

Endpoint for a websocket connection.

Construct directly or with parseWebSocketEndpoint.

Constructors

WebSocketEndpoint Hostname Port Path

Instances

Eq WebSocketEndpoint

Methods

(==) :: WebSocketEndpoint -> WebSocketEndpoint -> Bool

(/=) :: WebSocketEndpoint -> WebSocketEndpoint -> Bool

Show WebSocketEndpoint

Methods

showsPrec :: Int -> WebSocketEndpoint -> ShowS

show :: WebSocketEndpoint -> String

showList :: [WebSocketEndpoint] -> ShowS

parseWebSocketEndpoint :: String -> Maybe WebSocketEndpoint

Parse a WebSocketEndpoint.

Operations on the server

allocate :: HasCallStack => Session -> IO Nameplate

Allocate a nameplate on the server.

Throws a ClientError if the server rejects the message for any reason.

newtype Nameplate

Identifier for a "nameplate".

A nameplate is a very short string that identifies one peer to another. Its purpose is to allow peers to find each other without having to communicate the Mailbox identifier, which is generally too lengthy and cumbersome to be easily shared between humans.

Typically, one peer will allocate a nameplate and then communicate it out-of-band to the other peer.

Constructors

Nameplate Text

Instances

Eq Nameplate

Methods

(==) :: Nameplate -> Nameplate -> Bool

(/=) :: Nameplate -> Nameplate -> Bool

Show Nameplate

Methods

showsPrec :: Int -> Nameplate -> ShowS

show :: Nameplate -> String

showList :: [Nameplate] -> ShowS

ToJSON Nameplate

Methods

toJSON :: Nameplate -> Value

toEncoding :: Nameplate -> Encoding

toJSONList :: [Nameplate] -> Value

toEncodingList :: [Nameplate] -> Encoding

FromJSON Nameplate

Methods

parseJSON :: Value -> Parser Nameplate

parseJSONList :: Value -> Parser [Nameplate]

list :: HasCallStack => Session -> IO [Nameplate]

List the nameplates on the server.

Throws a ClientError if the server rejects the message for any reason.

claim :: HasCallStack => Session -> Nameplate -> IO Mailbox

Claim a nameplate on the server.

Throws a ClientError if the server rejects the message for any reason.

newtype Mailbox

Identifier for a mailbox.

A mailbox is a shared access point between Magic Wormhole peers within the same application (specified by AppID). To get a mailbox, you must first acquire a Nameplate and then claim that nameplate for your side with claim.

A mailbox ID is defined in the spec as a "large random string", but in practice is a 13 character, lower-case, alpha-numeric string.

Constructors

Mailbox Text

Instances

Eq Mailbox

Methods

(==) :: Mailbox -> Mailbox -> Bool

(/=) :: Mailbox -> Mailbox -> Bool

Show Mailbox

Methods

showsPrec :: Int -> Mailbox -> ShowS

show :: Mailbox -> String

showList :: [Mailbox] -> ShowS

ToJSON Mailbox

Methods

toJSON :: Mailbox -> Value

toEncoding :: Mailbox -> Encoding

toJSONList :: [Mailbox] -> Value

toEncodingList :: [Mailbox] -> Encoding

FromJSON Mailbox

Methods

parseJSON :: Value -> Parser Mailbox

parseJSONList :: Value -> Parser [Mailbox]

open :: HasCallStack => Session -> Mailbox -> IO Connection

Open a mailbox on the server.

If there's already a mailbox open, the server will send an error message. In the current implementation, that error will arise in a strange and unexpected place.

See https://github.com/warner/magic-wormhole/issues/261#issuecomment-343192449

close :: HasCallStack => Session -> Maybe Mailbox -> Maybe Mood -> IO ()

Close a mailbox on the server.

Throws a ClientError if the server rejects the message for any reason.

Errors

data ServerError

Error due to weirdness from the server.

Constructors

ResponseWithoutRequest ServerMessage

Server sent us a response for something that we hadn't requested.

UnexpectedMessage ServerMessage

We were sent a message other than Welcome on connect, or a Welcome message at any other time.

ErrorForNonRequest Text ClientMessage

We received an error message for a message that's not expected to have a response.

Unwelcome Text

Clients are not welcome on the server right now.

ParseError String

We couldn't understand the message from the server.

Instances

Eq ServerError

Methods

(==) :: ServerError -> ServerError -> Bool

(/=) :: ServerError -> ServerError -> Bool

Show ServerError

Methods

showsPrec :: Int -> ServerError -> ShowS

show :: ServerError -> String

showList :: [ServerError] -> ShowS

Exception ServerError

Methods

toException :: ServerError -> SomeException

fromException :: SomeException -> Maybe ServerError

displayException :: ServerError -> String

data ClientError

Error caused by misusing the client.

Constructors

AlreadySent ClientMessage

We tried to do an RPC while another RPC with the same response type was in flight. See warner/magic-wormhole#260 for details.

NotAnRPC ClientMessage

Tried to send a non-RPC as if it were an RPC (i.e. expecting a response).

BadRequest Text ClientMessage

We sent a message that the server could not understand.

Instances

Eq ClientError

Methods

(==) :: ClientError -> ClientError -> Bool

(/=) :: ClientError -> ClientError -> Bool

Show ClientError

Methods

showsPrec :: Int -> ClientError -> ShowS

show :: ClientError -> String

showList :: [ClientError] -> ShowS

Exception ClientError

Methods

toException :: ClientError -> SomeException

fromException :: SomeException -> Maybe ClientError

displayException :: ClientError -> String

Peer-to-peer

Opening a Mailbox shared with a peer gets you a Connection, but this is not enough to securely communicate with a peer. The next step is to establish an EncryptedConnection (via -- withEncryptedConnection), and then communicate with sendMessage and receiveMessage.

Establishing a secure connection

withEncryptedConnection

Arguments

:: Connection

Underlying to a peer. Get this with open.

-> Password

The shared password that is the basis of the encryption. Construct with makePassword.

-> (EncryptedConnection -> IO a)

Action to perform with the encrypted connection.

-> IO a

The result of the action

Run an action that communicates with a Magic Wormhole peer through an encrypted connection.

Does the "pake" and "version" exchanges necessary to negotiate an encrypted connection and then runs the user-provided action. This action can then use sendMessage and receiveMessage to send & receive messages from its peer.

Can throw:

• PeerError, when we receive nonsensical data from the other peer
• PakeError, when SPAKE2 cryptography fails
• VersionsError, when we cannot agree on shared capabilities (this can sometimes imply SPAKE2 cryptography failure)

data Connection

A connection to a peer via the Rendezvous server.

Normally construct this with open.

data EncryptedConnection

A Magic Wormhole peer-to-peer application session.

Construct one of these using withEncryptedConnection.

You get one of these after you have found a peer, successfully negotatiated a shared key, and verified that negotiation by exchanging versions. (Note that this does not include the "verifying" step mentioned in magic-wormhole's documentation, which is about a human being verifying the correctness of the code).

All messages in this session, sent & received, are encrypted using keys derived from this shared key.

deriveKey :: EncryptedConnection -> Purpose -> Key

Derive a new key for the given purpose

Construct a new key from the encrypted connection's session key for the given purpose

Errors

data PeerError

Something that went wrong with the client protocol.

Instances

Eq PeerError

Methods

(==) :: PeerError -> PeerError -> Bool

(/=) :: PeerError -> PeerError -> Bool

Show PeerError

Methods

showsPrec :: Int -> PeerError -> ShowS

show :: PeerError -> String

showList :: [PeerError] -> ShowS

Exception PeerError

Methods

toException :: PeerError -> SomeException

fromException :: SomeException -> Maybe PeerError

displayException :: PeerError -> String

data VersionsError

An error occurred during versionExchange.

Instances

Eq VersionsError

Methods

(==) :: VersionsError -> VersionsError -> Bool

(/=) :: VersionsError -> VersionsError -> Bool

Show VersionsError

Methods

showsPrec :: Int -> VersionsError -> ShowS

show :: VersionsError -> String

showList :: [VersionsError] -> ShowS

Exception VersionsError

Methods

toException :: VersionsError -> SomeException

fromException :: SomeException -> Maybe VersionsError

displayException :: VersionsError -> String

data PakeError

An error that occured during pakeExchange.

Instances

Eq PakeError

Methods

(==) :: PakeError -> PakeError -> Bool

(/=) :: PakeError -> PakeError -> Bool

Show PakeError

Methods

showsPrec :: Int -> PakeError -> ShowS

show :: PakeError -> String

showList :: [PakeError] -> ShowS

Exception PakeError

Methods

toException :: PakeError -> SomeException

fromException :: SomeException -> Maybe PakeError

displayException :: PakeError -> String

Communicating with a peer

sendMessage :: EncryptedConnection -> PlainText -> IO ()

Send an encrypted message to the peer.

Obtain an EncryptedConnection with withEncryptedConnection.

The message will be encrypted using a one-off key deriving from the shared key.

receiveMessage :: EncryptedConnection -> STM PlainText

Receive a decrypted message from the peer.

Obtain an EncryptedConnection with withEncryptedConnection.

newtype PlainText

Unencrypted text.

Constructors

PlainText

Fields

• plainTextToByteString :: ByteString

Instances

Eq PlainText

Methods

(==) :: PlainText -> PlainText -> Bool

(/=) :: PlainText -> PlainText -> Bool

Ord PlainText

Methods

compare :: PlainText -> PlainText -> Ordering

(<) :: PlainText -> PlainText -> Bool

(<=) :: PlainText -> PlainText -> Bool

(>) :: PlainText -> PlainText -> Bool

(>=) :: PlainText -> PlainText -> Bool

max :: PlainText -> PlainText -> PlainText

min :: PlainText -> PlainText -> PlainText

Show PlainText

Methods

showsPrec :: Int -> PlainText -> ShowS

show :: PlainText -> String

showList :: [PlainText] -> ShowS

Magic Wormhole applications

Once you've established an EncryptedConnection to your peer, the world is your oyster. You can send whatever data you'd like.

However, Magic Wormhole comes with at least one built-in "application": message and file transfer. This Haskell implementation only supports sending and receiving a simple message.

data Offer

An offer made by a sender as part of the Magic Wormhole file transfer protocol.

Currently only supports sending simple text messages. A full version would also support sending files and directories.

Constructors

Message Text

A simple text message.

File FilePath FileOffset

Offer a File with filename and size.

Directory

Offer a Directory

Fields

• directoryMode :: DirectoryMode

  Mode. Currently always "zipfile/deflated".

• dirName :: Text

  Directory Name.

• zipSize :: Natural

  size of the transmitted compressed data in bytes

• numBytes :: Natural

  estimated total size of the uncompressed directory

• numFiles :: Natural

  number of files and directories being sent

Instances

Eq Offer

Methods

(==) :: Offer -> Offer -> Bool

(/=) :: Offer -> Offer -> Bool

Show Offer

Methods

showsPrec :: Int -> Offer -> ShowS

show :: Offer -> String

showList :: [Offer] -> ShowS

ToJSON Offer

Methods

toJSON :: Offer -> Value

toEncoding :: Offer -> Encoding

toJSONList :: [Offer] -> Value

toEncodingList :: [Offer] -> Encoding

FromJSON Offer

Methods

parseJSON :: Value -> Parser Offer

parseJSONList :: Value -> Parser [Offer]

data DirectoryMode

Constructors

ZipFileDeflated

Instances

Eq DirectoryMode

Methods

(==) :: DirectoryMode -> DirectoryMode -> Bool

(/=) :: DirectoryMode -> DirectoryMode -> Bool

Show DirectoryMode

Methods

showsPrec :: Int -> DirectoryMode -> ShowS

show :: DirectoryMode -> String

showList :: [DirectoryMode] -> ShowS

ToJSON DirectoryMode

Methods

toJSON :: DirectoryMode -> Value

toEncoding :: DirectoryMode -> Encoding

toJSONList :: [DirectoryMode] -> Value

toEncodingList :: [DirectoryMode] -> Encoding

FromJSON DirectoryMode

Methods

parseJSON :: Value -> Parser DirectoryMode

parseJSONList :: Value -> Parser [DirectoryMode]