event.h File Reference

Canonical UDIF audit-event records. More...

#include "udif.h"
#include "mcelmanager.h"

Go to the source code of this file.

Data Structures
struct	udif_event_record
	Canonical UDIF audit-event record. More...

Macros
#define	UDIF_EVENT_CONTEXT_SIZE   32U
#define	UDIF_EVENT_RECORD_SIZE
	Encoded size, in bytes, of a canonical UDIF audit-event record.

Typedefs
typedef enum udif_event_classes	udif_event_classes
typedef enum udif_event_codes	udif_event_codes
typedef struct udif_event_record	udif_event_record

Enumerations
enum	udif_event_classes { udif_event_class_membership = 1U , udif_event_class_transaction = 2U , udif_event_class_registry = 3U , udif_event_class_error = 4U }
	UDIF audit-event ledger class identifiers. More...
enum	udif_event_codes {   udif_audit_event_none = 0x0000U , udif_audit_event_cert_enroll_request = 0x1000U , udif_audit_event_cert_enroll_response = 0x1001U , udif_audit_event_cert_revoke = 0x1002U ,   udif_audit_event_cert_suspend = 0x1003U , udif_audit_event_cert_resume = 0x1004U , udif_audit_event_cap_grant = 0x1005U , udif_audit_event_cap_revoke = 0x1006U ,   udif_audit_event_query_request = 0x2000U , udif_audit_event_query_response = 0x2001U , udif_audit_event_object_create = 0x3000U , udif_audit_event_object_transfer_request = 0x3001U ,   udif_audit_event_object_transfer_confirm = 0x3002U , udif_audit_event_registry_commit = 0x3003U , udif_audit_event_anchor_push = 0x4000U , udif_audit_event_anchor_ack = 0x4001U ,   udif_audit_event_treaty_propose = 0x5000U , udif_audit_event_treaty_cosign = 0x5001U , udif_audit_event_treaty_revoke = 0x5002U , udif_audit_event_treaty_query_forward = 0x5003U ,   udif_audit_event_treaty_query_response = 0x5004U , udif_audit_event_error_report = 0x6000U }
	UDIF audit-event operation identifiers. More...

Functions
UDIF_EXPORT_API void	udif_event_clear (udif_event_record *eventrec)
	Clear a UDIF audit-event record.
UDIF_EXPORT_API udif_errors	udif_event_create (udif_event_record *eventrec, udif_event_classes eventclass, udif_event_codes eventcode, const uint8_t *actorser, const uint8_t *subjectser, const uint8_t *contextid, uint64_t timestamp, const uint8_t *payload, size_t payloadlen)
	Create a canonical UDIF audit-event record.
UDIF_EXPORT_API udif_errors	udif_event_serialize (uint8_t *output, size_t outlen, const udif_event_record *eventrec)
	Serialize a UDIF audit-event record.
UDIF_EXPORT_API udif_errors	udif_event_log (udif_mcel_manager *mgr, udif_ledger_type ledger, udif_event_codes eventcode, const uint8_t *actorser, const uint8_t *subjectser, const uint8_t *contextid, uint64_t timestamp, const uint8_t *payload, size_t payloadlen)
	Create and append a UDIF audit event to an MCEL ledger.

Detailed Description

Canonical UDIF audit-event records.

This header defines the canonical audit-event record format used by UDIF membership, transaction, registry, and error ledgers. Audit events bind an event class, event code, actor serial, subject serial, context identifier, timestamp, payload digest, and payload length into a fixed-size record that can be committed to the MCEL-backed audit subsystem.

Event records store a digest of the event payload rather than the raw payload. This preserves auditability while limiting ledger exposure of sensitive or application-specific data.

Macro Definition Documentation

UDIF_EVENT_RECORD_SIZE

#define UDIF_EVENT_RECORD_SIZE

Value:

    (1U + 2U + UDIF_SERIAL_NUMBER_SIZE + UDIF_SERIAL_NUMBER_SIZE + \
    UDIF_EVENT_CONTEXT_SIZE + 8U + UDIF_CRYPTO_HASH_SIZE + 8U)

Encoded size, in bytes, of a canonical UDIF audit-event record.

The encoded event record contains the event class, event code, actor serial, subject serial, context identifier, timestamp, payload digest, and payload length. Integer fields are encoded in canonical little-endian form.

Enumeration Type Documentation

udif_event_classes

enum udif_event_classes

UDIF audit-event ledger class identifiers.

Event classes select the logical ledger category to which an audit event belongs. They are used to route canonical event records into the appropriate MCEL-backed audit stream.

Enumerator
udif_event_class_membership	Membership lifecycle and administrative events.
udif_event_class_transaction	Object transaction and transfer events.
udif_event_class_registry	Registry-root and registry-state commitment events.
udif_event_class_error	Error-report and fault-report events.

udif_event_codes

enum udif_event_codes

UDIF audit-event operation identifiers.

Event codes identify the specific protocol operation represented by an audit event. Codes are grouped by functional range: certificate and capability governance, query processing, object and registry operations, anchoring, treaty operation, and error reporting.

