Merkle-Chained Evidence Ledger (MCEL) More...

#include "mcelcommon.h"
#include "dilithium.h"

Data Structures
struct	mcel_store_callbacks
	The MCEL storage callback table. More...
struct	mcel_block_header
	The MCEL block header structure. More...
struct	mcel_checkpoint_audit_item
	The MCEL audit path item container. More...
struct	mcel_checkpoint_header
	The MCEL checkpoint header structure. More...
struct	mcel_ledger_state
	The MCEL ledger instance state. More...
struct	mcel_policy
	The MCEL namespace policy container. More...
struct	mcel_policy_context
	The MCEL policy context (caller-maintained). More...
struct	mcel_record_header
	The MCEL record header structure. More...

Macros
#define	MCEL_CONFIG_DILITHIUM
	The Dilithium MCEL parameter set.
#define	MCEL_USE_RCS_ENCRYPTION
	If the RCS encryption option is chosen SKDP uses the more modern RCS stream cipher with KMAC/QMAC authentication. The default symmetric cipher/authenticator is AES-256/GCM (GMAC Counter Mode) NIST standardized per SP800-38a.
#define	MCEL_ASYMMETRIC_SIGNING_KEY_SIZE (QSC_DILITHIUM_PRIVATEKEY_SIZE)
	The byte size of the secret private-key array.
#define	MCEL_ASYMMETRIC_VERIFY_KEY_SIZE (QSC_DILITHIUM_PUBLICKEY_SIZE)
	The byte size of the public-key array.
#define	MCEL_ASYMMETRIC_SIGNATURE_SIZE (QSC_DILITHIUM_SIGNATURE_SIZE)
	The byte size of the signature array.
#define	mcel_signature_generate_keypair qsc_dilithium_generate_keypair
	Generate an asymmetric signature key-pair.
#define	mcel_signature_sign qsc_dilithium_sign
	Sign a message with the asymmetric signature scheme.
#define	mcel_signature_verify qsc_dilithium_verify
	Verify a message with the asymmetric signature scheme.
#define	MCEL_BLOCK_HASH_SIZE 32U
	The MCEL 256-bit digest size in bytes.
#define	MCEL_BLOCK_HEADER_ENCODED_SIZE 62U
	The canonical encoded block header size in bytes.
#define	MCEL_BLOCK_ENCODED_FIXED_SIZE ((size_t)MCEL_BLOCK_HEADER_ENCODED_SIZE + ((size_t)MCEL_BLOCK_HASH_SIZE * 2U))
	The fixed-size portion of an encoded MCEL block in bytes.
#define	MCEL_BLOCK_KEYID_SIZE 32U
	The MCEL block key identifier size in bytes.
#define	MCEL_BLOCK_VERSION 1U
	The MCEL version number.
#define	MCEL_CHECKPOINT_HEADER_ENCODED_SIZE 62U
	The canonical encoded checkpoint header size in bytes.
#define	MCEL_CHECKPOINT_BUNDLE_FIXED_SIZE (MCEL_CHECKPOINT_HEADER_ENCODED_SIZE + (MCEL_BLOCK_HASH_SIZE * 2U))
	The fixed-size portion of an encoded MCEL checkpoint bundle in bytes.
#define	MCEL_CHECKPOINT_BUNDLE_ENCODED_SIZE (MCEL_ASYMMETRIC_SIGNATURE_SIZE + MCEL_BLOCK_HASH_SIZE + MCEL_CHECKPOINT_BUNDLE_FIXED_SIZE)
	The encoded-size portion of an encoded MCEL checkpoint bundle in bytes.
#define	MCEL_CHECKPOINT_KEYID_SIZE 32U
	The checkpoint key identifier size in bytes.
#define	MCEL_CHECKPOINT_SIGNED_COMMIT_SIZE (MCEL_ASYMMETRIC_SIGNATURE_SIZE + MCEL_BLOCK_HASH_SIZE)
	The size in bytes of a Dilithium signed checkpoint commitment message.
#define	MCEL_CHECKPOINT_VERSION 1U
	The MCEL checkpoint format version.
#define	MCEL_KEYROTATE_PAYLOAD_VERSION 0x01U
	The key rotation payload format version.
#define	MCEL_KEYROTATE_PAYLOAD_FIXED_SIZE (1U + 1U + (uint32_t)MCEL_CHECKPOINT_KEYID_SIZE + 2U)
	The fixed-size portion of the key rotation payload in bytes.
#define	MCEL_KEYROTATE_PAYLOAD_KEY_SIZE (MCEL_KEYROTATE_PAYLOAD_FIXED_SIZE + MCEL_ASYMMETRIC_VERIFY_KEY_SIZE)
	The rotation payload and signature verification key size.
#define	MCEL_LEDGER_NAMESPACE_ID_MAX 64U
	The maximum namespace identifier size in bytes.
#define	MCEL_PAYLOAD_MAX_SIZE 0xFFFFFFFFUL
	The maximum supported payload length in bytes (0 for unlimited).
#define	MCEL_RCS256_KEY_SIZE 32U
	The size in bytes of the RCS-256 cipher key.
#define	MCEL_RCS256_MAC_SIZE 32U
	The size in bytes of the RCS-256 authentication tag.
#define	MCEL_RCS_NONCE_SIZE 32U
	The size in bytes of the RCS nonce.
#define	MCEL_RCS_INFO_SIZE 48U
	The maximum size in bytes of the RCS info string.
#define	MCEL_RECORD_FLAG_ENCRYPTED 0x01U
	The record payload is encrypted (ciphertext) rather than plaintext.
#define	MCEL_RECORD_VERSION 1U
	The MCEL record format version.
