message.h File Reference

UDIF application-layer message framing. More...

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

Go to the source code of this file.

Data Structures
struct	udif_message
	A single UDIF application message. More...

Macros
#define	UDIF_MESSAGE_HEADER_SIZE   6U
	Fixed overhead of the wire frame: msgtype (1) + reserved (1) + payloadlen (4).
#define	UDIF_MESSAGE_PAYLOAD_MAX   (QSTP_PACKET_MESSAGE_MAX - QSTP_MACTAG_SIZE - 26U - UDIF_MESSAGE_HEADER_SIZE)
	Maximum UDIF message payload length in bytes.
#define	UDIF_MESSAGE_VERSION   1U
	Current UDIF frame version; embedded in the reserved byte.

Typedefs
typedef enum udif_message_type	udif_message_type
typedef UDIF_EXPORT_API struct udif_message	udif_message

Enumerations
enum	udif_message_type {   udif_msg_none = 0x00U , udif_msg_keepalive = 0x01U , udif_msg_cert_enroll_req = 0x10U , udif_msg_cert_enroll_resp = 0x11U ,   udif_msg_cert_revoke = 0x12U , udif_msg_cert_suspend = 0x13U , udif_msg_cert_resume = 0x14U , udif_msg_cap_grant = 0x15U ,   udif_msg_cap_revoke = 0x16U , udif_msg_query_req = 0x20U , udif_msg_query_resp = 0x21U , udif_msg_object_create = 0x30U ,   udif_msg_object_transfer_req = 0x31U , udif_msg_object_transfer_confirm = 0x32U , udif_msg_registry_commit = 0x33U , udif_msg_anchor_push = 0x40U ,   udif_msg_anchor_ack = 0x41U , udif_msg_treaty_propose = 0x50U , udif_msg_treaty_cosign = 0x51U , udif_msg_treaty_revoke = 0x52U ,   udif_msg_treaty_query_fwd = 0x53U , udif_msg_treaty_query_resp = 0x54U , udif_msg_error_report = 0x60U }
	Canonical UDIF message type codes. More...

Functions
UDIF_EXPORT_API udif_errors	udif_message_init (udif_message *msg, udif_message_type msgtype, const uint8_t *payload, uint32_t payloadlen)
	Initialize a message with a given type and payload.
UDIF_EXPORT_API void	udif_message_dispose (udif_message *msg)
	Release allocated storage and zero the message.
UDIF_EXPORT_API udif_errors	udif_message_encode (uint8_t *output, size_t outlen, const udif_message *msg, size_t *written)
	Encode a message into its canonical wire form.
UDIF_EXPORT_API udif_errors	udif_message_decode (udif_message *msg, const uint8_t *input, size_t inplen, size_t *consumed)
	Decode a canonical wire message.
UDIF_EXPORT_API size_t	udif_message_encoded_size (const udif_message *msg)
	Compute the total encoded wire size of a message.
UDIF_EXPORT_API const char *	udif_message_type_name (udif_message_type msgtype)
	Return a human-readable name for a message type.

Detailed Description

UDIF application-layer message framing.

Defines the canonical message type taxonomy and the application wire frame carried inside a UDIF tunnel record. QSTP provides cryptographic confidentiality and integrity for the complete UDIF inner record:

UDIF tunnel header || UDIF message frame

The UDIF tunnel layer prepends the header before QSTP sealing. UDIF messages carry only protocol semantics after that tunnel record header. Correlation, where needed, is carried inside the canonical payload of specific message types (e.g. queryid inside a query, treatyid inside a treaty exchange).

Keepalives, which were removed from QSTP to reduce attack surface, live here as udif_msg_keepalive. Both sides of a tunnel maintain independent keepalive timers; any tunnel with no TX activity within the keepalive interval emits an empty keepalive frame.

Macro Definition Documentation

UDIF_MESSAGE_PAYLOAD_MAX

#define UDIF_MESSAGE_PAYLOAD_MAX   (QSTP_PACKET_MESSAGE_MAX - QSTP_MACTAG_SIZE - 26U - UDIF_MESSAGE_HEADER_SIZE)

Maximum UDIF message payload length in bytes.

Derived from QSTP's per-packet message cap minus the QSTP tag overhead, the 26-byte UDIF tunnel record header, and the UDIF frame header. Every UDIF message fits inside a single QSTP packet; no fragmentation is performed at the UDIF layer.

At every currently-defined UDIF cryptographic suite (including the SPHINCS+/McEliece configurations with SPHINCS+-S5 signatures), the largest message type (a two-signature treaty cosign or object transfer confirmation) fits within this cap with margin to spare. A future suite that introduces larger signatures would surface as a clean udif_error_encode_failure at integration time.

