Home /Modules/http-3.0/http3_envelope.h

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 */