Enumerator
udif_audit_event_none	No event or uninitialized event code.
udif_audit_event_cert_enroll_request	Certificate enrollment request event.
udif_audit_event_cert_enroll_response	Certificate enrollment response event.
udif_audit_event_cert_revoke	Certificate revocation event.
udif_audit_event_cert_suspend	Certificate suspension event.
udif_audit_event_cert_resume	Certificate resumption event.
udif_audit_event_cap_grant	Capability grant event.
udif_audit_event_cap_revoke	Capability revocation event.
udif_audit_event_query_request	Query request event.
udif_audit_event_query_response	Query response event.
udif_audit_event_object_create	Object creation event.
udif_audit_event_object_transfer_request	Object transfer request event.
udif_audit_event_object_transfer_confirm	Object transfer confirmation event.
udif_audit_event_registry_commit	Registry-root commitment event.
udif_audit_event_anchor_push	Anchor push event from a child controller to its parent.
udif_audit_event_anchor_ack	Anchor acknowledgement event.
udif_audit_event_treaty_propose	Treaty proposal event.
udif_audit_event_treaty_cosign	Treaty co-signature event.
udif_audit_event_treaty_revoke	Treaty revocation event.
udif_audit_event_treaty_query_forward	Treaty query forwarding event.
udif_audit_event_treaty_query_response	Treaty query response event.
udif_audit_event_error_report	Signed or locally logged error-report event.

Function Documentation

udif_event_clear()

UDIF_EXPORT_API void udif_event_clear

(

udif_event_record *

eventrec

)

Clear a UDIF audit-event record.

This function clears all fields in an audit-event record and returns the structure to a zeroized state. It is used to dispose of temporary event records and to prevent stale event metadata from being reused.

Parameters

eventrec

[udif_event_record*] Pointer to the event record to clear.

udif_event_create()

UDIF_EXPORT_API udif_errors udif_event_create	(	udif_event_record *	eventrec,
		udif_event_classes	eventclass,
		udif_event_codes	eventcode,
		const uint8_t *	actorser,
		const uint8_t *	subjectser,
		const uint8_t *	contextid,
		uint64_t	timestamp,
		const uint8_t *	payload,
		size_t	payloadlen )

Create a canonical UDIF audit-event record.

This function initializes an audit-event record from the supplied event metadata and canonical payload. The function stores the event class, event code, actor serial, subject serial, context identifier, timestamp, payload length, and a cryptographic digest of the supplied payload.

The raw payload is not copied into the event record. Only its digest and length are retained, preserving audit integrity without storing the payload itself in the event structure.

Parameters

eventrec	[udif_event_record*] Pointer to the destination event record.
eventclass	[udif_event_classes] The logical audit ledger class for the event.
eventcode	[udif_event_codes] The protocol operation code represented by the event.
actorser	[const uint8_t*] Serial number of the actor or issuing entity.
subjectser	[const uint8_t*] Serial number of the subject affected by the event.
contextid	[const uint8_t*] Fixed-size context identifier associated with the event.
timestamp	[uint64_t] UTC event timestamp in seconds.
payload	[const uint8_t*] Pointer to the canonical payload to commit by digest.
payloadlen	[size_t] Length, in bytes, of the canonical payload.

Returns

Returns a udif_errors value indicating success or failure.

udif_event_log()

UDIF_EXPORT_API udif_errors udif_event_log	(	udif_mcel_manager *	mgr,
		udif_ledger_type	ledger,
		udif_event_codes	eventcode,
		const uint8_t *	actorser,
		const uint8_t *	subjectser,
		const uint8_t *	contextid,
		uint64_t	timestamp,
		const uint8_t *	payload,
		size_t	payloadlen )

Create and append a UDIF audit event to an MCEL ledger.

This function creates a canonical audit-event record from the supplied metadata and payload, serializes the event record, and appends it to the specified MCEL-backed UDIF ledger. The function is used by state-mutating handlers to ensure that protocol state changes are durably committed to the audit subsystem.

The function fails closed if a usable MCEL manager is not supplied. Callers that mutate protocol state after logging must treat a logging failure as a hard failure and must not allow unaudited state transitions to survive.

Parameters

mgr	[udif_mcel_manager*] Pointer to the MCEL manager used for audit logging.
ledger	[udif_ledger_type] Target UDIF ledger type.
eventcode	[udif_event_codes] Protocol operation code represented by the event.
actorser	[const uint8_t*] Serial number of the actor or issuing entity.
subjectser	[const uint8_t*] Serial number of the subject affected by the event.
contextid	[const uint8_t*] Fixed-size context identifier associated with the event.
timestamp	[uint64_t] UTC event timestamp in seconds.
payload	[const uint8_t*] Pointer to the canonical payload to commit by digest.
payloadlen	[size_t] Length, in bytes, of the canonical payload.

Returns

Returns a udif_errors value indicating success or failure.

udif_event_serialize()

UDIF_EXPORT_API udif_errors udif_event_serialize	(	uint8_t *	output,
		size_t	outlen,
		const udif_event_record *	eventrec )

Serialize a UDIF audit-event record.

This function serializes an audit-event record into its canonical binary representation. The serialized form uses fixed-size fields and little-endian encoding for integer values. The caller must provide an output buffer of at least UDIF_EVENT_RECORD_SIZE bytes.

Parameters

output	[uint8_t*] Pointer to the output buffer that receives the serialized event record.
outlen	[size_t] Length, in bytes, of the output buffer.
eventrec	[const udif_event_record*] Pointer to the event record to serialize.

Returns

Returns a udif_errors value indicating success or failure.