writeonce/runtime/src/tls.h

/* tls.h — hand-rolled TLS 1.3 (runtime-v2 9 phase F). Sits on the crypto
 * ladder (crypto.h): AEAD (A), HKDF (B), X25519 (C), signatures (D), X.509
 * (E). This header is phase F: the record layer first, the handshake FSM and
 * net.connect_tls on top. Internal C; the VM enters through net builtins. */
#ifndef WO_TLS_H
#define WO_TLS_H

#include <stddef.h>
#include <stdint.h>

/* The two SHA-256 TLS 1.3 cipher suites we implement. AES-128-GCM is
 * mandatory-to-implement (RFC 8446 §9.1); ChaCha20-Poly1305 is the portable
 * fallback when the CPU has no AES-NI. AES-256-GCM uses SHA-384 and is a later
 * add (the HKDF is SHA-256 today). */
enum {
    WO_TLS_AES_128_GCM_SHA256 = 1,
    WO_TLS_CHACHA20_POLY1305_SHA256 = 2,
};

/* TLS 1.3 record content types (RFC 8446 §5.1). */
enum {
    WO_TLS_CT_CHANGE_CIPHER_SPEC = 20,
    WO_TLS_CT_ALERT = 21,
    WO_TLS_CT_HANDSHAKE = 22,
    WO_TLS_CT_APPLICATION_DATA = 23,
};

/* Overhead a sealed record adds over its plaintext: 5-byte header + 1-byte
 * inner content-type + 16-byte AEAD tag. */
#define WO_TLS_RECORD_OVERHEAD 22

/* Seal one TLS 1.3 record (RFC 8446 §5.2). Writes the full wire record —
 * 5-byte header || encrypted (TLSInnerPlaintext) || 16-byte tag — into out,
 * which must hold at least ptlen + WO_TLS_RECORD_OVERHEAD bytes. `seq` is the
 * record sequence number; the per-record nonce is iv XOR seq (big-endian, §5.3).
 * No padding. Returns the record length, or -1 on a bad suite. */
int wo_tls_record_seal(int suite, const uint8_t *key, size_t keylen,
                       const uint8_t iv[12], uint64_t seq, uint8_t content_type,
                       const uint8_t *pt, size_t ptlen, uint8_t *out);

/* Open one TLS 1.3 record. `rec` is the full wire record (header included),
 * reclen its length. Writes the recovered content into out (must hold
 * reclen bytes) and the recovered inner content-type into *content_type,
 * after stripping trailing zero padding (§5.2/§5.4). Returns the content
 * length, or -1 on a malformed record or AEAD authentication failure. */
int wo_tls_record_open(int suite, const uint8_t *key, size_t keylen,
                       const uint8_t iv[12], uint64_t seq, const uint8_t *rec,
                       size_t reclen, uint8_t *out, uint8_t *content_type);

/* ---- key schedule (phase F2, RFC 8446 §7.1, SHA-256) --------------------- */

/* The traffic secrets the handshake derives, in the order they become known. */
typedef struct {
    uint8_t handshake_secret[32];
    uint8_t master_secret[32];
    uint8_t client_hs_traffic[32];
    uint8_t server_hs_traffic[32];
    uint8_t client_ap_traffic[32];
    uint8_t server_ap_traffic[32];
} wo_tls_key_schedule;

/* Handshake-phase secrets from the ECDHE shared secret and the
 * ClientHello..ServerHello transcript hash. Fills handshake_secret, the two
 * hs-traffic secrets, and master_secret (which needs no further transcript). */
void wo_tls_derive_handshake(wo_tls_key_schedule *ks, const uint8_t *ecdhe,
                             size_t ecdhe_len, const uint8_t hash_ch_sh[32]);

/* Application-phase traffic secrets from master_secret (already in ks) and the
 * ClientHello..server-Finished transcript hash. */
void wo_tls_derive_application(wo_tls_key_schedule *ks,
                               const uint8_t hash_ch_sf[32]);

/* Per-direction AEAD key (key_len 16 or 32) and 12-byte IV from a traffic
 * secret (HKDF-Expand-Label "key"/"iv"). */
void wo_tls_traffic_keys(const uint8_t traffic_secret[32], size_t key_len,
                         uint8_t *key, uint8_t iv[12]);

/* Finished verify_data = HMAC(HKDF-Expand-Label(base_key,"finished","",32),
 * transcript_hash). Same routine builds and checks it (compare with ct_memeq). */
void wo_tls_finished_verify(const uint8_t base_key[32],
                            const uint8_t transcript_hash[32], uint8_t out[32]);

/* ---- handshake messages (phase F3, RFC 8446 §4) -------------------------- */

/* Parse a ServerHello handshake message (bytes start at the handshake type
 * 0x02). Fills *suite (a WO_TLS_* enum) and the server's 32-byte X25519 key
 * share. Returns 0, or -1 on any malformation, an unsupported suite/group, or
 * a HelloRetryRequest. */
int wo_tls_parse_server_hello(const uint8_t *msg, size_t len, int *suite,
                              uint8_t server_pub[32]);