#define	MCEL_RECORD_KEYID_SIZE 32U
	The record signer or policy key identifier size in bytes.
#define	MCEL_RECORD_HEADER_ENCODED_SIZE 58U
	The canonical encoded record header size in bytes.
#define	MCEL_RECORD_TYPE_KEYROTATE 0x3U
	The record type code for a key rotation control record.
#define	MCEL_SIGNED_HASH_SIZE (MCEL_ASYMMETRIC_SIGNATURE_SIZE + MCEL_BLOCK_HASH_SIZE)
	The byte size of the signed message.
#define	MCEL_STORE_LOC_BLOCKS "mcel/blocks"
	The logical storage location used to write serialized sealed blocks.
#define	MCEL_STORE_LOC_CHECKPOINTS "mcel/checkpoints"
	The logical storage location used to append serialized checkpoint bundles.
#define	MCEL_STORE_LOC_HEAD "mcel/head"
	The logical storage location used to store the current checkpoint head bundle.
#define	MCEL_STORE_LOC_RECORDS "mcel/records"
	The logical storage location used to append serialized records.

Typedefs
typedef MCEL_EXPORT_API struct mcel_store_callbacks	mcel_store_callbacks
typedef MCEL_EXPORT_API struct mcel_block_header	mcel_block_header
typedef MCEL_EXPORT_API struct mcel_checkpoint_audit_item	mcel_checkpoint_audit_item
typedef MCEL_EXPORT_API struct mcel_checkpoint_header	mcel_checkpoint_header
typedef MCEL_EXPORT_API struct mcel_ledger_state	mcel_ledger_state
typedef MCEL_EXPORT_API struct mcel_policy	mcel_policy
typedef MCEL_EXPORT_API struct mcel_policy_context	mcel_policy_context
typedef MCEL_EXPORT_API struct mcel_record_header	mcel_record_header

Enumerations
enum	mcel_record_types { mcel_record_type_none = 0U , mcel_record_type_checkpoint = 1U , mcel_record_type_event = 2U , mcel_record_type_key_rotate = 3U , mcel_record_type_policy = 4U }
	The MCEL record type identifiers. More...
enum	mcel_policy_ops { mcel_policyop_append_record = 1U , mcel_policyop_seal_checkpoint = 2U }
	The MCEL policy operation identifiers. More...
enum	mcel_policy_errors { mcel_policyerr_none = 0U , mcel_policyerr_invalid_parameter = 1U , mcel_policyerr_record_type_denied = 2U , mcel_policyerr_payload_too_large = 3U , mcel_policyerr_plaintext_denied = 4U , mcel_policyerr_sequence_invalid = 5U , mcel_policyerr_timestamp_invalid = 6U , mcel_policyerr_keyid_mismatch = 7U }
	The MCEL policy error values. More...

Functions
MCEL_EXPORT_API bool	mcel_block_commit (uint8_t output, const mcel_block_header header, const uint8_t *blkroot)
	Compute a MCEL block commitment from a block header and Merkle root.
MCEL_EXPORT_API bool	mcel_block_encode (uint8_t output, size_t outlen, const mcel_block_header header, const uint8_t blkroot, const uint8_t blkcommit, const uint8_t *reccommits, size_t reccount)
	Serialize a sealed MCEL block into a canonical byte string.
MCEL_EXPORT_API size_t	mcel_block_encoded_size (size_t reccount)
	Get the required buffer size for an encoded MCEL block.
MCEL_EXPORT_API bool	mcel_block_encode_header (uint8_t output, const mcel_block_header header)
	Encode a MCEL block header using canonical fixed-size encoding.
MCEL_EXPORT_API bool	mcel_block_seal (uint8_t blkroot, uint8_t blkcommit, const mcel_block_header header, const uint8_t reccommits, size_t reccount)
	Seal a MCEL block by computing the Merkle root and block commitment.
MCEL_EXPORT_API bool	mcel_checkpoint_audit_path_verify (uint8_t outheadcommit, const mcel_checkpoint_audit_item items, size_t itemcount, const uint8_t *publickey)
	Verify an ordered audit path of MCEL checkpoint bundles.
MCEL_EXPORT_API bool	mcel_checkpoint_bundle_encode (uint8_t output, size_t outlen, const mcel_checkpoint_header header, const uint8_t blkroot, const uint8_t prevcommit, const uint8_t *sigcommit, size_t siglen)
	Serialize a MCEL checkpoint bundle into a canonical byte string.
MCEL_EXPORT_API size_t	mcel_checkpoint_bundle_encoded_size (size_t siglen)
	Get the required buffer size for an encoded MCEL checkpoint bundle.
MCEL_EXPORT_API bool	mcel_checkpoint_bundle_verify (uint8_t chkcommit, mcel_checkpoint_header header, uint8_t blkroot, uint8_t prevcommit, const uint8_t bundle, size_t bundlelen, const uint8_t publickey)
	Verify a serialized MCEL checkpoint bundle.
MCEL_EXPORT_API bool	mcel_checkpoint_chain_link_verify (const uint8_t prevcommit, const uint8_t curprevcommit, const mcel_checkpoint_header prevhdr, const mcel_checkpoint_header curhdr)
	Verify the chain linkage between two verified checkpoints.
MCEL_EXPORT_API bool	mcel_checkpoint_commit (uint8_t output, const mcel_checkpoint_header header, const uint8_t blkroot, const uint8_t pldcommit)
	Compute a MCEL checkpoint commitment from a checkpoint header, block root, and previous checkpoint commitment.
MCEL_EXPORT_API bool	mcel_checkpoint_consistency_verify (const uint8_t firstroot, const uint8_t secondroot, size_t first, size_t second, const uint8_t *proof, size_t prooflen)
	Verify a MCEL Merkle consistency proof between two tree roots.
