logging.h File Reference

UDIF audit logging operations. More...

#include "udif.h"

Go to the source code of this file.

Data Structures
struct	udif_logging_entry
	Audit log entry. More...
struct	udif_logging_state
	Log state structure. More...

Macros
#define	UDIF_LOG_DEFAULT_CAPACITY   1024U
	Default log capacity.
#define	UDIF_LOG_MAX_CAPACITY   10485760U
	Maximum log capacity.
#define	UDIF_LOG_MAX_DATA_SIZE   65535U

Typedefs
typedef UDIF_EXPORT_API enum udif_logging_type	udif_logging_type
typedef UDIF_EXPORT_API struct udif_logging_entry	udif_logging_entry
typedef UDIF_EXPORT_API struct udif_logging_state	udif_logging_state

Enumerations
enum	udif_logging_type { udif_logging_membership = 0 , udif_logging_transaction = 1 }
	Log types. More...

Functions
UDIF_EXPORT_API udif_errors	udif_logging_initialize (udif_logging_state *log, udif_logging_type logtype, const uint8_t *ownerser, size_t capacity)
	Initialize a log.
UDIF_EXPORT_API udif_errors	udif_logging_append (udif_logging_state *log, uint16_t eventcode, const uint8_t *subjser, uint64_t timestamp, const uint8_t *data, size_t datalen, const uint8_t *sigkey, bool(*rng_generate)(uint8_t *, size_t))
	Append an entry to the log.
UDIF_EXPORT_API udif_errors	udif_logging_compute_root (uint8_t *root, const udif_logging_state *log, size_t fromseq, size_t toseq)
	Compute log Merkle root.
UDIF_EXPORT_API udif_errors	udif_logging_generate_proof (uint8_t *proof, size_t *prooflen, const udif_logging_state *log, size_t entryseq)
	Generate log inclusion proof.
UDIF_EXPORT_API bool	udif_logging_verify_proof (const uint8_t *proof, size_t prooflen, const uint8_t *root, const uint8_t *entrydigest)
	Verify log inclusion proof.
UDIF_EXPORT_API udif_errors	udif_logging_get_entry (udif_logging_entry *entry, const udif_logging_state *log, size_t seq)
	Get log entry at sequence.
UDIF_EXPORT_API size_t	udif_logging_get_count (const udif_logging_state *log)
	Get log entry count.
UDIF_EXPORT_API bool	udif_logging_verify_entry (const udif_logging_entry *entry, const uint8_t *verkey)
	Verify log entry signature.
UDIF_EXPORT_API void	udif_logging_compute_entry_digest (uint8_t *digest, const udif_logging_entry *entry)
	Compute log entry digest.
UDIF_EXPORT_API udif_errors	udif_logging_resize (udif_logging_state *log, size_t capacity)
	Resize log capacity.
UDIF_EXPORT_API void	udif_logging_dispose (udif_logging_state *log)
	Dispose of a log.
UDIF_EXPORT_API void	udif_logging_clear (udif_logging_state *log)
	Clear a log.
UDIF_EXPORT_API void	udif_logging_entry_clear (udif_logging_entry *entry)
	Clear a log entry.
UDIF_EXPORT_API udif_errors	udif_logging_entry_serialize (uint8_t *output, size_t *outlen, const udif_logging_entry *entry)
	Serialize a log entry.
UDIF_EXPORT_API udif_errors	udif_logging_entry_deserialize (udif_logging_entry *entry, const uint8_t *input, size_t inlen)
	Deserialize a log entry.
UDIF_EXPORT_API bool	udif_logging_is_empty (const udif_logging_state *log)
	Check if log is empty.
UDIF_EXPORT_API bool	udif_logging_is_full (const udif_logging_state *log)
	Check if log is full.
UDIF_EXPORT_API udif_errors	udif_logging_get_statistics (const udif_logging_state *log, size_t *count, size_t *capacity, uint8_t *root)
	Get log statistics.

Detailed Description

UDIF audit logging operations.

This module implements tamper-evident audit logs for UDIF. Two types of logs are maintained:

• Membership Log: Enrollment, suspension, revocation events
• Transaction Log: Object transfers and state changes

Logs are append-only, cryptographically signed, and organized as Merkle trees for efficient proof generation. Log roots are periodically committed via Anchor Records.

Log Entry Structure:

• Event code
• Subject serial
• Timestamp
• Event data (TLV encoded)
• Entry digest
• Signature

Enumeration Type Documentation

udif_logging_type

enum udif_logging_type

Log types.

Enumerator
udif_logging_membership	Membership events log
udif_logging_transaction	Transaction events log

Function Documentation

udif_logging_append()

UDIF_EXPORT_API udif_errors udif_logging_append	(	udif_logging_state *	log,
		uint16_t	eventcode,
		const uint8_t *	subjser,
		uint64_t	timestamp,
		const uint8_t *	data,
		size_t	datalen,
		const uint8_t *	sigkey,
		bool(*	rng_generate )(uint8_t *, size_t) )

Append an entry to the log.

Adds a new event to the log with signature.

Parameters

log	The log state
eventcode	The event type code
subjser	[const] The subject entity serial (16 bytes)
timestamp	The event timestamp (UTC seconds)
data	[const] The event data (TLV encoded, can be NULL)
datalen	The data length
sigkey	[const] The signer's private key
rng_generate	Random number generator function

Returns

Returns udif_error_none on success

udif_logging_clear()

UDIF_EXPORT_API void udif_logging_clear

(

udif_logging_state *

log

)

Clear a log.

Removes all entries but keeps the structure allocated.

Parameters

log	The log state

udif_logging_compute_entry_digest()

UDIF_EXPORT_API void udif_logging_compute_entry_digest	(	uint8_t *	digest,
		const udif_logging_entry *	entry )

