Safe Haskell	None
Language	Haskell2010

MagicWormhole.Internal.ClientProtocol

Contents

Exported for testing

Description

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

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

Synopsis

data Connection = Connection {
- appID :: AppID
- ourSide :: Side
- send :: Phase -> Body -> IO ()
- receive :: STM MailboxMessage
}
newtype SessionKey = SessionKey ByteString
data PeerError
sendEncrypted :: Connection -> SessionKey -> Phase -> PlainText -> IO ()
receiveEncrypted :: Connection -> SessionKey -> STM (Phase, PlainText)
newtype PlainText = PlainText {
- plainTextToByteString :: ByteString
}
newtype CipherText = CipherText {
- cipherTextToByteString :: ByteString
}
decrypt :: Key -> CipherText -> Either PeerError PlainText
encrypt :: Key -> PlainText -> IO CipherText
deriveKey :: SessionKey -> Purpose -> Key
type Purpose = ByteString
phasePurpose :: Side -> Phase -> Purpose

Documentation

data Connection Source #

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 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 plainTextToByteString :: ByteString

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 cipherTextToByteString :: ByteString

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 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 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.