tunnel.h File Reference

UDIF tunnel abstraction over a QSTP secure channel. More...

#include "udif.h"
#include "message.h"
#include "qstp.h"

Go to the source code of this file.

Data Structures
struct	udif_tunnel_record_header
	Canonical UDIF transport record header. More...
struct	udif_tunnel
	Per-connection UDIF state layered atop a QSTP channel. More...

Macros
#define	UDIF_TRANSPORT_PROFILE_QSTP_INNER_HEADER   1U
	The normative UDIF transport profile implemented by this codebase.
#define	UDIF_TRANSPORT_HEADER_EXTERNAL_AAD   0U
	Indicates whether UDIF passes the record header as external AEAD AAD.
#define	UDIF_TRANSPORT_RATCHET_DELEGATED_TO_QSTP   1U
	Indicates whether branch-trunk rekeying is delegated to QSTP.
#define	UDIF_TUNNEL_RECORD_HEADER_SIZE   26U
	Canonical UDIF transport record header size in bytes.
#define	UDIF_TUNNEL_TIME_WINDOW_SECONDS   60U
	Maximum accepted sender clock skew in seconds.
#define	UDIF_TUNNEL_FLAG_DATA   0x01U
	Tunnel record carries application data.
#define	UDIF_TUNNEL_FLAG_KEEPALIVE   0x02U
	Tunnel record carries an application keepalive.
#define	UDIF_TUNNEL_FLAG_CLOSE   0x04U
	Tunnel record carries an orderly close notification.
#define	UDIF_TUNNEL_FLAG_CONTROL   0x08U
	Tunnel record carries control-plane data.
#define	UDIF_KEEPALIVE_INTERVAL_A_SECONDS   300U
	Keepalive send interval (seconds) for Profile-A (Authority/Root).
#define	UDIF_KEEPALIVE_INTERVAL_E_SECONDS   120U
	Keepalive send interval (seconds) for Profile-E (Enterprise).
#define	UDIF_KEEPALIVE_INTERVAL_U_SECONDS   120U
	Keepalive send interval (seconds) for Profile-U (User/Edge).
#define	UDIF_KEEPALIVE_INTERVAL_SECONDS   UDIF_KEEPALIVE_INTERVAL_E_SECONDS
	Default keepalive interval (seconds). Override at compile time to select a profile.
#define	UDIF_IDLE_TEARDOWN_MULTIPLIER   2U
	Multiplier applied to the keepalive interval to derive the idle teardown threshold.
#define	UDIF_IDLE_TEARDOWN_SECONDS   (UDIF_KEEPALIVE_INTERVAL_SECONDS * UDIF_IDLE_TEARDOWN_MULTIPLIER)
	Computed idle teardown threshold in seconds.
#define	UDIF_RATCHET_INTERVAL_SECONDS   3600U
	BC<->BC trunk QSTP rekey interval in seconds.
#define	UDIF_RATCHET_JITTER_SECONDS   300U
	Ratchet jitter bound in seconds (+/- 5 minutes per spec).

Typedefs
typedef UDIF_EXPORT_API struct udif_tunnel_record_header	udif_tunnel_record_header
typedef enum udif_rolepair	udif_rolepair
typedef enum udif_tunnel_side	udif_tunnel_side
typedef UDIF_EXPORT_API struct udif_tunnel	udif_tunnel

Enumerations
enum	udif_rolepair {   udif_rolepair_none = 0U , udif_rolepair_ua_gc = 1U , udif_rolepair_gc_bc = 2U , udif_rolepair_bc_bc = 3U ,   udif_rolepair_bc_root = 4U , udif_rolepair_treaty = 5U }
	Identifies the trust-tree relationship a tunnel spans. More...
enum	udif_tunnel_side { udif_tunnel_side_client = 0U , udif_tunnel_side_server = 1U }
	Which end of a tunnel this entity occupies. More...

Functions
UDIF_EXPORT_API udif_errors	udif_tunnel_record_header_serialize (uint8_t *output, size_t outlen, const udif_tunnel_record_header *header)
	Serialize a UDIF tunnel record header.
UDIF_EXPORT_API udif_errors	udif_tunnel_record_header_deserialize (udif_tunnel_record_header *header, const uint8_t *input, size_t inlen)
	Deserialize a UDIF tunnel record header.
UDIF_EXPORT_API udif_errors	udif_tunnel_record_header_validate (const udif_tunnel *tun, const udif_tunnel_record_header *header, uint64_t nowsecs)
	Validate a received UDIF tunnel record header against tunnel state.
