MagicWormhole.Internal.Peer

Interface for communicating with a Magic Wormhole peer.

Build on this to write an application that uses Magic Wormhole.

Documentation

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.

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)

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.

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