Runtime capability-token store. More...

#include "udif.h"
#include "capability.h"

Data Structures
struct	udif_capstore_entry
	Single stored capability-token entry. More...
struct	udif_capstore
	Fixed-capacity capability-token table. More...

Macros
#define	UDIF_CAPSTORE_CAPACITY 128U
	Maximum number of capability tokens retained in one entity context.

Typedefs
typedef UDIF_EXPORT_API enum udif_capstore_status	udif_capstore_status
typedef UDIF_EXPORT_API struct udif_capstore_entry	udif_capstore_entry
typedef UDIF_EXPORT_API struct udif_capstore	udif_capstore

Enumerations
enum	udif_capstore_status { udif_capstore_status_unknown = 0x00U , udif_capstore_status_active = 0x01U , udif_capstore_status_revoked = 0x02U , udif_capstore_status_expired = 0x03U }
	Runtime status for a stored capability token. More...

Functions
UDIF_EXPORT_API void	udif_capstore_initialize (udif_capstore *store)
	Initialize a capability-token store.
UDIF_EXPORT_API void	udif_capstore_clear (udif_capstore *store)
	Clear a capability-token store.
UDIF_EXPORT_API udif_errors	udif_capstore_add (udif_capstore store, const udif_capability capability)
	Add a capability token to the store without external verification.
UDIF_EXPORT_API udif_errors	udif_capstore_add_verified (udif_capstore store, const udif_capability capability, const uint8_t *issuerkey, uint64_t nowsecs)
	Verify and add a capability token to the store.
UDIF_EXPORT_API const udif_capability *	udif_capstore_find (const udif_capstore store, const uint8_t digest)
	Find an active capability token by digest.
UDIF_EXPORT_API const udif_capability *	udif_capstore_find_any (const udif_capstore store, const uint8_t digest)
	Find a capability token by digest regardless of runtime status.
UDIF_EXPORT_API udif_capstore_status	udif_capstore_get_status (const udif_capstore store, const uint8_t digest, uint64_t nowsecs)
	Get the runtime status of a stored capability token.
UDIF_EXPORT_API bool	udif_capstore_set_status (udif_capstore store, const uint8_t digest, udif_capstore_status status)
	Set the runtime status of a stored capability token.
UDIF_EXPORT_API bool	udif_capstore_remove (udif_capstore store, const uint8_t digest)
	Remove a capability token from the store.

Detailed Description

Runtime capability-token store.

The capability store is a fixed-capacity, deterministic lookup table keyed by the canonical capability digest. It is used by the policy engine to resolve the capability reference carried by a query or administrative request before an authorization decision is made.

Enumeration Type Documentation

◆ udif_capstore_status

enum udif_capstore_status

Runtime status for a stored capability token.

Enumerator
udif_capstore_status_unknown	No matching token or invalid status
udif_capstore_status_active	Token is active and usable
udif_capstore_status_revoked	Token has been revoked
udif_capstore_status_expired	Token is expired

Function Documentation

◆ udif_capstore_add()

UDIF_EXPORT_API udif_errors udif_capstore_add	(	udif_capstore *	store,
		const udif_capability *	capability )

Add a capability token to the store without external verification.

This function inserts the supplied capability token into the store using its canonical capability digest as the lookup key. The inserted entry is marked active. If a token with the same digest is already present, the existing entry may be replaced or rejected according to the implementation policy.

This function does not validate the capability tag, issuer key, expiry time, or policy constraints. Callers that accept externally supplied tokens should use udif_capstore_add_verified instead.

Parameters

store	[udif_capstore*] Pointer to the capability store.
capability	[const udif_capability*] Pointer to the capability token to add.

Returns: Returns a udif_errors value indicating success or failure.

◆ udif_capstore_add_verified()

UDIF_EXPORT_API udif_errors udif_capstore_add_verified	(	udif_capstore *	store,
		const udif_capability *	capability,
		const uint8_t *	issuerkey,
		uint64_t	nowsecs )

Verify and add a capability token to the store.

This function verifies the supplied capability token before inserting it into the store. Verification includes recomputing the capability digest, validating the issuer-authenticated KMAC tag with the supplied issuer key, checking expiry against the supplied time value, and rejecting malformed or unauthorized capability encodings according to the capability-token rules.

On successful verification, the capability is inserted into the store and marked active. If verification fails, the store is not updated.

Parameters

store	[udif_capstore*] Pointer to the capability store.
capability	[const udif_capability*] Pointer to the capability token to verify and add.
issuerkey	[const uint8_t*] Pointer to the issuer capability-authentication key.
nowsecs	[uint64_t] Current UTC time in seconds, used for expiry validation.

