entity.h File Reference

Runtime state for a UDIF entity process (Root, BC, GC, or UA). More...

#include "udif.h"
#include "certificate.h"
#include "certstore.h"
#include "capstore.h"
#include "treatystore.h"
#include "mcelmanager.h"
#include "registry.h"
#include "tunnel.h"
#include "qstp.h"

Go to the source code of this file.

Data Structures
struct	udif_tunnel_table
	Flat fixed-capacity table of active tunnels. More...
struct	udif_anchor_sequence_state
	Expected anchor sequence for a child entity. More...
struct	udif_entity_registry_entry
	Runtime registry slot keyed by owner certificate serial. More...
struct	udif_entity_context
	Aggregate runtime state for a single UDIF entity process. More...
struct	udif_entity_config
	Initialization parameters for a UDIF entity process. More...

Macros
#define	UDIF_ENTITY_MAX_TUNNELS   64U
	Maximum number of simultaneous tunnels per entity in the prototype.
#define	UDIF_ENTITY_MAX_ANCHOR_STATES   64U
	Maximum number of tracked child anchor sequence states.
#define	UDIF_ENTITY_MAX_REGISTRIES   64U
	Maximum number of runtime UA registries tracked by one entity.

Typedefs
typedef UDIF_EXPORT_API struct udif_tunnel_table	udif_tunnel_table
typedef UDIF_EXPORT_API struct udif_anchor_sequence_state	udif_anchor_sequence_state
typedef UDIF_EXPORT_API struct udif_entity_registry_entry	udif_entity_registry_entry
typedef UDIF_EXPORT_API struct udif_entity_context	udif_entity_context
typedef UDIF_EXPORT_API struct udif_entity_config	udif_entity_config

Functions
UDIF_EXPORT_API udif_errors	udif_entity_anchor_expected_sequence (const udif_entity_context *ctx, const uint8_t *childser, uint64_t *expseq)
	Resolve the expected anchor sequence for a child.
UDIF_EXPORT_API udif_errors	udif_entity_anchor_commit_sequence (udif_entity_context *ctx, const uint8_t *childser, uint64_t acceptedseq)
	Commit an accepted anchor sequence for a child.
UDIF_EXPORT_API udif_errors	udif_entity_init (udif_entity_context *ctx, const udif_entity_config *cfg)
	Initialize an entity context from configuration.
UDIF_EXPORT_API void	udif_entity_dispose (udif_entity_context *ctx)
	Tear down an entity context.
UDIF_EXPORT_API udif_registry_state *	udif_entity_registry_find (udif_entity_context *ctx, const uint8_t *ownerser)
	Find a runtime registry by owner serial.
UDIF_EXPORT_API const udif_registry_state *	udif_entity_registry_find_const (const udif_entity_context *ctx, const uint8_t *ownerser)
	Find a runtime registry by owner serial.
UDIF_EXPORT_API udif_registry_state *	udif_entity_registry_get_or_create (udif_entity_context *ctx, const uint8_t *ownerser, size_t capacity)
	Resolve or create a runtime registry by owner serial.
UDIF_EXPORT_API void	udif_entity_registry_clear_all (udif_entity_context *ctx)
	Clear and dispose all runtime registries.
UDIF_EXPORT_API udif_tunnel *	udif_entity_add_tunnel (udif_entity_context *ctx, const udif_tunnel *tun)
	Insert a tunnel into the entity's tunnel table.
UDIF_EXPORT_API udif_tunnel *	udif_entity_find_tunnel (udif_entity_context *ctx, const uint8_t *peerserial, const uint8_t *treatyid)
	Find a tunnel by peer serial and optional treaty id.
UDIF_EXPORT_API udif_tunnel *	udif_entity_find_tunnel_by_qstp (udif_entity_context *ctx, const qstp_connection_state *qstpcns)
	Look up the tunnel associated with a QSTP connection.
UDIF_EXPORT_API void	udif_entity_remove_tunnel (udif_entity_context *ctx, udif_tunnel *tun, bool notify)
	Remove a tunnel from the table, closing it if still open.
UDIF_EXPORT_API void	udif_entity_tick_tunnels (udif_entity_context *ctx, uint64_t nowsecs)
	Drive timers for every tunnel in the table.
UDIF_EXPORT_API udif_tunnel *	udif_tunneltable_add (udif_tunnel_table *table, const udif_tunnel *tun)
	Add a tunnel — tunnel-table variant.
