magic-wormhole-0.3.0: 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.

Instances
Eq PeerError Source # 
Instance details

Defined in MagicWormhole.Internal.ClientProtocol

Methods

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

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

Show PeerError Source # 
Instance details

Defined in MagicWormhole.Internal.ClientProtocol

Methods

showsPrec :: Int -> PeerError -> ShowS

show :: PeerError -> String

showList :: [PeerError] -> ShowS

Exception PeerError Source # 
Instance details

Defined in MagicWormhole.Internal.ClientProtocol

Methods

toException :: PeerError -> SomeException

fromException :: SomeException -> Maybe PeerError

displayException :: PeerError -> String

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.

newtype PlainText Source #

Unencrypted text.

Constructors

PlainText 

Fields

Instances
Eq PlainText Source # 
Instance details

Defined in MagicWormhole.Internal.ClientProtocol

Methods

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

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

Ord PlainText Source # 
Instance details

Defined in MagicWormhole.Internal.ClientProtocol

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

Defined in MagicWormhole.Internal.ClientProtocol

Methods

showsPrec :: Int -> PlainText -> ShowS

show :: PlainText -> String

showList :: [PlainText] -> ShowS

Exported for testing

newtype CipherText Source #

Encrypted text.

Constructors

CipherText 

Fields

Instances
Eq CipherText Source # 
Instance details

Defined in MagicWormhole.Internal.ClientProtocol

Methods

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

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

Ord CipherText Source # 
Instance details

Defined in MagicWormhole.Internal.ClientProtocol

Show CipherText Source # 
Instance details

Defined in MagicWormhole.Internal.ClientProtocol

Methods

showsPrec :: Int -> CipherText -> ShowS

show :: CipherText -> String

showList :: [CipherText] -> ShowS

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.