MCEL_EXPORT_API bool	mcel_checkpoint_decode_header (mcel_checkpoint_header header, const uint8_t input)
	Decode a MCEL checkpoint header from its canonical encoding.
MCEL_EXPORT_API bool	mcel_checkpoint_encode_header (uint8_t output, const mcel_checkpoint_header header)
	Encode a MCEL checkpoint header using canonical fixed-size encoding.
MCEL_EXPORT_API bool	mcel_checkpoint_prove_consistency (uint8_t proof, size_t prooflen, const uint8_t leaves, size_t oldcount, size_t newcount)
	Generate a MCEL Merkle consistency proof between two tree sizes.
MCEL_EXPORT_API bool	mcel_checkpoint_seal (uint8_t chkcommit, uint8_t sigcommit, size_t siglen, const mcel_checkpoint_header header, const uint8_t blkroot, const uint8_t prevcommit, const uint8_t privatekey, bool(rng_generate)(uint8_t *, size_t))
	Seal a MCEL checkpoint from a sealed block by generating the checkpoint commitment and signing it.
MCEL_EXPORT_API bool	mcel_checkpoint_sign (uint8_t sigcommit, size_t siglen, const uint8_t chkcommit, const uint8_t privatekey, bool(rng_generate)(uint8_t , size_t))
	Sign a MCEL checkpoint commitment using Dilithium.
MCEL_EXPORT_API bool	mcel_checkpoint_verify (uint8_t chkcommit, size_t commitlen, const uint8_t sigcommit, size_t siglen, const uint8_t publickey)
	Verify a MCEL signed checkpoint commitment using Dilithium.
MCEL_EXPORT_API size_t	mcel_keyrotate_payload_size (size_t pubkeylen)
	Get the required buffer size for a key rotation record payload.
MCEL_EXPORT_API size_t	mcel_keyrotate_record_create (mcel_record_header header, uint8_t payload, size_t payload_len, uint64_t sequence, uint8_t flags, const uint8_t newkeyid, const uint8_t newpubkey, size_t pubkeylen)
	Create a key rotation record header and payload.
MCEL_EXPORT_API bool	mcel_ledger_append_record (mcel_ledger_state state, uint8_t reccommit, uint64_t outpos, const mcel_record_header header, const uint8_t *payload, size_t paylen)
	Append a record to the ledger record log and return its commitment.
MCEL_EXPORT_API bool	mcel_ledger_get_checkpoint_head (mcel_ledger_state state, uint8_t head_commit, mcel_checkpoint_header *head_header)
	Get the current checkpoint head from the ledger state.
MCEL_EXPORT_API bool	mcel_ledger_initialize (mcel_ledger_state state, const mcel_store_callbacks store, const uint8_t nsid, size_t nsidlen, const uint8_t publickey, uint8_t *headbuf, size_t headbuflen)
	Initialize (open) a MCEL ledger namespace and load the checkpoint head if present.
MCEL_EXPORT_API bool	mcel_ledger_seal_block (mcel_ledger_state state, uint8_t blkroot, uint8_t blkcommit, const mcel_block_header header, const uint8_t reccommits, size_t reccount, uint8_t blockbuf, size_t blockbuflen, uint64_t *outpos)
	Seal a block from record commitments and write the sealed block through the storage callbacks.
MCEL_EXPORT_API bool	mcel_ledger_seal_checkpoint (mcel_ledger_state state, uint8_t chkcommit, const mcel_checkpoint_header header, const uint8_t blkroot, const void sigkey, uint8_t bundlebuf, size_t bundlebuflen, uint64_t *outpos)
	Seal a checkpoint from a sealed block root and update the ledger head.
MCEL_EXPORT_API bool	mcel_ledger_verify_integrity (mcel_ledger_state state, uint8_t headbuf, size_t headbuflen, const mcel_checkpoint_audit_item *audit, size_t auditcount)
	Verify the cryptographic integrity of the ledger state.
MCEL_EXPORT_API bool	mcel_payload_commit (uint8_t output, bool encrypted, const uint8_t payload, size_t paylen)
	Compute a MCEL payload commitment.
MCEL_EXPORT_API bool	mcel_policy_apply (mcel_policy_errors perr, const mcel_policy policy, const mcel_policy_context state, mcel_policy_ops op, const mcel_record_header recordhdr, const mcel_checkpoint_header *checkpointhdr)
	Apply namespace policy rules to a MCEL operation.
MCEL_EXPORT_API bool	mcel_record_decrypt_payload (uint8_t output, size_t outlen, const uint8_t ciphertext, size_t ctlen, const uint8_t ad, size_t adlen, const uint8_t key, uint8_t *nonce)
	Decrypt a record payload using the AEAD cipher.
MCEL_EXPORT_API void	mcel_record_encrypt_payload (uint8_t output, size_t outlen, const uint8_t plaintext, size_t ptlen, const uint8_t ad, size_t adlen, const uint8_t key, uint8_t *nonce)
	Encrypt a record payload using the AEAD cipher.
MCEL_EXPORT_API bool	mcel_record_encode_header (uint8_t output, const mcel_record_header header)
	Encode a MCEL record header using canonical fixed-size encoding.
MCEL_EXPORT_API bool	mcel_record_commit (uint8_t output, const mcel_record_header header, const uint8_t *pldcommit)
	Compute a MCEL record commitment from a record header and payload commitment.
MCEL_EXPORT_API bool	mcel_store_callbacks_initialize (mcel_store_callbacks output, const mcel_store_callbacks input, void *context)
	Initialize and validate the MCEL storage callback table.