UDIF_EXPORT_API uint8_t	udif_tunnel_record_flag (udif_message_type msgtype)
	Return the UDIF tunnel record flag for a message type.
UDIF_EXPORT_API udif_errors	udif_tunnel_init (udif_tunnel *tun, qstp_connection_state *qstpcns, const uint8_t *peerserial, udif_rolepair rolepair, udif_tunnel_side side, const uint8_t *treatyid, uint64_t nowsecs)
	Initialize a freshly-opened tunnel record.
UDIF_EXPORT_API void	udif_tunnel_close (udif_tunnel *tun, bool notify)
	Close the tunnel and clear its state.
UDIF_EXPORT_API udif_errors	udif_tunnel_send (udif_tunnel *tun, const udif_message *msg, uint64_t nowsecs)
	Encode and send a UDIF message over the tunnel.
UDIF_EXPORT_API udif_errors	udif_tunnel_on_receive (udif_tunnel *tun, const uint8_t *input, size_t inplen, udif_message *outmsg, uint64_t nowsecs)
	Process an inbound decrypted payload delivered by QSTP.
UDIF_EXPORT_API udif_errors	udif_tunnel_tick (udif_tunnel *tun, uint64_t nowsecs)
	Drive per-tunnel timers forward.
UDIF_EXPORT_API udif_errors	udif_tunnel_send_keepalive (udif_tunnel *tun, uint64_t nowsecs)
	Force an immediate keepalive send, independent of the timer.
UDIF_EXPORT_API udif_errors	udif_tunnel_trigger_ratchet (udif_tunnel *tun, uint64_t nowsecs)
	Force an immediate ratchet trigger on a BC<->BC trunk.
UDIF_EXPORT_API bool	udif_tunnel_is_open (const udif_tunnel *tun, uint64_t nowsecs)
	Check whether the tunnel is open and operational.

Detailed Description

UDIF tunnel abstraction over a QSTP secure channel.

A udif_tunnel wraps a single QSTP connection and adds UDIF-specific lifecycle policy: per-role-pair behavior, application-level keepalives (required because QSTP no longer provides them), idle teardown, and for BC<->BC trunks, scheduled QSTP rekey triggers that invoke qstp_send_symmetric_ratchet_request.

Data flow. QSTP is callback-driven, so tunnel I/O is not a symmetric send/recv pair. On the send path, udif_tunnel_send encodes a udif_message, prepends a canonical UDIF tunnel record header, calls qstp_encrypt_packet to seal the resulting inner record, serializes the packet, and writes it to the underlying socket. On the receive path, QSTP's receive thread decrypts the next packet and invokes a registered callback; that callback (installed by the entity's main loop) calls udif_tunnel_on_receive, which validates the UDIF inner header, decodes the payload as a udif_message, and hands it to the dispatcher. There is no blocking udif_tunnel_recv.

Formal transport profile. UDIF delegates outer handshake authentication, packet confidentiality, packet integrity, and channel rekeying to QSTP. UDIF does not pass a separate associated-data pointer into QSTP. Instead, the UDIF header is an inner, encrypted, and authenticated record prefix:

QSTP-Seal(UDIF-Header || UDIF-Message)

The QSTP authentication tag therefore covers the UDIF header because the header is part of the sealed plaintext. UDIF then validates suite, epoch, sequence, time window, and record class after successful QSTP authentication and before dispatch. This is the normative implementation profile for this codebase. The written UDIF specification and formal analysis should describe this QSTP-wrapped inner-header model rather than an independent UDIF AEAD header passed as external AAD.

Macro Definition Documentation

UDIF_TRANSPORT_HEADER_EXTERNAL_AAD

#define UDIF_TRANSPORT_HEADER_EXTERNAL_AAD   0U

Indicates whether UDIF passes the record header as external AEAD AAD.

This implementation does not use a separate external-AAD parameter. The UDIF header is protected as part of the QSTP-sealed plaintext.

UDIF_TRANSPORT_PROFILE_QSTP_INNER_HEADER

#define UDIF_TRANSPORT_PROFILE_QSTP_INNER_HEADER   1U

The normative UDIF transport profile implemented by this codebase.

A value of one indicates that UDIF records are sealed by QSTP as inner records of the form UDIF-Header || UDIF-Message.

Enumeration Type Documentation

udif_rolepair

enum udif_rolepair

Identifies the trust-tree relationship a tunnel spans.

Role-pair governs lifecycle policy: which tunnels use QSTP rekeying, which are ephemeral, and which carry a treaty identifier.

