Crypto.Noise

Please see the README for usage information.

Types

data HandshakeRole

Represents the side of the conversation upon which a party resides.

Constructors

InitiatorRole

ResponderRole

Instances

Eq HandshakeRole

Methods

(==) :: HandshakeRole -> HandshakeRole -> Bool

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

data HandshakeOpts d

Represents the various options which define a handshake.

data NoiseException

Represents the various exceptions which can be thrown.

• InvalidHandshakeOptions occurs when a key that is needed is missing, or when a key is provided that shouldn't be. For example, it would be an error for the initiator to provide a remote static key if using the Noise_NX pattern, because that key is transmitted during the handshake.
• DecryptionError occurs when a non-handshake message fails to be decrypted.
• HandshakeError occurs when a handshake message fails to be processed. This can be due to an invalid transmitted ephemeral key, a transmitted static key which fails to be decrypted, or a handshake message payload which fails to be decrypted.
• MessageLimitReached occurs if the user attempts to send or receive more than 2^64 messages. This is needed because nonces are 8-bytes (64 bits), and doing so would cause catastrophic key re-use.

Constructors

InvalidHandshakeOptions String

DecryptionError String

HandshakeError String

MessageLimitReached String

Instances

Show NoiseException

Methods

showsPrec :: Int -> NoiseException -> ShowS

show :: NoiseException -> String

showList :: [NoiseException] -> ShowS

Exception NoiseException

Methods

toException :: NoiseException -> SomeException

fromException :: SomeException -> Maybe NoiseException

displayException :: NoiseException -> String

data NoiseState c d h

Represents the complete state of a Noise conversation.

Functions

defaultHandshakeOpts :: HandshakePattern -> HandshakeRole -> HandshakeOpts d

Returns a default set of handshake options. The prologue is set to an empty string, PSK-mode is disabled, and all keys are set to Nothing.

noiseState :: forall c d h. (Cipher c, DH d, Hash h) => HandshakeOpts d -> NoiseState c d h

Creates a NoiseState.

writeMessage :: (MonadThrow m, Cipher c, Hash h) => NoiseState c d h -> ScrubbedBytes -> m (ByteString, NoiseState c d h)

Creates a Noise message with the provided payload. Note that the payload may not be authenticated or encrypted at all points during the handshake. Please see section 8.4 of the protocol document for details.

To prevent catastrophic key re-use, this function may only be used to secure 2^64 - 1 post-handshake messages.

readMessage :: (MonadThrow m, Cipher c, Hash h) => NoiseState c d h -> ByteString -> m (ScrubbedBytes, NoiseState c d h)

Reads a Noise message and returns the embedded payload. If the handshake fails, a HandshakeError will be returned. After the handshake is complete, if decryption fails a DecryptionError is returned.

To prevent catastrophic key re-use, this function may only be used to receive 2^64 - 1 post-handshake messages.

remoteStaticKey :: NoiseState c d h -> Maybe (PublicKey d)

For handshake patterns where the remote party's static key is transmitted, this function can be used to retrieve it. This allows for the creation of public key-based access-control lists.

handshakeComplete :: NoiseState c d h -> Bool

Returns True if the handshake is complete.

handshakeHash :: Hash h => NoiseState c d h -> ScrubbedBytes

Retrieves the h value associated with the conversation's SymmetricState. This value is intended to be used for channel binding. For example, the initiator might cryptographically sign this value as part of some higher-level authentication scheme.

The value returned by this function is only meaningful after the handshake is complete.

See section 9.4 of the protocol for details.

Lenses

hoPattern :: forall d. Lens' (HandshakeOpts d) HandshakePattern

hoRole :: forall d. Lens' (HandshakeOpts d) HandshakeRole

hoPrologue :: forall d. Lens' (HandshakeOpts d) Plaintext

hoPreSharedKey :: forall d. Lens' (HandshakeOpts d) (Maybe Plaintext)

hoLocalStatic :: forall d. Lens' (HandshakeOpts d) (Maybe (KeyPair d))

hoLocalSemiEphemeral :: forall d. Lens' (HandshakeOpts d) (Maybe (KeyPair d))

hoLocalEphemeral :: forall d. Lens' (HandshakeOpts d) (Maybe (KeyPair d))

hoRemoteStatic :: forall d. Lens' (HandshakeOpts d) (Maybe (PublicKey d))

hoRemoteSemiEphemeral :: forall d. Lens' (HandshakeOpts d) (Maybe (PublicKey d))

hoRemoteEphemeral :: forall d. Lens' (HandshakeOpts d) (Maybe (PublicKey d))