Variables
MCEL_EXPORT_API enum mcel_record_types	mcel_record_types
MCEL_EXPORT_API enum mcel_policy_ops	mcel_policy_ops
MCEL_EXPORT_API enum mcel_policy_errors	mcel_policy_errors

Detailed Description

Merkle-Chained Evidence Ledger (MCEL)

DOXYGEN_IGNORE

This header defines the public API for the MCEL evidence ledger subsystem. The ledger implements a local, append only, cryptographically verifiable logging structure intended for audit, non-repudiation, and regulatory evidence purposes.

The MCEL ledger is designed as a foundational substrate for higher-level systems, including secure financial messaging, asset transfer workflows, and globally anchored provenance systems. It is not a consensus blockchain and does not perform settlement, balance tracking, or global ordering.

Core properties provided by this API include:

Append only record storage with hash chaining
Deterministic record commitments using Keccak-based hashing
Cryptographic signatures over records and checkpoints using UDIF keys
Merkle tree batching and checkpointing for scalable audit
Inclusion proofs for selective disclosure and sampled verification
External anchoring references for third-party attestation
Explicit epoch management for key rotation and administrative resets

Records stored in the ledger are opaque to the ledger itself. The ledger does not interpret message semantics, payload formats, or application-level meaning. Its sole responsibility is to provide verifiable evidence of existence, ordering, and authorization.

Typical usage flow:

Initialize a ledger instance with a stable ledger identifier, epoch, signing key, and append-only storage backend.
Append records representing messages, acknowledgments, or administrative actions, each producing a signed record commitment.
Periodically batch records into checkpoints, producing signed Merkle roots that summarize ledger state over a sequence range.
Optionally anchor checkpoint commitments to an external witness system.
Provide inclusion proofs and checkpoint artifacts to auditors, counterparties, or regulators as required.

All cryptographic operations are domain separated and deterministic. Verification of records and checkpoints can be performed independently by third parties without access to private keys or plaintext payloads.

This API is intended to be stable and forward compatible. Extensions such as global provenance pillars, cross-ledger anchoring, or asset-level semantics can be layered above this interface without breaking existing evidence guarantees.

Enumeration Type Documentation

◆ mcel_policy_errors

enum mcel_policy_errors

The MCEL policy error values.

Enumerator
mcel_policyerr_none	No policy error is set
mcel_policyerr_invalid_parameter	Policy error invalid parameter
mcel_policyerr_record_type_denied	Policy error record type denied
mcel_policyerr_payload_too_large	Policy error payload too large
mcel_policyerr_plaintext_denied	Policy error plaintext denied
mcel_policyerr_sequence_invalid	Policy error sequence invalid
mcel_policyerr_timestamp_invalid	Policy error timestampinvalid
mcel_policyerr_keyid_mismatch	Policy error keyid mismatch

◆ mcel_policy_ops

enum mcel_policy_ops

The MCEL policy operation identifiers.

Enumerator
mcel_policyop_append_record	Authorize appending a record
mcel_policyop_seal_checkpoint	Authorize sealing a checkpoint

◆ mcel_record_types

enum mcel_record_types

The MCEL record type identifiers.

Enumerator
mcel_record_type_none	Record type is none
mcel_record_type_checkpoint	A checkpoint reference record (extension hook)
mcel_record_type_event	A general event record
mcel_record_type_key_rotate	A key rotation event record
mcel_record_type_policy	A policy or configuration record

Function Documentation

◆ mcel_block_commit()

MCEL_EXPORT_API bool mcel_block_commit	(	uint8_t *	output,
		const mcel_block_header *	header,
		const uint8_t *	blkroot )

Compute a MCEL block commitment from a block header and Merkle root.

Parameters

output	A pointer to the output commitment array of size `MCEL_BLOCK_HASH_SIZE`.
header	[const] A pointer to the block header structure.
blkroot	[const] A pointer to the block Merkle root array of size `MCEL_BLOCK_HASH_SIZE`.

Returns: Returns true if the commitment was generated successfully.

◆ mcel_block_encode()

MCEL_EXPORT_API bool mcel_block_encode	(	uint8_t *	output,
		size_t	outlen,
		const mcel_block_header *	header,
		const uint8_t *	blkroot,
		const uint8_t *	blkcommit,
		const uint8_t *	reccommits,
		size_t	reccount )

Serialize a sealed MCEL block into a canonical byte string.

Parameters

output	A pointer to the encoded block buffer.
outlen	The length of the output buffer.
header	[const] A pointer to the block header structure.
blkroot	[const] A pointer to the block Merkle root array of size `MCEL_BLOCK_HASH_SIZE`.
blkcommit	[const] A pointer to the block commitment array of size `MCEL_BLOCK_HASH_SIZE`.
reccommits	[const] A pointer to an array of record commitments, each of size `MCEL_BLOCK_HASH_SIZE`.
reccount	The number of record commitments in the array.

Returns: Returns true if the block was serialized successfully.

◆ mcel_block_encode_header()

MCEL_EXPORT_API bool mcel_block_encode_header	(	uint8_t *	output,
		const mcel_block_header *	header )

Encode a MCEL block header using canonical fixed-size encoding.

Parameters

output	A pointer to the output byte array of size `MCEL_BLOCK_HEADER_ENCODED_SIZE`.
header	[const] A pointer to the block header structure.

Returns: Returns true if the header was encoded successfully.

◆ mcel_block_encoded_size()

MCEL_EXPORT_API size_t mcel_block_encoded_size ( size_t reccount )

Get the required buffer size for an encoded MCEL block.

Parameters

reccount The number of record commitments in the block.

Returns: The required buffer size in bytes for mcel_encode_block or 0 on error.

◆ mcel_block_seal()