Enumerator
udif_rolepair_none	Uninitialized
udif_rolepair_ua_gc	UA <-> GC; ephemeral; UA is client; no periodic ratchet
udif_rolepair_gc_bc	GC <-> BC; persistent; GC is client; no periodic ratchet
udif_rolepair_bc_bc	BC <-> BC trunk; persistent; hourly QSTP rekey
udif_rolepair_bc_root	BC <-> Root; persistent; BC is client; no periodic ratchet
udif_rolepair_treaty	Treaty tunnel; separate QSTP session; treaty-id tagged

udif_tunnel_side

enum udif_tunnel_side

Which end of a tunnel this entity occupies.

The client side is responsible for triggering QSTP rekeying on ratcheting role pairs. Both sides maintain independent keepalive timers.

Enumerator
udif_tunnel_side_client	Client end (initiator)
udif_tunnel_side_server	Server end (listener)

Function Documentation

udif_tunnel_close()

UDIF_EXPORT_API void udif_tunnel_close	(	udif_tunnel *	tun,
		bool	notify )

Close the tunnel and clear its state.

Invokes qstp_connection_close on qstpcns if still open, marks the tunnel closing, and zeroes timer fields. Idempotent.

Parameters

tun	The tunnel (may be NULL)
notify	If true, instructs QSTP to notify the remote peer of the close

udif_tunnel_init()

UDIF_EXPORT_API udif_errors udif_tunnel_init	(	udif_tunnel *	tun,
		qstp_connection_state *	qstpcns,
		const uint8_t *	peerserial,
		udif_rolepair	rolepair,
		udif_tunnel_side	side,
		const uint8_t *	treatyid,
		uint64_t	nowsecs )

Initialize a freshly-opened tunnel record.

Call after the QSTP handshake has completed and a qstp_connection_state is available. Populates timers from nowsecs and role-pair policy. Does not take ownership of qstpcns.

For non-ratcheting role pairs, ratchetdeadline is set to 0. For treaty tunnels, treatyid is copied in; for other role pairs, treatyid may be NULL and is zeroed.

Parameters

tun	The tunnel record to initialize
qstpcns	The established QSTP connection
peerserial	[const] The 16-byte serial of the remote certificate
rolepair	The role-pair classification
side	Which end this entity occupies
treatyid	[const] The 16-byte treaty id (required when rolepair == udif_rolepair_treaty; may be NULL otherwise)
nowsecs	The current UTC seconds

Returns

Returns udif_error_none on success, udif_error_invalid_input on bad arguments.

udif_tunnel_is_open()

UDIF_EXPORT_API bool udif_tunnel_is_open	(	const udif_tunnel *	tun,
		uint64_t	nowsecs )

Check whether the tunnel is open and operational.

A tunnel is operational when qstpcns is non-NULL, closing is false, and nowsecs < idledeadline.

Parameters

tun	[const] The tunnel (may be NULL; returns false)
nowsecs	The current UTC seconds

Returns

Returns true if operational, false otherwise.

udif_tunnel_on_receive()

UDIF_EXPORT_API udif_errors udif_tunnel_on_receive	(	udif_tunnel *	tun,
		const uint8_t *	input,
		size_t	inplen,
		udif_message *	outmsg,
		uint64_t	nowsecs )

Process an inbound decrypted payload delivered by QSTP.

Intended to be invoked from inside the receive_callback passed to qstp_client_connect_ipv4 or qstp_server_start_ipv4. The bytes supplied are the plaintext payload produced by qstp_decrypt_packet; QSTP has already validated the outer QSTP packet and authentication tag. This function validates the inner UDIF record header before decoding the udif_message.

Decodes the inner UDIF message and writes it to outmsg (caller-owned; caller must dispose with udif_message_dispose). On success updates lastrxsecs and pushes idledeadline forward to lastrxsecs + UDIF_IDLE_TEARDOWN_SECONDS. Keepalives are surfaced to the caller rather than swallowed so the dispatcher can update telemetry.

Parameters

tun	The tunnel the payload arrived on
input	[const] The decrypted payload bytes
inplen	The length of the decrypted payload in bytes
outmsg	The output message (caller disposes on success)
nowsecs	The current UTC seconds (for timer updates)

Returns

Returns udif_error_none on success, udif_error_decode_failure on a malformed frame, udif_error_invalid_state if the tunnel is closing.

udif_tunnel_record_flag()

UDIF_EXPORT_API uint8_t udif_tunnel_record_flag

(

udif_message_type

msgtype

)

Return the UDIF tunnel record flag for a message type.

Parameters

msgtype

The UDIF message type.

Returns

Returns a UDIF_TUNNEL_FLAG_* value.