/* Verify a server CertificateVerify (RFC 8446 §4.4.3) against the leaf
 * certificate DER, given the negotiated signature_scheme wire value, the
 * signature, and the running transcript hash (ClientHello..Certificate). Only
 * rsa_pss_rsae_sha256 (0x0804), rsa_pkcs1_sha256 (0x0401) and
 * ecdsa_secp256r1_sha256 (0x0403) are accepted, and the scheme must match the
 * leaf key type. Returns 1 valid, 0 otherwise. */
int wo_tls_verify_cert_verify(const uint8_t *leaf_der, size_t leaf_len,
                              uint16_t sig_scheme, const uint8_t *sig,
                              size_t sig_len, const uint8_t transcript_hash[32]);

/* Build a ClientHello handshake message offering TLS 1.3 / x25519 /
 * RSA-PSS+RSA-PKCS1+ECDSA-P256, for `hostname` (SNI). random32 and the 32-byte
 * legacy session_id are caller-supplied. Writes into out (cap outcap); *outlen
 * gets the length. Returns 0, or -1 if the buffer is too small. */
int wo_tls_build_client_hello(const char *hostname, size_t hostlen,
                              const uint8_t client_pub[32],
                              const uint8_t random32[32],
                              const uint8_t session_id[32], uint8_t *out,
                              size_t outcap, size_t *outlen);

/* ---- sans-io client handshake driver (phase F3c) -------------------------
 * A pure state machine: no sockets. The caller frames TLS records (read the
 * 5-byte header, then that many bytes) and feeds whole records in; the driver
 * advances the handshake and hands back bytes to send. This keeps every I/O
 * concern out of the security-critical FSM, so it is fully testable offline
 * (KAT'd against the RFC 8448 record trace).
 *
 * SECURITY NOTE — not yet a safe live client: this core verifies the server's
 * CertificateVerify and Finished (proving possession of the leaf key) but does
 * NOT yet walk the certificate chain to a trust anchor or match the hostname
 * against the cert SAN. Those (the deferred phase-E bits) MUST land before this
 * drives a real connection, or the client is open to MITM. It is currently an
 * internal building block; net.connect_tls is not wired to it. */

#define WO_TLS_BUF_MAX 16384u     /* transcript / reassembly cap (RFC 8448 fits) */
#define WO_TLS_LEAF_MAX 8192u     /* largest leaf certificate accepted */

typedef enum {
    WO_TLS_WANT_MORE = 0,         /* need another record */
    WO_TLS_ESTABLISHED = 1,       /* handshake done; output holds client Finished */
    WO_TLS_FAILED = -1,           /* verification/parse failure — connection dead */
} wo_tls_status;

typedef struct {
    int suite;
    size_t keylen;                            /* AEAD key length, 16 or 32 */
    uint8_t client_priv[32], client_pub[32];
    wo_tls_key_schedule ks;
    /* current read/write record protection (handshake, then application) */
    uint8_t rd_key[32], rd_iv[12], wr_key[32], wr_iv[12];
    uint64_t rd_seq, wr_seq;
    uint8_t transcript[WO_TLS_BUF_MAX]; size_t tlen;
    uint8_t hsbuf[WO_TLS_BUF_MAX]; size_t hsn;   /* reassembled handshake bytes */
    uint8_t leaf[WO_TLS_LEAF_MAX]; size_t leaflen;
    uint16_t cv_scheme;
    uint8_t out[1024]; size_t outn;              /* bytes for the caller to send */
    int st;                                      /* internal FSM state */
} wo_tls_client;

/* Start a handshake from a caller-built ClientHello handshake message and a
 * fixed X25519 private key (production passes fresh randomness; the KAT injects
 * the RFC's). Frames the ClientHello into a plaintext record in c->out for the
 * caller to send, and seeds the transcript. 0 ok, -1 on a buffer problem. */
int wo_tls_client_start_with(wo_tls_client *c, const uint8_t *ch_msg,
                             size_t ch_len, const uint8_t priv[32]);

/* Feed one whole TLS record. Advances the FSM. Returns WANT_MORE (need the
 * next record), ESTABLISHED (handshake complete — drain c->out for the client
 * Finished, then use the encrypt/decrypt calls), or FAILED. */
wo_tls_status wo_tls_client_push_record(wo_tls_client *c, const uint8_t *rec,
                                        size_t reclen);

/* Copy out (and clear) the bytes the driver wants sent. Returns the count. */
size_t wo_tls_client_take_output(wo_tls_client *c, uint8_t *out, size_t outcap);

/* Application data, post-handshake (application traffic keys). encrypt writes a
 * full record into out; decrypt reads one record and yields the plaintext plus
 * its inner content type. Return the byte count, or -1 on overflow / auth
 * failure. */
int wo_tls_client_encrypt(wo_tls_client *c, const uint8_t *data, size_t len,
                          uint8_t *out, size_t outcap);
int wo_tls_client_decrypt(wo_tls_client *c, const uint8_t *rec, size_t reclen,
                          uint8_t *out, size_t outcap, uint8_t *content_type);

#endif