MCEL_EXPORT_API bool mcel_block_seal	(	uint8_t *	blkroot,
		uint8_t *	blkcommit,
		const mcel_block_header *	header,
		const uint8_t *	reccommits,
		size_t	reccount )

Seal a MCEL block by computing the Merkle root and block commitment.

Parameters

blkroot	A pointer to the output Merkle root array of size `MCEL_BLOCK_HASH_SIZE`.
blkcommit	A pointer to the output block commitment array of size `MCEL_BLOCK_HASH_SIZE`.
header	[const] A pointer to the block header structure.
reccommits	[const] A pointer to an array of record commitments, each of size `MCEL_BLOCK_HASH_SIZE`.
reccount	The number of record commitments in the array.

Returns: Returns true if the block was sealed successfully.

◆ mcel_checkpoint_audit_path_verify()

MCEL_EXPORT_API bool mcel_checkpoint_audit_path_verify	(	uint8_t *	outheadcommit,
		const mcel_checkpoint_audit_item *	items,
		size_t	itemcount,
		const uint8_t *	publickey )

Verify an ordered audit path of MCEL checkpoint bundles.

Parameters

outheadcommit	A pointer to the output last (head) checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.
items	[const] A pointer to the ordered audit item array (oldest to newest).
itemcount	The number of audit items in the array.
publickey	[const] A pointer to the Dilithium public key array.

Returns: Returns true if the audit path was verified successfully.

◆ mcel_checkpoint_bundle_encode()

MCEL_EXPORT_API bool mcel_checkpoint_bundle_encode	(	uint8_t *	output,
		size_t	outlen,
		const mcel_checkpoint_header *	header,
		const uint8_t *	blkroot,
		const uint8_t *	prevcommit,
		const uint8_t *	sigcommit,
		size_t	siglen )

Serialize a MCEL checkpoint bundle into a canonical byte string.

Parameters

output	A pointer to the output buffer.
outlen	The length of the output buffer in bytes.
header	[const] A pointer to the checkpoint header structure.
blkroot	[const] A pointer to the sealed block Merkle root array of size `MCEL_BLOCK_HASH_SIZE`.
prevcommit	[const] A pointer to the previous checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.
sigcommit	[const] A pointer to the signed commitment message.
siglen	The length of the signed commitment message in bytes.

Returns: Returns true if the bundle was serialized successfully.

◆ mcel_checkpoint_bundle_encoded_size()

MCEL_EXPORT_API size_t mcel_checkpoint_bundle_encoded_size ( size_t siglen )

Get the required buffer size for an encoded MCEL checkpoint bundle.

Parameters

siglen The length of the signed commitment message in bytes.

Returns: The required buffer size in bytes for mcel_encode_checkpoint_bundle or 0 on error.

◆ mcel_checkpoint_bundle_verify()

MCEL_EXPORT_API bool mcel_checkpoint_bundle_verify	(	uint8_t *	chkcommit,
		mcel_checkpoint_header *	header,
		uint8_t *	blkroot,
		uint8_t *	prevcommit,
		const uint8_t *	bundle,
		size_t	bundlelen,
		const uint8_t *	publickey )

Verify a serialized MCEL checkpoint bundle.

Parameters

chkcommit	A pointer to the output checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.
header	A pointer to the output checkpoint header structure.
blkroot	A pointer to the output block Merkle root array of size `MCEL_BLOCK_HASH_SIZE`.
prevcommit	A pointer to the output previous checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.
bundle	[const] A pointer to the serialized checkpoint bundle.
bundlelen	The length of the serialized bundle in bytes.
publickey	[const] A pointer to the Dilithium public key array.

Returns: Returns true if the bundle was verified successfully.

◆ mcel_checkpoint_chain_link_verify()

MCEL_EXPORT_API bool mcel_checkpoint_chain_link_verify	(	const uint8_t *	prevcommit,
		const uint8_t *	curprevcommit,
		const mcel_checkpoint_header *	prevhdr,
		const mcel_checkpoint_header *	curhdr )

Verify the chain linkage between two verified checkpoints.

Parameters

prevcommit	[const] The previous checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.
curprevcommit	[const] The current checkpoints embedded previous-commit array of size `MCEL_BLOCK_HASH_SIZE`.
prevhdr	[const] A pointer to the previous checkpoint header structure.
curhdr	[const] A pointer to the current checkpoint header structure.

Returns: Returns true if the chain link is valid.

◆ mcel_checkpoint_commit()

MCEL_EXPORT_API bool mcel_checkpoint_commit	(	uint8_t *	output,
		const mcel_checkpoint_header *	header,
		const uint8_t *	blkroot,
		const uint8_t *	pldcommit )

Compute a MCEL checkpoint commitment from a checkpoint header, block root, and previous checkpoint commitment.

Parameters

output	A pointer to the output commitment array of size `MCEL_BLOCK_HASH_SIZE`.
header	[const] A pointer to the checkpoint header structure.
blkroot	[const] A pointer to the block Merkle root array of size `MCEL_BLOCK_HASH_SIZE`.
pldcommit	[const] A pointer to the previous checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.

Returns: Returns true if the commitment was generated successfully.

◆ mcel_checkpoint_consistency_verify()

MCEL_EXPORT_API bool mcel_checkpoint_consistency_verify	(	const uint8_t *	firstroot,
		const uint8_t *	secondroot,
		size_t	first,
		size_t	second,
		const uint8_t *	proof,
		size_t	prooflen )

Verify a MCEL Merkle consistency proof between two tree roots.

Parameters

firstroot	[const] The older tree root hash.
secondroot	[const] The newer tree root hash.
first	The older tree size (leaf count), must be > 0 and < second.
second	The newer tree size (leaf count), must be > first.
proof	[const] The consistency proof buffer (concatenated hashes).
prooflen	The length of the proof buffer in bytes.