udif_tunnel_record_header_deserialize()

UDIF_EXPORT_API udif_errors udif_tunnel_record_header_deserialize	(	udif_tunnel_record_header *	header,
		const uint8_t *	input,
		size_t	inlen )

Deserialize a UDIF tunnel record header.

Parameters

header	The output header.
input	[const] The encoded header.
inlen	The length of the encoded header.

Returns

Returns udif_error_none on success.

udif_tunnel_record_header_serialize()

UDIF_EXPORT_API udif_errors udif_tunnel_record_header_serialize	(	uint8_t *	output,
		size_t	outlen,
		const udif_tunnel_record_header *	header )

Serialize a UDIF tunnel record header.

Parameters

output	The output buffer.
outlen	The length of the output buffer.
header	[const] The header to serialize.

Returns

Returns udif_error_none on success.

udif_tunnel_record_header_validate()

UDIF_EXPORT_API udif_errors udif_tunnel_record_header_validate	(	const udif_tunnel *	tun,
		const udif_tunnel_record_header *	header,
		uint64_t	nowsecs )

Validate a received UDIF tunnel record header against tunnel state.

Parameters

tun	[const] The tunnel state.
header	[const] The decoded header.
nowsecs	Current UTC seconds.

Returns

Returns udif_error_none on success.

udif_tunnel_send()

UDIF_EXPORT_API udif_errors udif_tunnel_send	(	udif_tunnel *	tun,
		const udif_message *	msg,
		uint64_t	nowsecs )

Encode and send a UDIF message over the tunnel.

Serializes msg to canonical form, hands it to qstp_encrypt_packet for sealing, serializes the resulting qstp_network_packet via qstp_packet_to_stream, and writes the bytes to the underlying socket via qsc_socket_send. On success updates lasttxsecs and pushes keepalivedeadline forward to lasttxsecs + UDIF_KEEPALIVE_INTERVAL_SECONDS.

Parameters

tun	The open tunnel
msg	[const] The message to send
nowsecs	The current UTC seconds (for timer updates)

Returns

Returns udif_error_none on success, udif_error_invalid_state if the tunnel is closing, udif_error_encode_failure on UDIF serialization failure, udif_error_internal on QSTP or socket failure.

udif_tunnel_send_keepalive()

UDIF_EXPORT_API udif_errors udif_tunnel_send_keepalive	(	udif_tunnel *	tun,
		uint64_t	nowsecs )

Force an immediate keepalive send, independent of the timer.

Useful for diagnostics and for probing a tunnel before issuing a latency-sensitive request.

Parameters

tun	The open tunnel
nowsecs	The current UTC seconds

Returns

Returns udif_error_none on success.

udif_tunnel_tick()

UDIF_EXPORT_API udif_errors udif_tunnel_tick	(	udif_tunnel *	tun,
		uint64_t	nowsecs )

Drive per-tunnel timers forward.

Should be called periodically (once per second is adequate) from the entity's event loop, for every tunnel in the tunnel table. Performs, in order:

1. If nowsecs >= keepalivedeadline, sends udif_msg_keepalive and advances keepalivedeadline by UDIF_KEEPALIVE_INTERVAL_SECONDS.
2. If nowsecs >= idledeadline, closes the tunnel (peer silent too long).
3. If rolepair == udif_rolepair_bc_bc and side == udif_tunnel_side_client and nowsecs >= ratchetdeadline, invokes qstp_send_symmetric_ratchet_request on qstpcns and advances ratchetdeadline by UDIF_RATCHET_INTERVAL_SECONDS with jitter in [-UDIF_RATCHET_JITTER_SECONDS, +UDIF_RATCHET_JITTER_SECONDS].

Idempotent within a single second. If a timer action fails fatally, the tunnel's closing flag is set and the caller should remove the tunnel from the table.

Parameters

tun	The tunnel
nowsecs	The current UTC seconds

Returns

Returns udif_error_none on success, or the error code from a failed timer action.

udif_tunnel_trigger_ratchet()

UDIF_EXPORT_API udif_errors udif_tunnel_trigger_ratchet	(	udif_tunnel *	tun,
		uint64_t	nowsecs )

Force an immediate ratchet trigger on a BC<->BC trunk.

Valid only when rolepair == udif_rolepair_bc_bc and side == udif_tunnel_side_client. Advances ratchetdeadline on success.

Parameters

tun	The open trunk tunnel
nowsecs	The current UTC seconds

Returns

Returns udif_error_none on success, udif_error_invalid_request if the role-pair or side is wrong for a manual ratchet trigger.