UDIF_EXPORT_API udif_tunnel *	udif_tunneltable_find (udif_tunnel_table *table, const uint8_t *peerserial, const uint8_t *treatyid)
	Find a tunnel by peer serial — tunnel-table variant.
UDIF_EXPORT_API udif_tunnel *	udif_tunneltable_find_by_qstp (udif_tunnel_table *table, const qstp_connection_state *qstpcns)
	Find a tunnel by QSTP connection — tunnel-table variant.
UDIF_EXPORT_API void	udif_tunneltable_remove (udif_tunnel_table *table, udif_tunnel *tun, bool notify)
	Remove a tunnel — tunnel-table variant.
UDIF_EXPORT_API void	udif_tunneltable_tick (udif_tunnel_table *table, uint64_t nowsecs)
	Tick all tunnels — tunnel-table variant.

Detailed Description

Runtime state for a UDIF entity process (Root, BC, GC, or UA).

A udif_entity_context is the single in-memory representation of everything a running entity needs to serve or issue UDIF operations: its own UDIF certificate and signing key, its QSTP certificate and signing key (the two-layer certificate model from Phase 5), the trust anchors it validates against, the udif_mcel_manager that holds the three ledgers and storage backend, and the tunnel table enumerating active QSTP sessions.

Every handler receives a pointer to this structure; the dispatcher uses the role field to decide which messages the entity is allowed to accept. Role is expressed using the existing udif_roles enum defined in udif.h, with the following mapping to the UDIF specification:

udif_role_root - Root Authority udif_role_ugc - Group Controller udif_role_ubc - Branch Controller udif_role_client - User Agent

The prototype is single-threaded from the entity's perspective. QSTP's receive thread delivers payloads via a callback that marshals them through the dispatcher; send operations happen on the main thread. Implementations that require concurrent access must add their own synchronization.

Function Documentation

udif_entity_add_tunnel()

UDIF_EXPORT_API udif_tunnel * udif_entity_add_tunnel	(	udif_entity_context *	ctx,
		const udif_tunnel *	tun )

Insert a tunnel into the entity's tunnel table.

The tunnel's storage is copied into the table entry.

Parameters

ctx	The entity context
tun	[const] The fully initialized tunnel

Returns

Returns a pointer to the stored tunnel entry on success, NULL if the table is full.

udif_entity_anchor_commit_sequence()

UDIF_EXPORT_API udif_errors udif_entity_anchor_commit_sequence	(	udif_entity_context *	ctx,
		const uint8_t *	childser,
		uint64_t	acceptedseq )

Commit an accepted anchor sequence for a child.

Stores the next expected sequence after a verified anchor has been accepted.

Parameters

ctx	The entity context.
childser	[const] The child certificate serial.
acceptedseq	The accepted sequence value.

Returns

Returns udif_error_none on success.

udif_entity_anchor_expected_sequence()

UDIF_EXPORT_API udif_errors udif_entity_anchor_expected_sequence	(	const udif_entity_context *	ctx,
		const uint8_t *	childser,
		uint64_t *	expseq )

Resolve the expected anchor sequence for a child.

Unknown children are treated as genesis children and therefore expect sequence 0.

Parameters

ctx	The entity context.
childser	[const] The child certificate serial.
expseq	The output expected sequence.

Returns

Returns udif_error_none on success.

udif_entity_dispose()

UDIF_EXPORT_API void udif_entity_dispose

(

udif_entity_context *

ctx

)

Tear down an entity context.

Closes all tunnels, disposes the MCEL manager, and zeroizes private key material. Idempotent. Safe to call on a zero-initialized context.

Parameters

ctx	The context (may be NULL)

udif_entity_find_tunnel()

UDIF_EXPORT_API udif_tunnel * udif_entity_find_tunnel	(	udif_entity_context *	ctx,
		const uint8_t *	peerserial,
		const uint8_t *	treatyid )

Find a tunnel by peer serial and optional treaty id.

When treatyid is NULL, matches the first non-treaty tunnel with the given peer serial. When treatyid is non-NULL, matches only treaty tunnels with the given treaty id.

Parameters

ctx	The entity context
peerserial	[const] The 16-byte peer certificate serial
treatyid	[const] The 16-byte treaty id (may be NULL)

Returns

Returns a pointer to the matching tunnel, or NULL if none.

udif_entity_find_tunnel_by_qstp()

UDIF_EXPORT_API udif_tunnel * udif_entity_find_tunnel_by_qstp	(	udif_entity_context *	ctx,
		const qstp_connection_state *	qstpcns )

Look up the tunnel associated with a QSTP connection.

Used by QSTP receive callbacks to resolve the inbound connection back to the UDIF tunnel record.

