Home /Modules/http-3.0/http3_handshake.h

http3_handshake.h

http-3.0/http3_handshake.h · 111 line(s) · c

/* ==========================================================================
 * http3_handshake.h -- SLeeLa HTTP 3.0 capability-negotiation handshake.
 *
 * Two peers (a client and a router/server) each advertise the set of protocol
 * capability LEVELS they support, as a neutral bitmask. The handshake then
 * deterministically selects the HIGHEST COMMON LEVEL both peers support.
 *
 * Levels are cumulative delivery-efficiency tiers (see QOS.md / the timing
 * work): each higher level implies the ones below it.
 *
 *   L1 BASELINE  : envelope + integrity gate only (always supported).
 *   L2 PER_LEG   : per-leg MSS / path-MTU sizing for goodput.
 *   L3 PACING    : timing-aware pacing (max-speed / balance).
 *   L4 ECHO      : echo-acknowledged, deadline-aware delivery.
 *
 * A peer whose software is not yet updated advertises only the levels it knows
 * (at minimum L1). The negotiation therefore lets an older router run the
 * MODEST BASELINE and transparently move up once its software is apt to update
 * and it advertises higher levels -- no flag day, no identity, just the highest
 * level both ends actually support.
 *
 * The 4-byte capability offer is covered by the connection's keyed MAC
 * (http3_mac.h): a peer cannot have its advertised capabilities silently
 * downgraded/upgraded in flight without invalidating the tag.
 *
 * The capability value is a plain bitmask. It carries NO national, geographic,
 * or identity meaning -- it names supported protocol tiers only.
 *
 * Pure data: no I/O, no allocation.
 * ========================================================================== */
#ifndef HTTP3_HANDSHAKE_H
#define HTTP3_HANDSHAKE_H

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

#include "http3_mac.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Capability levels as bit flags (cumulative tiers). */
typedef enum {
    HTTP3_CAP_NONE     = 0x00,
    HTTP3_CAP_L1_BASE  = 0x01, /* baseline: envelope + integrity gate       */
    HTTP3_CAP_L2_PERLEG= 0x02, /* per-leg MSS / path-MTU sizing             */
    HTTP3_CAP_L3_PACING= 0x04, /* timing-aware pacing (max-speed/balance)   */
    HTTP3_CAP_L4_ECHO  = 0x08  /* echo-acknowledged, deadline-aware delivery*/
} http3_cap_flag_t;

/* The baseline every conforming peer must support. */
#define HTTP3_CAP_BASELINE HTTP3_CAP_L1_BASE

/* Full set a fully-updated peer advertises (L1..L4). */
#define HTTP3_CAP_ALL \
    (HTTP3_CAP_L1_BASE | HTTP3_CAP_L2_PERLEG | HTTP3_CAP_L3_PACING | HTTP3_CAP_L4_ECHO)

/*
 * A peer's capability offer: the 32-bit bitmask it advertises, plus a MAC tag
 * over the offer (computed under the shared connection key).
 */
typedef struct {
    uint32_t capabilities; /* OR of http3_cap_flag_t the peer supports */
    uint64_t mac;          /* keyed MAC over the canonical offer bytes  */
} http3_cap_offer_t;

/*
 * Build a capability offer: normalizes `capabilities` to always include the
 * baseline (L1), then stamps the MAC under `key`. Returns 0 on success, -1 on a
 * NULL argument.
 */
int http3_handshake_make_offer(http3_cap_offer_t *offer,
                               uint32_t capabilities,
                               const uint8_t key[HTTP3_MAC_KEY_BYTES]);

/* Verify an offer's MAC under `key`. Returns 1 if authentic, 0 otherwise. */
int http3_handshake_verify_offer(const http3_cap_offer_t *offer,
                                 const uint8_t key[HTTP3_MAC_KEY_BYTES]);

/*
 * Deterministically select the negotiated level from two offers: the HIGHEST
 * single level present in BOTH peers' capability sets (levels are cumulative,
 * so the result is one of HTTP3_CAP_L1_BASE..L4_ECHO). Because every conforming
 * peer includes the baseline, the result is at least L1 -- an older peer simply
 * caps the pair at the modest baseline until it advertises more.
 *
 * Returns the selected level flag, or HTTP3_CAP_NONE only if a peer failed to
 * include the baseline (non-conforming).
 */
uint32_t http3_handshake_negotiate(uint32_t local_caps, uint32_t remote_caps);

/*
 * Full handshake step over two received offers: verify BOTH MACs under `key`,
 * then negotiate. Writes the agreed level to *agreed. Returns 0 on success, -1
 * if either MAC fails (agreed set to HTTP3_CAP_NONE) or on a NULL argument.
 */
int http3_handshake_resolve(const http3_cap_offer_t *local,
                            const http3_cap_offer_t *remote,
                            const uint8_t key[HTTP3_MAC_KEY_BYTES],
                            uint32_t *agreed);

/* Human-readable level name (e.g. "L3_PACING") for logs/diagnostics. */
const char *http3_handshake_level_name(uint32_t level);

#ifdef __cplusplus
}
#endif

#endif /* HTTP3_HANDSHAKE_H */