Ensure that you provide the keys which are required by the handshake pattern you choose. For example,
the Noise_IK pattern requires that the initiator provides a local static key and a remote static key,
while the responder is only responsible for a local static key. You can use defaultHandshakeOpts to
return a default set of options in which all keys are set to Nothing. The initiator must set a
local ephemeral key for all handshake patterns. The responder must set a local ephemeral key for all
interactive (i.e. not one-way) patterns.

Ensure that you never re-use a NoiseState to send more than one message.

Decrypted messages are stored internally as ScrubbedBytes and will be wiped from memory when they are
destroyed.

Helper Functions

The following functions are found in Crypto.Noise.DH and are used to manipulate keys:

dhGenKey – Generate a fresh (private, public) key pair

dhPubToBytes – Convert a public key to ScrubbedBytes

dhBytesToPub – Convert ScrubbedBytes to a public key

dhSecToBytes – Convert a private key to ScrubbedBytes

dhBytesToPair – Convert ScrubbedBytes to a (private, public) key pair

The following functions are found in Crypto.Noise:

remoteStaticKey – 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 – Returns True if the handshake is complete.

processPSKs – This function repeatedly applies PSKs to a NoiseState until the list of PSKs becomes empty
or the handshake pattern stops asking for PSKs.

handshakeHash – 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. See section 11.2 of the protocol for details.

rekeySending and rekeyReceiving – Rekeys the given NoiseState according to section 11.3 of the protocol.

Vectors

Test vectors can be generated and verified using the vectors program. It accepts no arguments. When run,
it will check for the existence of vectors/cacophony.txt within the current working directory. If it is not
found, it is generated. If it is found, it is verified. All files within the vectors/ directory (regardless
of their name) are also verified. Note that this program can only generate and verify vectors whose handshake
patterns are pre-defined in this library.

Custom Handshakes

If the built-in handshake patterns are insufficient for your application, you can define your own. Note that
this should be done with care.

Tools

format-vectors.py

Vectors generated by the vector program are formatted as minified JSON. This python script takes the path
to a vector file as an argument and reformats it so that it conforms to
the style specified on the Noise Wiki.

noise-repl

This program acts as a kind of REPL for Noise messages. It supports sending and receiving messages via UDP
or via a pipe to a shell command.

All messages transmitted via a pipe are expected to be prepended by a two byte big-endian length.

Changes

0.10.0

Completely refactored API

Added rev32 support

Removed examples because they are difficult to maintain

Added noise-repl tool

0.9.2

Added ability to export raw symmetric keys

0.9.1

Enabled llvm flag support on executables

Removed deepseq library dependency

Disallowed reserved nonce (2^64 - 1)

Fixed problem with CipherState count not incrementing

0.9.0

Removed secondary key support (rev 31)

Renamed dh tokens (rev 31)

Added Noise-C vectors

Regenerated test vectors

Now using IsString instance of ScrubbedBytes from memory package

Linting

0.8.0

Exceptions are now provided by the safe-exceptions package
(breaking API change)

Added Noise_XXfallback pattern

Minor improvements to handshake pattern definition

Updated non-standard handshake patterns to conform with rev 30

Fixed bug which caused echo-server to read wrong public key

0.7.0

Major API overhaul and refactoring

Added test vector support

Added secondary symmetric key support

Added GHC 8.0.2 to unit tests

Removed Noise_XR

General code cleanup and other minor tweaks

0.6.0

Added ability to abort handshakes based on the remote party’s public key

Improved documentation

Factored out ScrubbedBytes utilities to separate module

Added echo-server and echo-client example

Renamed HandshakeStateParams to HandshakeOpts

0.5.0

Added Curve448 support

Major refactoring and API changes
A DSL was created to represent handshake patterns.