Parameters

ctx	The entity context
qstpcns	The QSTP connection

Returns

Returns a pointer to the matching tunnel, or NULL if none.

udif_entity_init()

UDIF_EXPORT_API udif_errors udif_entity_init	(	udif_entity_context *	ctx,
		const udif_entity_config *	cfg )

Initialize an entity context from configuration.

Initializes the MCEL manager (for roles that keep ledgers), copies certificates and keys, clears the tunnel table, and sets nextanchorsecs according to role and profile. Returns an error if any resource cannot be opened.

Parameters

ctx	The output context
cfg	[const] The configuration

Returns

Returns udif_error_none on success, udif_error_invalid_input on bad arguments, udif_error_internal on MCEL or storage failure.

udif_entity_registry_clear_all()

UDIF_EXPORT_API void udif_entity_registry_clear_all

(

udif_entity_context *

ctx

)

Clear and dispose all runtime registries.

Parameters

ctx	The entity context.

udif_entity_registry_find()

UDIF_EXPORT_API udif_registry_state * udif_entity_registry_find	(	udif_entity_context *	ctx,
		const uint8_t *	ownerser )

Find a runtime registry by owner serial.

Parameters

ctx	The entity context.
ownerser	[const] The owner certificate serial.

Returns

Returns the registry on success, or NULL if no registry exists.

udif_entity_registry_find_const()

UDIF_EXPORT_API const udif_registry_state * udif_entity_registry_find_const	(	const udif_entity_context *	ctx,
		const uint8_t *	ownerser )

Find a runtime registry by owner serial.

Parameters

ctx	[const] The entity context.
ownerser	[const] The owner certificate serial.

Returns

Returns the registry on success, or NULL if no registry exists.

udif_entity_registry_get_or_create()

UDIF_EXPORT_API udif_registry_state * udif_entity_registry_get_or_create	(	udif_entity_context *	ctx,
		const uint8_t *	ownerser,
		size_t	capacity )

Resolve or create a runtime registry by owner serial.

Parameters

ctx	The entity context.
ownerser	[const] The owner certificate serial.
capacity	Initial capacity when a new registry is created.

Returns

Returns the registry on success, or NULL on failure.

udif_entity_remove_tunnel()

UDIF_EXPORT_API void udif_entity_remove_tunnel	(	udif_entity_context *	ctx,
		udif_tunnel *	tun,
		bool	notify )

Remove a tunnel from the table, closing it if still open.

Parameters

ctx	The entity context
tun	The tunnel entry (previously returned from add/find)
notify	If true, instructs QSTP to notify the remote peer of the close

udif_entity_tick_tunnels()

UDIF_EXPORT_API void udif_entity_tick_tunnels	(	udif_entity_context *	ctx,
		uint64_t	nowsecs )

Drive timers for every tunnel in the table.

Calls udif_tunnel_tick on each occupied entry; removes any that fail or that have exceeded idle teardown. Intended to be invoked once per second from the main event loop.

Parameters

ctx	The entity context
nowsecs	The current UTC seconds

udif_tunneltable_add()

UDIF_EXPORT_API udif_tunnel * udif_tunneltable_add	(	udif_tunnel_table *	table,
		const udif_tunnel *	tun )

Add a tunnel — tunnel-table variant.

See also

udif_entity_add_tunnel

udif_tunneltable_find()

UDIF_EXPORT_API udif_tunnel * udif_tunneltable_find	(	udif_tunnel_table *	table,
		const uint8_t *	peerserial,
		const uint8_t *	treatyid )

Find a tunnel by peer serial — tunnel-table variant.

See also

udif_entity_find_tunnel

udif_tunneltable_find_by_qstp()

UDIF_EXPORT_API udif_tunnel * udif_tunneltable_find_by_qstp	(	udif_tunnel_table *	table,
		const qstp_connection_state *	qstpcns )

Find a tunnel by QSTP connection — tunnel-table variant.

See also

udif_entity_find_tunnel_by_qstp

udif_tunneltable_remove()

UDIF_EXPORT_API void udif_tunneltable_remove	(	udif_tunnel_table *	table,
		udif_tunnel *	tun,
		bool	notify )

Remove a tunnel — tunnel-table variant.

See also

udif_entity_remove_tunnel

udif_tunneltable_tick()

UDIF_EXPORT_API void udif_tunneltable_tick	(	udif_tunnel_table *	table,
		uint64_t	nowsecs )

Tick all tunnels — tunnel-table variant.

See also

udif_entity_tick_tunnels