magic-wormhole-0.2.1: Interact with Magic Wormhole

Safe HaskellNone
LanguageHaskell2010

MagicWormhole.Internal.ClientProtocol

Contents

Description

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

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

Synopsis

Documentation

data Connection Source #

A connection to a peer via the Rendezvous server.

Normally construct this with open.

Constructors

Connection 

Fields

newtype SessionKey Source #

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

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.

sendEncrypted Source #

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

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.

Exported for testing

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

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

encrypt :: Key -> PlainText -> IO CipherText Source #

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

deriveKey Source #

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

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

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