MagicWormhole.Internal.ClientProtocol

Low-level details for talking to a Magic Wormhole peer.

For a user-facing interface, see MagicWormhole.Internal.Peer.

Documentation

data Connection

A connection to a peer via the Rendezvous server.

Normally construct this with open.

Constructors

Connection

Fields

• appID :: AppID

  The application ID for this connection.

• ourSide :: Side

  The identifier for this side of the connection.

• send :: Phase -> Body -> IO ()

  Send a message to the other side.

• receive :: STM MailboxMessage

  Receive a message from the other side.

newtype SessionKey

SPAKE2 key used for the duration of a Magic Wormhole peer-to-peer connection.

You can obtain a SessionKey using pakeExchange.

Individual messages will be encrypted using encrypt (decrypt), which must be given a key that's generated from this one (see deriveKey).

Constructors

SessionKey ByteString

data PeerError

Something that went wrong with the client protocol.

Constructors

CouldNotDecrypt ByteString

We received a message from the other side that we could not decrypt

InvalidNonce ByteString

We could not determine the SecretBox nonce from the message we received

MessageOutOfOrder Phase PlainText

We received a message for a phase that we have already received a message for.

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

sendEncrypted

Arguments

:: Connection

Connection to the peer

-> SessionKey

The key established for this session

-> Phase

Phase of the protocol this message represents

-> PlainText

Content of the message

-> IO ()

Send an encrypted message to the peer.

receiveEncrypted

Arguments

:: Connection

Connection to the peer

-> SessionKey

The key established for this session

-> STM (Phase, PlainText)

The phase and content of the message we received

Pull a message from the peer and decrypt it. If the message fails to decrypt, an exception will be thrown, aborting the transaction and leaving the message on the queue.

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

Exported for testing

newtype CipherText

Encrypted text.

Constructors

CipherText

Fields

• cipherTextToByteString :: ByteString

Instances

Eq CipherText

Methods

(==) :: CipherText -> CipherText -> Bool

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

Ord CipherText

Methods

compare :: CipherText -> CipherText -> Ordering

(<) :: CipherText -> CipherText -> Bool

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

(>) :: CipherText -> CipherText -> Bool

(>=) :: CipherText -> CipherText -> Bool

max :: CipherText -> CipherText -> CipherText

min :: CipherText -> CipherText -> CipherText

Show CipherText

Methods

showsPrec :: Int -> CipherText -> ShowS

show :: CipherText -> String

showList :: [CipherText] -> ShowS

decrypt :: Key -> CipherText -> Either PeerError PlainText

Decrypt a message using SecretBox. Get the key from deriveKey. Encrypted using encrypt.

encrypt :: Key -> PlainText -> IO CipherText

Encrypt a message using SecretBox. Get the key from deriveKey. Decrypt with decrypt.

deriveKey

Arguments

:: SessionKey

Key established for this session

-> Purpose

What this key is for. Normally created using phasePurpose.

-> Key

A key to use once to send or receive a message

Derive a one-off key from the SPAKE2 SessionKey. Use this key only once.

type Purpose = ByteString

The purpose of a message. deriveKey combines this with the SessionKey to make a unique Key. Do not re-use a Purpose to send more than message.

phasePurpose :: Side -> Phase -> Purpose

Obtain a Purpose for deriving a key to send a message that's part of a peer-to-peer communication.