Crypto.Noise.Handshake

For more information regarding HandshakePatterns, please see the Crypto.Noise.HandshakePatterns module.

Types

data SendingCipherState c

Represents the Noise cipher state for outgoing data.

data ReceivingCipherState c

Represents the Noise cipher state for incoming data.

data HandshakeCallbacks d

Contains the callbacks required by runHandshake.

hscbSend and hscbRecv are called when handshake data needs to be sent to and received from the remote peer, respectively. hscbSend will typically be a function which writes to a socket, and hscbRecv will typically be a function which reads from a socket.

hscbPayloadIn and hscbPayloadOut are called when handshake payloads are received and sent, respectively. To be more precise, hscbPayloadIn is called after an incoming handshake message has been decrypted successfully, and hscbPayloadOut is called during the construction of an outgoing handshake message.

hscbStaticIn is called as soon as a static key is received from the remote party. If this function evaluates to False, the handshake is immediately aborted and a HandshakeAborted exception is thrown. Otherwise, the handshake proceeds normally. This is intended to create a firewall/access control list which can be used to prohibit communication with certain parties. In the noiseXR and noiseIX patterns, this will prevent the initiator from discovering your identity. In the noiseXX pattern, this will prevent the responder from discovering your identity.

All five of these callbacks apply to handshake messages only. After the handshake is complete they are no longer used.

Constructors

HandshakeCallbacks

Fields

hscbSend :: ByteString -> IO ()

hscbRecv :: IO ByteString

hscbPayloadIn :: Plaintext -> IO ()

hscbPayloadOut :: IO Plaintext

hscbStaticIn :: PublicKey d -> IO Bool

data HandshakeState c d h

Represents the state of a handshake.

data HandshakeOpts c d

Contains the parameters required to initialize a HandshakeState. The keys you need to provide are dependent on the type of handshake you are using. If you fail to provide a key that your handshake type depends on, or you provide a static key which is supposed to be set during the exchange, you will receive a HandshakeStateFailure exception.

Constructors

HandshakeOpts

Fields

hspPattern :: HandshakePattern c

hspPrologue :: Plaintext

hspPreSharedKey :: Maybe Plaintext

hspLocalStaticKey :: Maybe (KeyPair d)

hspLocalEphemeralKey :: Maybe (KeyPair d)

hspRemoteStaticKey :: Maybe (PublicKey d)

hspRemoteEphemeralKey :: Maybe (PublicKey d)

hspInitiator :: Bool

Functions

handshakeState :: forall c d h. (Cipher c, Curve d, Hash h) => HandshakeOpts c d -> HandshakeState c d h

Constructs a HandshakeState.

runHandshake :: (Cipher c, Curve d, Hash h) => HandshakeState c d h -> HandshakeCallbacks d -> IO (SendingCipherState c, ReceivingCipherState c)

Given a HandshakeState and HandshakeCallbacks, runs a handshake from start to finish. The SendingCipherState and ReceivingCipherState are intended to be used by encryptPayload and decryptPayload, respectively.

encryptPayload

Arguments

:: Cipher c

=> Plaintext

The data to encrypt

-> SendingCipherState c

-> (ByteString, SendingCipherState c)

Encrypts a payload. The returned SendingCipherState must be used for all subsequent calls.

decryptPayload

Arguments

:: Cipher c

=> ByteString

The data to decrypt

-> ReceivingCipherState c

-> (Plaintext, ReceivingCipherState c)

Decrypts a payload. The returned ReceivingCipherState must be used for all subsequent calls.