Returns: Returns true if the consistency proof is valid.

◆ mcel_checkpoint_decode_header()

MCEL_EXPORT_API bool mcel_checkpoint_decode_header	(	mcel_checkpoint_header *	header,
		const uint8_t *	input )

Decode a MCEL checkpoint header from its canonical encoding.

Parameters

header	A pointer to the receiving checkpoint header structure.
input	[const] A pointer to the encoded header bytes.

Returns: Returns true on success.

◆ mcel_checkpoint_encode_header()

MCEL_EXPORT_API bool mcel_checkpoint_encode_header	(	uint8_t *	output,
		const mcel_checkpoint_header *	header )

Encode a MCEL checkpoint header using canonical fixed-size encoding.

Parameters

output	A pointer to the output byte array of size `MCEL_CHECKPOINT_HEADER_ENCODED_SIZE`.
header	[const] A pointer to the checkpoint header structure.

Returns: Returns true if the header was encoded successfully.

◆ mcel_checkpoint_prove_consistency()

MCEL_EXPORT_API bool mcel_checkpoint_prove_consistency	(	uint8_t *	proof,
		size_t	prooflen,
		const uint8_t *	leaves,
		size_t	oldcount,
		size_t	newcount )

Generate a MCEL Merkle consistency proof between two tree sizes.

Parameters

proof	A pointer to the output proof buffer.
prooflen	The length of the output proof buffer in bytes.
leaves	[const] A pointer to the leaf hash array (new_count * MCEL_BLOCK_HASH_SIZE).
oldcount	The leaf count of the older tree (must be <= new_count).
newcount	The leaf count of the newer tree.

Returns: Returns true if the proof was generated successfully.

◆ mcel_checkpoint_seal()

MCEL_EXPORT_API bool mcel_checkpoint_seal	(	uint8_t *	chkcommit,
		uint8_t *	sigcommit,
		size_t *	siglen,
		const mcel_checkpoint_header *	header,
		const uint8_t *	blkroot,
		const uint8_t *	prevcommit,
		const uint8_t *	privatekey,
		bool(*	rng_generate )(uint8_t *, size_t) )

Seal a MCEL checkpoint from a sealed block by generating the checkpoint commitment and signing it.

Parameters

chkcommit	A pointer to the output checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.
sigcommit	A pointer to the signed commitment output buffer of size `MCEL_CHECKPOINT_SIGNED_COMMIT_SIZE`.
siglen	A pointer to the returned signed message length in bytes.
header	[const] A pointer to the checkpoint header structure.
blkroot	[const] A pointer to the sealed block Merkle root array of size `MCEL_BLOCK_HASH_SIZE`.
prevcommit	[const] A pointer to the previous checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.
privatekey	[const] A pointer to the Dilithium private key array.
rng_generate	A pointer to a secure RNG function.

Returns: Returns true if the checkpoint was sealed successfully.

◆ mcel_checkpoint_sign()

MCEL_EXPORT_API bool mcel_checkpoint_sign	(	uint8_t *	sigcommit,
		size_t *	siglen,
		const uint8_t *	chkcommit,
		const uint8_t *	privatekey,
		bool(*	rng_generate )(uint8_t *, size_t) )

Sign a MCEL checkpoint commitment using Dilithium.

Parameters

sigcommit	A pointer to the signed commitment output buffer of size `MCEL_CHECKPOINT_SIGNED_COMMIT_SIZE`.
siglen	A pointer to the returned signed message length in bytes.
chkcommit	[const] A pointer to the checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.
privatekey	[const] A pointer to the Dilithium private key array.
rng_generate	A pointer to a secure RNG function.

Returns: Returns true if the commitment was signed successfully.

◆ mcel_checkpoint_verify()

MCEL_EXPORT_API bool mcel_checkpoint_verify	(	uint8_t *	chkcommit,
		size_t *	commitlen,
		const uint8_t *	sigcommit,
		size_t	siglen,
		const uint8_t *	publickey )

Verify a MCEL signed checkpoint commitment using Dilithium.

Parameters

chkcommit	A pointer to the output checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.
commitlen	A pointer to the returned commitment length in bytes.
sigcommit	[const] A pointer to the signed commitment message.
siglen	The signed message length in bytes.
publickey	[const] A pointer to the Dilithium public key array.

Returns: Returns true if the signature was verified successfully.

◆ mcel_keyrotate_payload_size()

MCEL_EXPORT_API size_t mcel_keyrotate_payload_size ( size_t pubkeylen )

Get the required buffer size for a key rotation record payload.

Parameters

pubkeylen The new public key length in bytes.

Returns: The required payload size in bytes.

◆ mcel_keyrotate_record_create()

MCEL_EXPORT_API size_t mcel_keyrotate_record_create	(	mcel_record_header *	header,
		uint8_t *	payload,
		size_t	payload_len,
		uint64_t	sequence,
		uint8_t	flags,
		const uint8_t *	newkeyid,
		const uint8_t *	newpubkey,
		size_t	pubkeylen )

Create a key rotation record header and payload.

Parameters

header	A pointer to the receiving record header structure.
payload	A pointer to the output payload buffer.
payload_len	The length of the output payload buffer in bytes.
sequence	The record sequence number.
flags	The record flags.
newkeyid	[const] The new signer or policy identifier.
newpubkey	[const] The new public key bytes.
pubkeylen	The new public key length in bytes.

Returns: Returns the payload length in bytes.

◆ mcel_ledger_append_record()

MCEL_EXPORT_API bool mcel_ledger_append_record	(	mcel_ledger_state *	state,
		uint8_t *	reccommit,
		uint64_t *	outpos,
		const mcel_record_header *	header,
		const uint8_t *	payload,
		size_t	paylen )

