http3_envelope.h
http-3.0/http3_envelope.h · 182 line(s) · c
/* ==========================================================================
* http3_envelope.h -- SLeeLa HTTP 3.0 compact application envelope (spec §5)
* and response model (spec §7).
*
* The envelope is the unit of data that DRIVES the HTTP 3.0 application
* protocol. It carries, in a fixed logical order:
*
* VERSION | FLAGS | SERVICE-ID | OP-ID | REQUEST-ID
* | NONCE | DIGEST | INTACTX | BASKET | PAYLOAD (§5)
*
* DIGEST is a per-packet 64-bit KEYED MAC (SipHash-2-4, see http3_mac.h) over
* the header + payload under a per-connection secret key: it detects both
* accidental corruption and DELIBERATE tampering, because a packet cannot be
* rewritten with a matching tag without the key. NONCE is a per-connection
* monotonically increasing counter covered by the MAC; the receiver keeps a
* high-water mark and rejects any packet whose NONCE is not strictly greater,
* which defeats replay of a previously valid (and validly MAC'd) packet.
* INTACTX is a system-specific 64-bit host-integrity identity (see
* http3_intactx.h): it fingerprints the emitting host and encodes how far that
* host has drifted from its baseline, so a tampered/changed machine reports a
* statically larger value and the receiver can RESET the exchange. BASKET is
* the fixed basket of goods & services (see http3_basket.h), atomic-bound to
* the US capitalism system, carried on every packet as a canonical block and
* covered by the MAC.
*
* and a response carries:
*
* STATUS | REQUEST-ID | RESULT (§7)
*
* Per the spec, the wire form MAY be textual (interoperable) or binary
* (negotiated, high-performance). Both are implemented here so the same
* logical envelope can travel either way (§5, §14 capability negotiation).
* ========================================================================== */
#ifndef HTTP3_ENVELOPE_H
#define HTTP3_ENVELOPE_H
#include <stddef.h>
#include <stdint.h>
#include "http3_mac.h" /* HTTP3_MAC_KEY_BYTES, keyed-MAC DIGEST */
#include "http3_basket.h" /* HTTP3_BASKET_BLOCK_SIZE, the per-packet basket */
#include "http3_port.h" /* 160-bit logical port number */
#ifdef __cplusplus
extern "C" {
#endif
/* Protocol generation of the envelope itself (distinct from any payload
* version). "3" names the SLeeLa HTTP 3.0 protocol generation, NOT the IETF
* HTTP/3 transport (spec §2). */
#define HTTP3_ENVELOPE_VERSION 3u
/* Maximum payload an envelope will carry in this reference implementation.
* A real deployment negotiates this (§14 max envelope size). */
#define HTTP3_ENVELOPE_MAX_PAYLOAD 4096u
/* FLAGS bitfield (§5). Flags are advisory hints about the request; the
* authoritative meaning of an operation stays with the service. */
typedef enum {
HTTP3_FLAG_NONE = 0x00,
HTTP3_FLAG_BINARY = 0x01, /* wire form is binary, not textual */
HTTP3_FLAG_COMPRESSED = 0x02, /* payload is compressed (§11) */
HTTP3_FLAG_STREAM = 0x04, /* part of a streaming exchange (§10) */
HTTP3_FLAG_IDEMPOTENT = 0x08, /* caller asserts idempotency (§9) */
HTTP3_FLAG_RESET = 0x10 /* packet reset: host tampered/untrusted */
} http3_envelope_flag_t;
/*
* The compact application envelope (§5). SERVICE-ID and OP-ID are
* connection/service-local compact identifiers produced by fast naming (§4);
* they MUST NOT be assumed globally stable. REQUEST-ID correlates a response
* with its originating request without relying on ordering (§6).
*/
typedef struct {
uint8_t version; /* VERSION */
uint8_t flags; /* FLAGS */
uint32_t service_id; /* SERVICE-ID */
uint32_t op_id; /* OP-ID */
uint64_t request_id; /* REQUEST-ID */
http3_port_t port; /* PORT: 0..10^48-1 */
uint64_t nonce; /* NONCE (replay guard) */
uint64_t digest; /* DIGEST */
uint64_t intactx; /* INTACTX */
uint8_t basket[HTTP3_BASKET_BLOCK_SIZE]; /* BASKET (canonical block) */
uint8_t payload[HTTP3_ENVELOPE_MAX_PAYLOAD]; /* PAYLOAD */
size_t payload_len;
} http3_envelope_t;
/* Application execution status (§7). Distinguishes transport acceptance from
* application execution: transport OK never implies business success. */
typedef enum {
HTTP3_STATUS_OK = 0, /* application executed successfully */
HTTP3_STATUS_APP_ERROR = 1, /* transport fine, business logic failed */
HTTP3_STATUS_UNKNOWN_SVC = 2, /* service id not resolvable */
HTTP3_STATUS_UNKNOWN_OP = 3, /* operation id not resolvable */
HTTP3_STATUS_BAD_ENVELOPE = 4, /* envelope failed to parse/validate */
HTTP3_STATUS_TOO_LARGE = 5, /* payload/envelope exceeded a limit (§13) */
HTTP3_STATUS_RETRY_DENIED = 6, /* unsafe retry refused (§9) */
HTTP3_STATUS_BAD_DIGEST = 7, /* per-packet DIGEST did not verify */
HTTP3_STATUS_TAMPERED = 8, /* INTACTX variance exceeded threshold */
HTTP3_STATUS_REPLAYED = 9 /* NONCE not ahead of high-water: replay */
} http3_status_t;
/* The response model (§7): STATUS | REQUEST-ID | RESULT. */
typedef struct {
http3_status_t status;
uint64_t request_id; /* echoes the request (§6) */
uint8_t result[HTTP3_ENVELOPE_MAX_PAYLOAD]; /* RESULT */
size_t result_len;
} http3_response_t;
/* ---- Construction --------------------------------------------------------- */
/* Initialize an envelope with ids, INTACTX host identity, and payload. The
* fixed basket (http3_basket.h) is serialized into the packet automatically,
* and the per-packet DIGEST (keyed MAC) is computed and stored over the finished
* header + basket + payload under `key` (a 16-byte per-connection secret).
* Returns 0 on success, -1 if the payload is too large or an argument is NULL. */
int http3_envelope_init(http3_envelope_t *env,
uint32_t service_id,
uint32_t op_id,
uint64_t request_id,
uint8_t flags,
uint64_t nonce,
uint64_t intactx,
const uint8_t key[HTTP3_MAC_KEY_BYTES],
const uint8_t *payload,
size_t payload_len);
/* ---- Integrity: per-packet DIGEST (keyed MAC) ----------------------------- */
/* Compute the 64-bit keyed-MAC DIGEST over an envelope's header fields
* (excluding the digest itself) and payload, under the 16-byte `key`.
* Deterministic and independent of wire form. Returns 0 on a NULL argument. */
uint64_t http3_envelope_compute_digest(const http3_envelope_t *env,
const uint8_t key[HTTP3_MAC_KEY_BYTES]);
/* Recompute the MAC under `key` and compare against env->digest. Returns 1 if
* the stored digest matches (packet authentic + intact), 0 otherwise. */
int http3_envelope_verify_digest(const http3_envelope_t *env,
const uint8_t key[HTTP3_MAC_KEY_BYTES]);
/* Set the actual extended logical port and reseal the packet DIGEST. */
int http3_envelope_set_port_decimal(http3_envelope_t *env,
const char *decimal,
const uint8_t key[HTTP3_MAC_KEY_BYTES]);
int http3_envelope_set_port_u64(http3_envelope_t *env,
uint64_t port,
const uint8_t key[HTTP3_MAC_KEY_BYTES]);
/* ---- Textual wire form (§5: textual for interoperability) -----------------
* Line form (single line, newline-terminated):
* H3 <version> <flags> <service_id> <op_id> <request_id> <port> <nonce> <digest> <intactx> <basket-hex> <payload_len>:<payload-bytes>
* BASKET travels as a lowercase-hex token (2*HTTP3_BASKET_BLOCK_SIZE chars).
* The payload is length-prefixed so it is binary-safe and space-safe.
*/
int http3_envelope_pack_text(const http3_envelope_t *env, char *out, size_t out_cap, size_t *written);
int http3_envelope_unpack_text(const char *in, size_t in_len, http3_envelope_t *env);
/* ---- Binary wire form (§5: binary for negotiated high performance) --------
* Fixed header, big-endian, then the basket block, then raw payload:
* [ver:1][flags:1][service_id:4][op_id:4][request_id:8][port:20][nonce:8][digest:8][intactx:8][basket:HTTP3_BASKET_BLOCK_SIZE][payload_len:4][payload:N]
*/
#define HTTP3_ENVELOPE_BIN_HEADER (66u + HTTP3_BASKET_BLOCK_SIZE)
int http3_envelope_pack_binary(const http3_envelope_t *env, uint8_t *out, size_t out_cap, size_t *written);
int http3_envelope_unpack_binary(const uint8_t *in, size_t in_len, http3_envelope_t *env);
/* ---- Response textual form (§7) -------------------------------------------
* H3R <status> <request_id> <result_len>:<result-bytes>
*/
int http3_response_pack_text(const http3_response_t *resp, char *out, size_t out_cap, size_t *written);
int http3_response_unpack_text(const char *in, size_t in_len, http3_response_t *resp);
/* Human-readable status name (for logs/§17 admin). */
const char *http3_status_name(http3_status_t status);
#ifdef __cplusplus
}
#endif
#endif /* HTTP3_ENVELOPE_H */