Noise-C Documentation

Table of Contents

• Supported Patterns and Algorithms
• Major API's
• Supporting API's
• Other information
• Directory structure
• Building
• TODO
• Contact

Noise-C is a plain C implementation of the Noise Protocol, intended as a reference implementation. It can also be referred to as "Noisy", which is what you get when you say "Noise-C" too fast. The code is distributed under the terms of the MIT license, with the code available from github.

Note

This project is still a work in progress. There is still a lot of cleaning up and example writing to do.

The initial target is GNU/Linux systems, because that's what I have, but contributions are definitely welcome to make the code work on other platforms. Desktop systems will be targeted first and then embedded systems. "Make It Work And Then Make It Work Better" is my motto.

Supported Patterns and Algorithms

• Specification Level: Revision 30
• Prefixes: Noise and NoisePSK
• Patterns: N, X, K, NN, NK, NX, XN, XK, XX, KN, KK, KX, IN, IK, IX, XXfallback, Xnoidh, NXnoidh, XXnoidh, KXnoidh, IKnoidh, IXnoidh, NNhfs, NKhfs, NXhfs, XNhfs, XKhfs, XXhfs, KNhfs, KKhfs, KXhfs, INhfs, IKhfs, IXhfs, XXfallback+hfs, NXnoidh+hfs, XXnoidh+hfs, KXnoidh+hfs, IKnoidh+hfs, IXnoidh+hfs
• Diffie-Hellman: 25519, 448
• Post-Quantum: NewHope
• Cipher: ChaChaPoly, AESGCM
• Hash: BLAKE2s, BLAKE2b, SHA256, SHA512
• Other: Support for Hybrid Forward Secrecy

Note that the post-quantum "NewHope" algorithm only works with the "NN" handshake pattern because it does not support long-term static keys. For more information, see the Post-Quantum Noise with New Hope page on the Noise wiki.

Major API's

• HandshakeState
• CipherState

Supporting API's

• SymmetricState
• HashState
• DHState
• SignState
• RandState
• Key/certificate loading and saving
• Utilities

Other information

• Using Noise-C: Client/Server Echo Example
• Certificate and private key file format

Directory structure

• include/noise/ - Public API definitions for inclusion into applications.
• src/protocol/ - Source code for the core Noise-C protocol library.
• src/protobufs/ - Source code for the Noise-C protobufs library.
• src/keys/ - Source code for the key and certificate management library.
• src/crypto/ - Public domain and open source reference implementations of the cryptographic primitives.
• src/backend/ref/ - Backends for CipherState, HashState, DHState, and SignState that use the reference cryptographic primitives.
• src/backend/openssl/ - OpenSSL crypto backend
• src/backend/sodium/ - libsodium crypto backend
• tools/protoc/ - Source code for the Noise-C protobufs compiler.
• tools/keytool/ - Command-line key and certificate management tool.
• tests/unit/ - Unit tests to exercise the library's functionality.
• tests/vector/ - Public JSON test vectors and test harness for the Noise protocol.
• tests/vector-gen/ - Generates test vectors in JSON format.
• tests/performance/ - Performance tests for the cryptographic primitives.
• examples/ - Source code for examples.
• doc/ - Overview and example documentation.

Building

The library uses autoconf and automake for the Makefile structure. You will need to have these installed to build from the sources in the git repository. Bison and Flex are also requred to build the noise-protoc protobuf compiler.

To build the library under GNU/Linux and run the tests, type the following:

$ autoreconf -i
$ ./configure
$ make
$ make check

The following parameters can be supplied to configure to select other crypto back ends:

• –with-libsodium - Use libsodium to provide crypto primitives, falling back to the reference back end where libsodium does not have an implementation.
• –with-openssl - Use the AESGCM implementation from OpenSSL.

Both options can be combined to get the best of both worlds.

TODO

In no particular order:

• Examples and overview documentation.
• Mechanism to encrypt static keypairs with a passphrase.
• Complete the standalone key generation utility for static keypairs.
• Compile-time subsetting of the library for applications that only need a subset of the algorithms, and for platforms with limited memory.

Contributions are welcome to help implement any of these.

Contact

For more information on this library, to report bugs, to contribute, or to suggest improvements, please contact the author Rhys Weatherley via e-mail.