Append a record to the ledger record log and return its commitment.

Parameters

state	A pointer to the ledger state structure.
reccommit	A pointer to the output record commitment array of size `MCEL_BLOCK_HASH_SIZE`.
outpos	A pointer to the returned append position offset, can be NULL.
header	[const] A pointer to the record header structure.
payload	[const] A pointer to the record payload bytes.
paylen	The payload length in bytes.

Returns: Returns true if the record was committed and appended successfully.

◆ mcel_ledger_get_checkpoint_head()

MCEL_EXPORT_API bool mcel_ledger_get_checkpoint_head	(	mcel_ledger_state *	state,
		uint8_t *	head_commit,
		mcel_checkpoint_header *	head_header )

Get the current checkpoint head from the ledger state.

Parameters

state	A pointer to the ledger state structure.
head_commit	A pointer to the output head checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.
head_header	A pointer to the output head checkpoint header structure.

Returns: Returns true if the head is available, false if no head is loaded.

◆ mcel_ledger_initialize()

MCEL_EXPORT_API bool mcel_ledger_initialize	(	mcel_ledger_state *	state,
		const mcel_store_callbacks *	store,
		const uint8_t *	nsid,
		size_t	nsidlen,
		const uint8_t *	publickey,
		uint8_t *	headbuf,
		size_t	headbuflen )

Initialize (open) a MCEL ledger namespace and load the checkpoint head if present.

Parameters

state	A pointer to the ledger state structure.
store	[const] A pointer to an initialized storage callback table.
nsid	[const] A pointer to the namespace identifier bytes.
nsidlen	The namespace identifier length in bytes.
publickey	[const] A pointer to the Dilithium public key.
headbuf	A pointer to a caller-provided buffer used to read the head checkpoint bundle.
headbuflen	The length of the head buffer in bytes.

Returns: Returns true if the ledger was initialized successfully.

◆ mcel_ledger_seal_block()

MCEL_EXPORT_API bool mcel_ledger_seal_block	(	mcel_ledger_state *	state,
		uint8_t *	blkroot,
		uint8_t *	blkcommit,
		const mcel_block_header *	header,
		const uint8_t *	reccommits,
		size_t	reccount,
		uint8_t *	blockbuf,
		size_t	blockbuflen,
		uint64_t *	outpos )

Seal a block from record commitments and write the sealed block through the storage callbacks.

Parameters

state	A pointer to the ledger state structure.
blkroot	A pointer to the output block Merkle root array of size `MCEL_BLOCK_HASH_SIZE`.
blkcommit	A pointer to the output block commitment array of size `MCEL_BLOCK_HASH_SIZE`.
header	[const] A pointer to the block header structure.
reccommits	[const] A pointer to an array of record commitments (reccount * MCEL_BLOCK_HASH_SIZE).
reccount	The number of record commitments.
blockbuf	A pointer to a caller-provided buffer used to encode the sealed block.
blockbuflen	The length of the block buffer in bytes.
outpos	A pointer to the returned append position offset, can be NULL.

Returns: Returns true if the block was sealed and stored successfully.

◆ mcel_ledger_seal_checkpoint()

MCEL_EXPORT_API bool mcel_ledger_seal_checkpoint	(	mcel_ledger_state *	state,
		uint8_t *	chkcommit,
		const mcel_checkpoint_header *	header,
		const uint8_t *	blkroot,
		const void *	sigkey,
		uint8_t *	bundlebuf,
		size_t	bundlebuflen,
		uint64_t *	outpos )

Seal a checkpoint from a sealed block root and update the ledger head.

Parameters

state	A pointer to the ledger state structure.
chkcommit	A pointer to the output checkpoint commitment array of size `MCEL_BLOCK_HASH_SIZE`.
header	[const] A pointer to the checkpoint header structure.
blkroot	[const] A pointer to the sealed block Merkle root array of size `MCEL_BLOCK_HASH_SIZE`.
sigkey	[const] A pointer to the Dilithium private signing key.
bundlebuf	A pointer to a caller-provided buffer used to encode the checkpoint bundle.
bundlebuflen	The length of the bundle buffer in bytes.
outpos	A pointer to the returned append position offset, can be NULL.

Returns: Returns true if the checkpoint was sealed and stored successfully.

◆ mcel_ledger_verify_integrity()

MCEL_EXPORT_API bool mcel_ledger_verify_integrity	(	mcel_ledger_state *	state,
		uint8_t *	headbuf,
		size_t	headbuflen,
		const mcel_checkpoint_audit_item *	audit,
		size_t	auditcount )

Verify the cryptographic integrity of the ledger state.

This function verifies the stored head checkpoint bundle (if present) by reading it from the storage backend and validating its signature and commitment. Optionally, an audit path may be provided to verify a sequence of checkpoint bundles and their chain links.

Parameters

state	A pointer to the ledger state structure.
headbuf	A pointer to a caller-provided buffer used to read the head bundle.
headbuflen	The length of the head buffer in bytes.
audit	[const] An optional pointer to an audit path item array, can be NULL.
auditcount	The number of audit items in the array, can be 0.

Returns: Returns true if integrity checks succeeded, false on failure.

◆ mcel_payload_commit()

MCEL_EXPORT_API bool mcel_payload_commit	(	uint8_t *	output,
		bool	encrypted,
		const uint8_t *	payload,
		size_t	paylen )

Compute a MCEL payload commitment.

Parameters

output	A pointer to the output hash array of size `MCEL_BLOCK_HASH_SIZE`.
encrypted	Set to true if the payload is encrypted, false if plaintext.
payload	[const] A pointer to the payload bytes.
paylen	The length of the payload in bytes.