Returns: Returns a udif_errors value indicating success or failure.

◆ udif_capstore_clear()

UDIF_EXPORT_API void udif_capstore_clear ( udif_capstore * store )

Clear a capability-token store.

This function securely clears the stored capability entries and resets the store to an empty state. It is used when an entity context is disposed, reset, or reinitialized so that stale capability tokens are not retained.

Parameters

store [udif_capstore*] Pointer to the capability store to clear.

◆ udif_capstore_find()

UDIF_EXPORT_API const udif_capability * udif_capstore_find	(	const udif_capstore *	store,
		const uint8_t *	digest )

Find an active capability token by digest.

This function searches the store for a capability token whose canonical digest matches the supplied digest. Only active, usable entries are returned; revoked, expired, unknown, or unused entries are not returned.

Parameters

store	[const udif_capstore*] Pointer to the capability store.
digest	[const uint8_t*] Pointer to the capability digest to search for.

Returns: Returns a pointer to the matching active capability token, or NULL if no active match is found.

◆ udif_capstore_find_any()

UDIF_EXPORT_API const udif_capability * udif_capstore_find_any	(	const udif_capstore *	store,
		const uint8_t *	digest )

Find a capability token by digest regardless of runtime status.

This function searches the store for a capability token whose canonical digest matches the supplied digest and returns the matching token even if the stored entry is revoked or expired. It is intended for administrative, revocation, diagnostic, or audit paths that must locate a token independently of its current usability.

Parameters

store	[const udif_capstore*] Pointer to the capability store.
digest	[const uint8_t*] Pointer to the capability digest to search for.

Returns: Returns a pointer to the matching capability token, or NULL if no matching token is found.

◆ udif_capstore_get_status()

UDIF_EXPORT_API udif_capstore_status udif_capstore_get_status	(	const udif_capstore *	store,
		const uint8_t *	digest,
		uint64_t	nowsecs )

Get the runtime status of a stored capability token.

This function locates a capability token by digest and returns its effective runtime status. If the token is active but its validity interval has expired relative to nowsecs, the function reports the token as expired. If the token is not present, the function returns udif_capstore_status_unknown.

Parameters

store	[const udif_capstore*] Pointer to the capability store.
digest	[const uint8_t*] Pointer to the capability digest to query.
nowsecs	[uint64_t] Current UTC time in seconds, used for expiry evaluation.

Returns: Returns the effective udif_capstore_status for the matching token.

◆ udif_capstore_initialize()

UDIF_EXPORT_API void udif_capstore_initialize ( udif_capstore * store )

Initialize a capability-token store.

This function clears the capability store and places it in an empty, deterministic state. All entries are marked unused, all runtime status fields are reset, and the active entry count is set to zero.

Parameters

store [udif_capstore*] Pointer to the capability store to initialize.

◆ udif_capstore_remove()

UDIF_EXPORT_API bool udif_capstore_remove	(	udif_capstore *	store,
		const uint8_t *	digest )

Remove a capability token from the store.

This function locates a capability token by digest and removes the entry from the store. The removed entry is cleared and marked unused so that it can no longer authorize policy checks or administrative operations.

Parameters

store	[udif_capstore*] Pointer to the capability store.
digest	[const uint8_t*] Pointer to the capability digest identifying the token to remove.

Returns: Returns true if a matching entry was found and removed; otherwise returns false.

◆ udif_capstore_set_status()

UDIF_EXPORT_API bool udif_capstore_set_status	(	udif_capstore *	store,
		const uint8_t *	digest,
		udif_capstore_status	status )

Set the runtime status of a stored capability token.

This function locates a capability token by digest and updates its runtime status. It is used to revoke, expire, reactivate, or otherwise administratively change the local status of a stored capability token, subject to the implementation's status-transition rules.

Parameters

store	[udif_capstore*] Pointer to the capability store.
digest	[const uint8_t*] Pointer to the capability digest identifying the token.
status	[udif_capstore_status] New runtime status to assign.

Returns: Returns true if the matching entry was found and updated; otherwise returns false.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ udif_capstore_status

Function Documentation

◆ udif_capstore_add()

◆ udif_capstore_add_verified()

◆ udif_capstore_clear()

◆ udif_capstore_find()

◆ udif_capstore_find_any()

◆ udif_capstore_get_status()

◆ udif_capstore_initialize()

◆ udif_capstore_remove()

◆ udif_capstore_set_status()