Noise-C Library

Note: This is a port of the noise-c library to build on microcontroller targets. It ships build support for PlatformIO, ESP-IDF, and plain CMake, so it can be consumed by any microcontroller (or host) project that builds with CMake, not just ESP8266/ESP32.

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.

The documentation contains more information on the library, examples, and how to build it.

Using it in a CMake project

The top-level CMakeLists.txt detects which build it is running under:

• Under ESP-IDF (ESP_PLATFORM set) it registers itself as an IDF component, requiring the esphome__libsodium component.
• Anywhere else it defines a static library target noise_c, also available as esphome::noise_c, with include/ and src/ on its public include path.

So any CMake-based project - a vendor SDK, a bare-metal cross-compile toolchain, Zephyr, or a host build for tests - can pull it in with add_subdirectory() (or FetchContent) and link the target:

add_subdirectory(third_party/noise-c)
target_link_libraries(my_app PRIVATE esphome::noise_c)

The crypto backend is a compile-time choice made through the NOISE_USE_* macros in include/noise/defines.h. The default backend is libsodium; if your project already defines a sodium target before add_subdirectory(), the generic build links against it automatically. Otherwise select the reference backend, or configure with -DNOISE_C_FIND_LIBSODIUM=ON to find a system libsodium with pkg-config.

Minimum CMake version for the generic target is 3.13; fetching the libsodium fork for the tests needs 3.14.

Configuring with -DNOISE_C_BUILD_TESTS=ON also builds the unit and vector tests; ctest runs them. They link against ESPHome's libsodium fork, fetched from GitHub at the version idf_component.yml pins with its patches applied, so the tests exercise the same sources the published packages ship. Add -DNOISE_C_FIND_LIBSODIUM=ON to test against a system libsodium instead. The unit tests cover the algorithms this fork ships. The vector runner skips a vector naming an algorithm the build leaves out and reports how many it skipped.

Size switches for microcontroller builds

Three macros in include/noise/defines.h trade features for flash and RAM. All three are on by default, so a build that says nothing gets the library it always had; define one as 0 to leave that feature out. The packaged builds turn all three off without asking, since ESPHome builds its handshake from algorithm ids and never names one: library.json for the PlatformIO library, and CMakeLists.txt for any ESP-IDF component build, from the Espressif registry or a local copy. A CMake build of the sources on a host keeps the defaults, so the tests cover the whole library.

• NOISE_USE_PROTOCOL_NAME_TABLE keeps the tables that turn algorithm names into ids and back. With it off, noise_protocol_name_to_id and noise_protocol_id_to_name handle only Noise_NNpsk0_25519_ChaChaPoly_SHA256 and answer NOISE_ERROR_UNKNOWN_ID or NOISE_ERROR_UNKNOWN_NAME for anything else. The rest of the name API stays, and a link with -ffunction-sections -fdata-sections -Wl,--gc-sections, which the ESP-IDF and Arduino builds pass, drops the tables along with whatever no longer reaches them. Turning the tables off pins the build to that one protocol, pattern included: the switches for AES, SHA512, the two BLAKE2 hashes, Curve448 and NewHope must stay off, the ones for SHA256, ChaCha20-Poly1305 and Curve25519 must stay on, and NOISE_USE_FALLBACK and NOISE_USE_HFS must be off as well: fallback needs the XX patterns named and the one pattern the build expands has no hfs. The build stops with an #error if any of them says otherwise. noise_handshakestate_new_by_id likewise accepts only NNpsk0 in that build, its expanded token list is a constant, so the base patterns and the modifier code go with the tables, and the pattern buffer in every handshake state shrinks from 64 bytes to the 8 that pattern needs.
• NOISE_USE_FALLBACK and NOISE_USE_HFS keep the "fallback" and "hfs" pattern modifiers. With them off, a pattern that asks for one is rejected with NOISE_ERROR_UNKNOWN_NAME, and noise_handshakestate_fallback and noise_handshakestate_fallback_to return NOISE_ERROR_NOT_APPLICABLE.

This fork is maintained by the ESPHome project. To report bugs, contribute, or suggest improvements to it, please open an issue or pull request on esphome-libs/noise-c.

The original library was written by Rhys Weatherley; questions about upstream Noise-C itself belong on rweather/noise-c.