Returns: Returns true on success.

◆ mcel_policy_apply()

MCEL_EXPORT_API bool mcel_policy_apply	(	mcel_policy_errors *	perr,
		const mcel_policy *	policy,
		const mcel_policy_context *	state,
		mcel_policy_ops	op,
		const mcel_record_header *	recordhdr,
		const mcel_checkpoint_header *	checkpointhdr )

Apply namespace policy rules to a MCEL operation.

Parameters

perr	A pointer to the returned policy error value.
policy	[const] A pointer to the policy container.
state	[const] A pointer to the policy context.
op	The operation being authorized.
recordhdr	[const] A pointer to the record header (append op), can be NULL otherwise.
checkpointhdr	[const] A pointer to the checkpoint header (seal op), can be NULL otherwise.

Returns: Returns true if the operation is allowed.

◆ mcel_record_commit()

MCEL_EXPORT_API bool mcel_record_commit	(	uint8_t *	output,
		const mcel_record_header *	header,
		const uint8_t *	pldcommit )

Compute a MCEL record commitment from a record header and payload commitment.

Parameters

output	A pointer to the output hash array of size `MCEL_BLOCK_HASH_SIZE`.
header	[const] A pointer to the record header structure.
pldcommit	[const] A pointer to the payload commitment array of size `MCEL_BLOCK_HASH_SIZE`.

Returns: Returns true if the record commitment was generated successfully.

◆ mcel_record_decrypt_payload()

MCEL_EXPORT_API bool mcel_record_decrypt_payload	(	uint8_t *	output,
		size_t	outlen,
		const uint8_t *	ciphertext,
		size_t	ctlen,
		const uint8_t *	ad,
		size_t	adlen,
		const uint8_t *	key,
		uint8_t *	nonce )

Decrypt a record payload using the AEAD cipher.

Parameters

output	A pointer to the plaintext output buffer.
outlen	The length of the output buffer in bytes.
ciphertext	[const] A pointer to the ciphertext input buffer (includes tag).
ctlen	The length of the ciphertext in bytes.
ad	[const] A pointer to associated data, can be NULL if `adlen` is 0.
adlen	The associated data length in bytes.
key	[const] A pointer to the cipher key.
nonce	A pointer to the nonce array of size `MCEL_RCS_NONCE_SIZE`.

Returns: Returns true if the transform completed, false on parameter or length failure.

◆ mcel_record_encode_header()

MCEL_EXPORT_API bool mcel_record_encode_header	(	uint8_t *	output,
		const mcel_record_header *	header )

Encode a MCEL record header using canonical fixed-size encoding.

Parameters

output	A pointer to the output byte array of size `MCEL_RECORD_HEADER_ENCODED_SIZE`.
header	[const] A pointer to the record header structure.

Returns: Returns true if the header was encoded successfully.

◆ mcel_record_encrypt_payload()

MCEL_EXPORT_API void mcel_record_encrypt_payload	(	uint8_t *	output,
		size_t	outlen,
		const uint8_t *	plaintext,
		size_t	ptlen,
		const uint8_t *	ad,
		size_t	adlen,
		const uint8_t *	key,
		uint8_t *	nonce )

Encrypt a record payload using the AEAD cipher.

Parameters

output	A pointer to the ciphertext output buffer.
outlen	The length of the output buffer in bytes.
plaintext	[const] A pointer to the plaintext input buffer.
ptlen	The length of the plaintext in bytes.
ad	[const] A pointer to associated data, can be NULL if `adlen` is 0.
adlen	The associated data length in bytes.
key	[const] A pointer to the cipher key.
nonce	A pointer to the nonce array of size `MCEL_RCS_NONCE_SIZE`.

◆ mcel_store_callbacks_initialize()

MCEL_EXPORT_API bool mcel_store_callbacks_initialize	(	mcel_store_callbacks *	output,
		const mcel_store_callbacks *	input,
		void *	context )

Initialize and validate the MCEL storage callback table.

Parameters

output	A pointer to the receiving callback table.
input	[const] A pointer to the caller-supplied callback table.
context	A pointer to the host-defined storage context.

Returns: Returns true if the callback table is valid and initialized, false on failure.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ mcel_policy_errors

◆ mcel_policy_ops

◆ mcel_record_types

Function Documentation

◆ mcel_block_commit()

◆ mcel_block_encode()

◆ mcel_block_encode_header()

◆ mcel_block_encoded_size()

◆ mcel_block_seal()

◆ mcel_checkpoint_audit_path_verify()

◆ mcel_checkpoint_bundle_encode()

◆ mcel_checkpoint_bundle_encoded_size()

◆ mcel_checkpoint_bundle_verify()

◆ mcel_checkpoint_chain_link_verify()

◆ mcel_checkpoint_commit()

◆ mcel_checkpoint_consistency_verify()

◆ mcel_checkpoint_decode_header()

◆ mcel_checkpoint_encode_header()

◆ mcel_checkpoint_prove_consistency()

◆ mcel_checkpoint_seal()

◆ mcel_checkpoint_sign()

◆ mcel_checkpoint_verify()

◆ mcel_keyrotate_payload_size()

◆ mcel_keyrotate_record_create()

◆ mcel_ledger_append_record()

◆ mcel_ledger_get_checkpoint_head()

◆ mcel_ledger_initialize()

◆ mcel_ledger_seal_block()

◆ mcel_ledger_seal_checkpoint()

◆ mcel_ledger_verify_integrity()

◆ mcel_payload_commit()

◆ mcel_policy_apply()

◆ mcel_record_commit()

◆ mcel_record_decrypt_payload()

◆ mcel_record_encode_header()

◆ mcel_record_encrypt_payload()

◆ mcel_store_callbacks_initialize()