Enumeration Type Documentation

udif_message_type

enum udif_message_type

Canonical UDIF message type codes.

Each code maps to exactly one handler on the receiving side. The high nibble groups related operations for readability; values are one byte on the wire.

Enumerator
udif_msg_none	Reserved; must not appear on the wire
udif_msg_keepalive	Application-level keepalive; empty payload
udif_msg_cert_enroll_req	Child CSR to parent
udif_msg_cert_enroll_resp	Parent-signed certificate to child
udif_msg_cert_revoke	Parent notifies revocation
udif_msg_cert_suspend	Parent notifies suspension
udif_msg_cert_resume	Parent notifies resumption
udif_msg_cap_grant	Parent grants a capability token
udif_msg_cap_revoke	Parent revokes a capability token
udif_msg_query_req	Predicate query; inner type code selects family
udif_msg_query_resp	Verdict and optional proof
udif_msg_object_create	UA creates an object in its registry
udif_msg_object_transfer_req	Sender UA requests transfer to receiver
udif_msg_object_transfer_confirm	Receiver UA co-signs transfer
udif_msg_registry_commit	Registry root update notification
udif_msg_anchor_push	Child anchor record to parent
udif_msg_anchor_ack	Parent acknowledgement
udif_msg_treaty_propose	Proposer sends treaty terms
udif_msg_treaty_cosign	Peer co-signs treaty
udif_msg_treaty_revoke	Either party revokes an active treaty
udif_msg_treaty_query_fwd	Cross-domain query forwarded under treaty
udif_msg_treaty_query_resp	Cross-domain query response
udif_msg_error_report	DENY, NOT_OWNER, etc.

Function Documentation

udif_message_decode()

UDIF_EXPORT_API udif_errors udif_message_decode	(	udif_message *	msg,
		const uint8_t *	input,
		size_t	inplen,
		size_t *	consumed )

Decode a canonical wire message.

Allocates a payload buffer owned by msg on success; caller must dispose via udif_message_dispose.

Parameters

msg	The output message
input	[const] The source buffer containing a complete encoded message
inplen	The size of the source buffer in bytes
consumed	The number of bytes consumed from input on success (may be NULL)

Returns

Returns udif_error_none on success, udif_error_decode_failure on malformed input or unsupported version, udif_error_internal on allocation failure.

udif_message_dispose()

UDIF_EXPORT_API void udif_message_dispose

(

udif_message *

msg

)

Release allocated storage and zero the message.

Safe to call on a zero-initialized or already-disposed message.

Parameters

msg	The message to dispose (may be NULL)

udif_message_encode()

UDIF_EXPORT_API udif_errors udif_message_encode	(	uint8_t *	output,
		size_t	outlen,
		const udif_message *	msg,
		size_t *	written )

Encode a message into its canonical wire form.

Output layout (little-endian multi-byte fields): offset 0: msgtype (uint8) offset 1: version (uint8, UDIF_MESSAGE_VERSION) offset 2: payloadlen (uint32) offset 6: payload (payloadlen bytes)

Parameters

output	The destination buffer
outlen	The size of the destination buffer in bytes
msg	[const] The message to encode
written	The number of bytes written on success (may be NULL)

Returns

Returns udif_error_none on success, udif_error_encode_failure if the destination buffer is too small, udif_error_invalid_input on bad arguments.

udif_message_encoded_size()

UDIF_EXPORT_API size_t udif_message_encoded_size

(

const udif_message *

msg

)

Compute the total encoded wire size of a message.

Parameters

msg	[const] The message

Returns

Returns UDIF_MESSAGE_HEADER_SIZE + msg->payloadlen, or 0 if msg is NULL.

udif_message_init()

UDIF_EXPORT_API udif_errors udif_message_init	(	udif_message *	msg,
		udif_message_type	msgtype,
		const uint8_t *	payload,
		uint32_t	payloadlen )

Initialize a message with a given type and payload.

Copies payloadlen bytes from payload into a newly allocated buffer owned by the message. Passing payload == NULL with payloadlen == 0 produces an empty message.

Parameters

msg	The output message
msgtype	The message type code
payload	[const] The source payload bytes (may be NULL if payloadlen == 0)
payloadlen	The length of the source payload in bytes

Returns

Returns udif_error_none on success, udif_error_invalid_input on bad arguments, udif_error_encode_failure if payloadlen exceeds UDIF_MESSAGE_PAYLOAD_MAX, udif_error_internal on allocation failure.

udif_message_type_name()

UDIF_EXPORT_API const char * udif_message_type_name

(

udif_message_type

msgtype

)

Return a human-readable name for a message type.

Parameters

msgtype

The type code

Returns

Returns a static string; never NULL (unknown codes return "unknown").