Noise Cryptographic Transport (cais.noise)¶
The noise subsystem provides a lightweight, zero-allocation, certificate-less secure channel engine based on the Noise Protocol Framework. It is designed to encrypt, authenticate, and frame bidirectional data streams across modern POSIX systems, Windows, and vintage embedded platforms.
Operating over Curve25519 (X25519), ChaCha20-Poly1305, and a native 32-bit implementation of BLAKE2s, cais.noise establishes cryptographically hardened links over raw TCP sockets (cais.socket), physical RS-232 serial UART ports (cais.serial), or any generic byte stream.
⚡ 1. Architectural Principles & Guarantees¶
1.1 Why Noise Instead of TLS?¶
Standard TLS stacks (such as OpenSSL, mbedTLS, or BearSSL) impose heavy architectural costs: * X.509 Certificate Bloat: Parsing ASN.1, verifying certificate revocation lists (CRLs/OCSP), and maintaining hundreds of trusted Root Certificate Authorities requires hundreds of kilobytes of code and megabytes of memory. * Complex State Machines & Handshake Latency: TLS negotiation involves ciphersuite selection, protocol version negotiation, and multiple round-trips. * Heavy Memory Allocations: Dynamic allocation during certificate validation and record handling is problematic on memory-constrained systems (e.g., DOS, WinCE, embedded microcontrollers).
cais.noise solves these issues permanently:
* Certificate-less Public Key Authentication: Peers identify each other directly by raw 32-byte Ed25519/X25519 public keys.
* Fixed Cryptographic Primitives: Negotiation is eliminated; both peers agree deterministically on the cipher suite.
* Zero Dynamic Heap Allocations: Handshake processing and transport encryption operate entirely on fixed stack buffers with zero runtime malloc() calls.
* Compact Footprint: The entire subsystem compiles into a few dozen kilobytes of static binary code.
1.2 Native 32-Bit Arithmetic Suite¶
Rather than using 64-bit BLAKE2b or SHA-512 (which require expensive 64-bit emulation on vintage 32-bit x86, ARMv4/v5, and Motorola 68000 processors), cais.noise exclusively standardizes on BLAKE2s (RFC 7693):
$$\text{Noise_[Pattern]_25519_ChaChaPoly_BLAKE2s}$$
- Key Exchange (DH): Curve25519 (X25519) via Monocypher.
- Authenticated Symmetric Cipher (AEAD): ChaCha20-Poly1305 with 96-bit Noise-formatted nonces (
uint64counter padded to 12 bytes). - Hash & Key Derivation (KDF): BLAKE2s operating on 32-bit words, HMAC-BLAKE2s (RFC 2104), and HKDF2 / HKDF3.
1.3 Transport-Agnostic Framing¶
Noise produces discrete authenticated cryptographic frames (up to 65,535 bytes). However, TCP sockets and serial UART ports operate as continuous byte streams without packet boundaries.
cais.noise includes a transport framing protocol:
┌─────────────────────────┬──────────────────────────────────────┐
│ Length Prefix (2 bytes)│ Noise Ciphertext Frame + Tag (MAC) │
│ Big-Endian (0..65535) │ Length = Plaintext + 16-byte MAC │
└─────────────────────────┴──────────────────────────────────────┘
🔄 2. Handshake Patterns¶
cais.noise supports four handshake patterns covering all networking topologies:
2.1 Noise_XX (Mutual Authentication & Identity Hiding)¶
The standard recommendation for general-purpose peer-to-peer and client-server communication. Neither party requires prior knowledge of the other's public key; both keys are transmitted encrypted and mutually verified.
* Round-Trips: 1.5 RTT (3 messages). * Security: Mutual static public key authentication, forward secrecy, and identity hiding against passive eavesdroppers.2.2 Noise_NK (Anonymous Client to Known Server)¶
Ideal for public web servers and telemetry collectors where the client knows the server's static public key, but the client remains anonymous.
* Round-Trips: 1 RTT (2 messages). * Security: Server authenticated; client identity unauthenticated (anonymous).2.3 Noise_IK (1-RTT Mutual Auth / WireGuard Pattern)¶
Optimized for known pairs of peers (like WireGuard VPN tunnels or recurring device communication). The client knows the server's public key, transmits its own encrypted static identity on the very first packet, and completes mutual authentication in a single round-trip.
* Round-Trips: 1 RTT (2 messages). * Security: Mutual authentication, fast session establishment with zero negotiation delay.2.4 Noise_NN (Opportunistic Encryption)¶
Ephemeral-only handshake with no static keys.
* Round-Trips: 1 RTT (2 messages). * Security: Defends against passive network sniffing; no defense against active Man-in-the-Middle (MITM) attacks.⚙️ 3. Constants & Enumerations¶
All constants are declared in include/cais/noise.h.
3.1 Handshake Pattern (cais_noise_pattern_t)¶
| C Identifier | Lua Field (cais.noise.pattern) |
Value | Description |
|---|---|---|---|
CAIS_NOISE_XX |
XX |
0 |
Mutual authentication, identity hiding (3 msgs) |
CAIS_NOISE_NN |
NN |
1 |
Ephemeral only, opportunistic (2 msgs) |
CAIS_NOISE_NK |
NK |
2 |
Anonymous initiator, known responder (2 msgs) |
CAIS_NOISE_IK |
IK |
3 |
1-RTT mutual authentication (WireGuard pattern) |
3.2 Handshake Role (cais_noise_role_t)¶
| C Identifier | Lua Field (cais.noise.role) |
Value | Description |
|---|---|---|---|
CAIS_NOISE_INITIATOR |
INITIATOR |
0 |
Outbound client initiating the handshake |
CAIS_NOISE_RESPONDER |
RESPONDER |
1 |
Inbound server waiting for handshake initiation |
3.3 State Machine Actions (cais_noise_action_t)¶
| C Identifier | Lua String Equivalent | Value | Description |
|---|---|---|---|
CAIS_NOISE_ACTION_FAILED |
"failed" |
-1 |
Handshake failed (MAC mismatch or protocol violation) |
CAIS_NOISE_ACTION_WRITE_MSG |
"write_msg" |
1 |
Local session must produce and send next message |
CAIS_NOISE_ACTION_READ_MSG |
"read_msg" |
2 |
Local session must read incoming handshake message |
CAIS_NOISE_ACTION_SPLIT |
"split" |
3 |
Handshake complete; split into transport ciphers |
3.4 Buffer Size Constants¶
| Constant Name | Value | Description |
|---|---|---|
CAIS_NOISE_KEY_LEN |
32 |
Curve25519 private or public key length in bytes |
CAIS_NOISE_TAG_LEN |
16 |
Poly1305 MAC authentication tag length in bytes |
CAIS_NOISE_MAX_FRAME_LEN |
65535 |
Maximum supported transport payload length per frame |
🏛️ 4. ANSI C89 Function Reference¶
4.1 Key Generation & CSPRNG¶
/* Generates a 32-byte X25519 private and public keypair using platform CSPRNG */
cais_status_t cais_noise_keygen(
unsigned char *out_priv,
unsigned char *out_pub,
char *err_buf,
size_t err_cap
);
/* Seeds the fallback PRNG for platforms lacking native CSPRNG hardware */
void cais_noise_seed(const void *entropy, size_t len);
4.2 Lifecycle & Configuration¶
/* Allocates a new Noise session state machine */
cais_noise_t *cais_noise_create(
cais_noise_pattern_t pattern,
cais_noise_role_t role,
char *err_buf,
size_t err_cap
);
/* Configures local static 32-byte private key (computes public key automatically) */
cais_status_t cais_noise_set_static_key(
cais_noise_t *noise,
const unsigned char *priv_key,
char *err_buf,
size_t err_cap
);
/* Configures pre-known remote static 32-byte public key (for NK or IK) */
cais_status_t cais_noise_set_remote_key(
cais_noise_t *noise,
const unsigned char *remote_pub,
char *err_buf,
size_t err_cap
);
/* Configures deterministic 32-byte ephemeral private key (used for test vector validation) */
cais_status_t cais_noise_set_ephemeral_key(
cais_noise_t *noise,
const unsigned char priv[CAIS_NOISE_KEY_LEN],
char *err_buf,
size_t err_cap
);
/* Configures optional contextual prologue bytes mixed into handshake hash */
cais_status_t cais_noise_set_prologue(
cais_noise_t *noise,
const void *prologue,
size_t prologue_len,
char *err_buf,
size_t err_cap
);
/* Initializes SymmetricState and enters first handshake state.
* Conforming to Noise Specification Rev 34 (Section 5.3), MixHash(prologue)
* is unconditionally executed during initialization, even when the prologue
* is empty (0 bytes), ensuring full cross-implementation interoperability.
*/
cais_status_t cais_noise_start(
cais_noise_t *noise,
char *err_buf,
size_t err_cap
);
/* Securely zeros all sensitive keying material and releases session */
void cais_noise_free(cais_noise_t *noise);
4.3 Introspection¶
/* Returns current action required by state machine */
cais_noise_action_t cais_noise_get_action(const cais_noise_t *noise);
/* Returns CAIS_TRUE if session has completed handshake and is in transport mode */
cais_bool_t cais_noise_is_complete(const cais_noise_t *noise);
/* Returns pointer to authenticated 32-byte remote public key, or NULL if unavailable */
const unsigned char *cais_noise_get_remote_static(const cais_noise_t *noise);
/* Retrieves the current 32-byte handshake hash (h) for verification or channel binding */
cais_status_t cais_noise_get_handshake_hash(
const cais_noise_t *noise,
unsigned char out_hash[CAIS_NOISE_HASH_LEN],
char *err_buf,
size_t err_cap
);
4.4 Handshake Message Processing (Transport-Agnostic)¶
/* Writes next handshake message, optionally including cleartext/encrypted payload */
cais_status_t cais_noise_write_message(
cais_noise_t *noise,
const void *payload,
size_t payload_len,
void *out_msg,
size_t out_cap,
size_t *out_len,
char *err_buf,
size_t err_cap
);
/* Reads and verifies an incoming handshake message, returning decrypted payload */
cais_status_t cais_noise_read_message(
cais_noise_t *noise,
const void *in_msg,
size_t in_len,
void *out_payload,
size_t out_cap,
size_t *out_payload_len,
char *err_buf,
size_t err_cap
);
4.5 Transport Encryption & Decryption¶
/* Encrypts transport payload with outbound CipherState. Output size: plain_len + 16 */
cais_status_t cais_noise_encrypt(
cais_noise_t *noise,
const void *plain,
size_t plain_len,
void *out_cipher,
size_t out_cap,
size_t *out_len,
char *err_buf,
size_t err_cap
);
/* Decrypts and authenticates ciphertext with inbound CipherState. Output size: cipher_len - 16 */
cais_status_t cais_noise_decrypt(
cais_noise_t *noise,
const void *cipher,
size_t cipher_len,
void *out_plain,
size_t out_cap,
size_t *out_len,
char *err_buf,
size_t err_cap
);
4.6 Stream Socket Framing Helpers¶
For direct operation over cais.socket:
/* Performs full synchronous handshake exchange over connected TCP socket */
cais_status_t cais_noise_handshake_socket(
cais_noise_t *noise,
cais_socket_t *sock,
char *err_buf,
size_t err_cap
);
/* Encrypts and sends a length-prefixed frame over TCP socket */
cais_status_t cais_noise_send_socket(
cais_noise_t *noise,
cais_socket_t *sock,
const void *data,
size_t len,
char *err_buf,
size_t err_cap
);
/* Receives and decrypts a length-prefixed frame from TCP socket */
cais_status_t cais_noise_recv_socket(
cais_noise_t *noise,
cais_socket_t *sock,
void *out_buf,
size_t out_cap,
size_t *out_len,
char *err_buf,
size_t err_cap
);
💻 5. Complete C89 Example¶
#include <stdio.h>
#include <string.h>
#include <cais/cais.h>
int main(void)
{
char err[128];
unsigned char server_priv[32], server_pub[32];
unsigned char client_priv[32], client_pub[32];
cais_noise_t *client, *server;
unsigned char msg1[128], msg2[128], msg3[128];
unsigned char payload[128], cipher[128], decrypted[128];
size_t mlen = 0, plen = 0, clen = 0, dlen = 0;
/* Generate Curve25519 static keys for both peers */
cais_noise_keygen(server_priv, server_pub, err, sizeof(err));
cais_noise_keygen(client_priv, client_pub, err, sizeof(err));
/* Initialize Noise_XX sessions */
client = cais_noise_create(CAIS_NOISE_XX, CAIS_NOISE_INITIATOR, err, sizeof(err));
server = cais_noise_create(CAIS_NOISE_XX, CAIS_NOISE_RESPONDER, err, sizeof(err));
cais_noise_set_static_key(client, client_priv, err, sizeof(err));
cais_noise_set_static_key(server, server_priv, err, sizeof(err));
cais_noise_start(client, err, sizeof(err));
cais_noise_start(server, err, sizeof(err));
/* Handshake Message 1: -> e */
cais_noise_write_message(client, NULL, 0, msg1, sizeof(msg1), &mlen, err, sizeof(err));
cais_noise_read_message(server, msg1, mlen, payload, sizeof(payload), &plen, err, sizeof(err));
/* Handshake Message 2: <- e, ee, s, es */
cais_noise_write_message(server, NULL, 0, msg2, sizeof(msg2), &mlen, err, sizeof(err));
cais_noise_read_message(client, msg2, mlen, payload, sizeof(payload), &plen, err, sizeof(err));
/* Handshake Message 3: -> s, se */
cais_noise_write_message(client, NULL, 0, msg3, sizeof(msg3), &mlen, err, sizeof(err));
cais_noise_read_message(server, msg3, mlen, payload, sizeof(payload), &plen, err, sizeof(err));
/* Both sessions are now in transport phase */
printf("Handshake complete: %s\n", cais_noise_is_complete(client) ? "YES" : "NO");
/* Transport Encryption: Client sends to Server */
cais_noise_encrypt(client, "Hello, C89 Noise!", 17, cipher, sizeof(cipher), &clen, err, sizeof(err));
cais_noise_decrypt(server, cipher, clen, decrypted, sizeof(decrypted), &dlen, err, sizeof(err));
decrypted[dlen] = '\0';
printf("Server received decrypted: '%s'\n", (char *)decrypted);
cais_noise_free(client);
cais_noise_free(server);
return 0;
}