Compute log entry digest.

Calculates the canonical digest of a log entry.

Parameters

digest	The output digest (32 bytes)
entry	[const] The log entry

udif_logging_compute_root()

UDIF_EXPORT_API udif_errors udif_logging_compute_root	(	uint8_t *	root,
		const udif_logging_state *	log,
		size_t	fromseq,
		size_t	toseq )

Compute log Merkle root.

Calculates the Merkle root of all log entries in a range.

Parameters

root	The output Merkle root (32 bytes)
log	[const] The log state
fromseq	The starting sequence (0-based index)
toseq	The ending sequence (inclusive)

Returns

Returns error none on success

udif_logging_dispose()

UDIF_EXPORT_API void udif_logging_dispose

(

udif_logging_state *

log

)

Dispose of a log.

Frees all resources and clears the log state.

Parameters

log	The log state

udif_logging_entry_clear()

UDIF_EXPORT_API void udif_logging_entry_clear

(

udif_logging_entry *

entry

)

Clear a log entry.

Zeros out a log entry structure.

Parameters

entry

The log entry to clear

udif_logging_entry_deserialize()

UDIF_EXPORT_API udif_errors udif_logging_entry_deserialize	(	udif_logging_entry *	entry,
		const uint8_t *	input,
		size_t	inlen )

Deserialize a log entry.

Decodes a log entry from canonical format.

Parameters

entry	The output log entry
input	[const] The input buffer
inlen	The input buffer length

Returns

Returns udif_error_none on success

udif_logging_entry_serialize()

UDIF_EXPORT_API udif_errors udif_logging_entry_serialize	(	uint8_t *	output,
		size_t *	outlen,
		const udif_logging_entry *	entry )

Serialize a log entry.

Encodes a log entry to canonical format.

Parameters

output	The output buffer
outlen	Pointer to output length (in: buffer size, out: bytes written)
entry	[const] The log entry to serialize

Returns

Returns udif_error_none on success

udif_logging_generate_proof()

UDIF_EXPORT_API udif_errors udif_logging_generate_proof	(	uint8_t *	proof,
		size_t *	prooflen,
		const udif_logging_state *	log,
		size_t	entryseq )

Generate log inclusion proof.

Creates a Merkle proof that an entry exists in the log.

Parameters

proof	The output proof buffer
prooflen	Pointer to proof length (in: buffer size, out: bytes written)
log	[const] The log state
entryseq	The entry sequence number (0-based index)

Returns

Returns udif_error_none on success

udif_logging_get_count()

UDIF_EXPORT_API size_t udif_logging_get_count

(

const udif_logging_state *

log

)

Get log entry count.

Returns the number of entries in the log.

Parameters

log	[const] The log state

Returns

The entry count

udif_logging_get_entry()

UDIF_EXPORT_API udif_errors udif_logging_get_entry	(	udif_logging_entry *	entry,
		const udif_logging_state *	log,
		size_t	seq )

Get log entry at sequence.

Retrieves a log entry by its sequence number.

Parameters

entry	The output log entry
log	[const] The log state
seq	The sequence number (0-based index)

Returns

Returns udif_error_none on success

udif_logging_get_statistics()

UDIF_EXPORT_API udif_errors udif_logging_get_statistics	(	const udif_logging_state *	log,
		size_t *	count,
		size_t *	capacity,
		uint8_t *	root )

Get log statistics.

Retrieves log statistics for monitoring.

Parameters

log	[const] The log state
count	Pointer to receive entry count
capacity	Pointer to receive capacity
root	The output root hash (32 bytes, can be NULL)

Returns

Returns udif_error_none on success

udif_logging_initialize()

UDIF_EXPORT_API udif_errors udif_logging_initialize	(	udif_logging_state *	log,
		udif_logging_type	logtype,
		const uint8_t *	ownerser,
		size_t	capacity )

Initialize a log.

Creates a new empty log for an entity.

Parameters

log	The log state structure
logtype	The log type (membership or transaction)
ownerser	[const] The owner's serial number (16 bytes)
capacity	Initial capacity (number of entries)

Returns

Returns udif_error_none on success

udif_logging_is_empty()

UDIF_EXPORT_API bool udif_logging_is_empty

(

const udif_logging_state *

log

)

Check if log is empty.

Tests if the log contains any entries.

Parameters

log	[const] The log state

Returns

Returns true if empty

udif_logging_is_full()

UDIF_EXPORT_API bool udif_logging_is_full

(

const udif_logging_state *

log

)

Check if log is full.

Tests if the log has reached capacity.

Parameters

log	[const] The log state

Returns

Returns true if full

udif_logging_resize()

UDIF_EXPORT_API udif_errors udif_logging_resize	(	udif_logging_state *	log,
		size_t	capacity )

Resize log capacity.

Expands the log capacity.

Parameters

log	The log state
capacity	The new capacity

Returns

Returns udif_error_none on success

udif_logging_verify_entry()

UDIF_EXPORT_API bool udif_logging_verify_entry	(	const udif_logging_entry *	entry,
		const uint8_t *	verkey )

Verify log entry signature.

Verifies the signature on a log entry.

Parameters

entry	[const] The log entry
verkey	[const] The signer's public key

Returns

Returns true if signature is valid

udif_logging_verify_proof()

UDIF_EXPORT_API bool udif_logging_verify_proof	(	const uint8_t *	proof,
		size_t	prooflen,
		const uint8_t *	root,
		const uint8_t *	entrydigest )

Verify log inclusion proof.

Verifies that a proof demonstrates entry membership in the log.

Parameters

proof	[const] The proof data
prooflen	The proof length
root	[const] The log Merkle root (32 bytes)
entrydigest	[const] The entry digest (32 bytes)

Returns

Returns true if proof is valid