mcel.h

Go to the documentation of this file.

/* 2025-2026 Quantum Resistant Cryptographic Solutions Corporation
 * All Rights Reserved.
 *
 * NOTICE:
 * This software and all accompanying materials are the exclusive property of
 * Quantum Resistant Cryptographic Solutions Corporation (QRCS). The intellectual
 * and technical concepts contained herein are proprietary to QRCS and are
 * protected under applicable Canadian, U.S., and international copyright,
 * patent, and trade secret laws.
 *
 * CRYPTOGRAPHIC ALGORITHMS AND IMPLEMENTATIONS:
 * - This software includes implementations of cryptographic primitives and
 *   algorithms that are standardized or in the public domain, such as AES
 *   and SHA-3, which are not proprietary to QRCS.
 * - This software also includes cryptographic primitives, constructions, and
 *   algorithms designed by QRCS, including but not limited to RCS, SCB, CSX, QMAC, and
 *   related components, which are proprietary to QRCS.
 * - All source code, implementations, protocol compositions, optimizations,
 *   parameter selections, and engineering work contained in this software are
 *   original works of QRCS and are protected under this license.
 *
 * LICENSE AND USE RESTRICTIONS:
 * - This software is licensed under the Quantum Resistant Cryptographic Solutions
 *   Public Research and Evaluation License (QRCS-PREL), 2025-2026.
 * - Permission is granted solely for non-commercial evaluation, academic research,
 *   cryptographic analysis, interoperability testing, and feasibility assessment.
 * - Commercial use, production deployment, commercial redistribution, or
 *   integration into products or services is strictly prohibited without a
 *   separate written license agreement executed with QRCS.
 * - Licensing and authorized distribution are solely at the discretion of QRCS.
 *
 * EXPERIMENTAL CRYPTOGRAPHY NOTICE:
 * Portions of this software may include experimental, novel, or evolving
 * cryptographic designs. Use of this software is entirely at the user's risk.
 *
 * DISCLAIMER:
 * THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE, SECURITY, OR NON-INFRINGEMENT. QRCS DISCLAIMS ALL
 * LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
 * ARISING FROM THE USE OR MISUSE OF THIS SOFTWARE.
 *
 * FULL LICENSE:
 * This software is subject to the Quantum Resistant Cryptographic Solutions
 * Public Research and Evaluation License (QRCS-PREL), 2025-2026. The complete license terms
 * are provided in the accompanying LICENSE file or at https://www.qrcscorp.ca.
 *
 * Written by: John G. Underhill
 * Contact: contact\qrcscorp.ca
 */
 
/*
 * \file mcel.h
 * \brief MCEL support header
 * 
 * Merkle Chained Event Ledger (MCEL)
 *
 * MCEL implements an append-only, cryptographically verifiable event ledger
 * designed for long-lived audit, provenance, and integrity assurance.
 * The ledger records discrete events as immutable records, batches records
 * into Merkle trees, and chains those batches using signed checkpoint
 * commitments to form a tamper-evident history.
 *
 * MCEL is optimized for environments with a bounded set of writers and a
 * potentially unbounded set of verifiers. It provides strong integrity,
 * ordering, and non-repudiation guarantees without requiring distributed
 * consensus, peer-to-peer networking, or economic mechanisms.
 *
 * Core properties:
 * - Append-only event records with canonical serialization
 * - Domain-separated cryptographic commitments for all object types
 * - Merkle tree batching for scalable inclusion proofs
 * - Hash-chained checkpoints with asymmetric signatures
 * - Portable checkpoint bundles for independent verification
 * - Support for audit paths, integrity verification, and key rotation
 *
 * MCEL is intended to serve as an integrity spine for higher-level systems
 * such as digital identity frameworks, compliance and evidence ledgers,
 * authorization workflows, and regulated institutional records.
 * Payload semantics are intentionally opaque to the ledger, allowing
 * application-specific object models to evolve independently.
 *
 * The implementation assumes a trusted storage backend providing append
 * semantics and optional overwrite support for the current ledger head.
 * All security guarantees derive from cryptographic verification rather
 * than trust in storage correctness.
 */
 
#ifndef MCEL_H
#define MCEL_H
 
#include "mcelcommon.h"
 
#if (!defined(MCEL_CONFIG_DILITHIUM) && !defined(MCEL_CONFIG_SPHINCSPLUS))
#   define MCEL_CONFIG_DILITHIUM
#endif
 
#if defined(MCEL_CONFIG_DILITHIUM)
#   include "dilithium.h"
#elif defined(MCEL_CONFIG_SPHINCSPLUS)
#   include "sphincsplus.h"
#else
#   error Invalid parameter set!
#endif

#define MCEL_USE_RCS_ENCRYPTION

#if defined(MCEL_USE_RCS_ENCRYPTION)
#   include "rcs.h"
#   define mcel_cipher_state qsc_rcs_state
#   define mcel_cipher_dispose qsc_rcs_dispose
#   define mcel_cipher_initialize qsc_rcs_initialize
#   define mcel_cipher_keyparams qsc_rcs_keyparams
#   define mcel_cipher_set_associated qsc_rcs_set_associated
#   define mcel_cipher_transform qsc_rcs_transform
#else
#   include "aes.h"
#   define mcel_cipher_state qsc_aes_gcm256_state
#   define mcel_cipher_dispose qsc_aes_gcm256_dispose
#   define mcel_cipher_initialize qsc_aes_gcm256_initialize
#   define mcel_cipher_keyparams qsc_aes_keyparams
#   define mcel_cipher_set_associated qsc_aes_gcm256_set_associated
#   define mcel_cipher_transform qsc_aes_gcm256_transform
#endif

 
#if defined(MCEL_CONFIG_DILITHIUM)
#   define MCEL_ASYMMETRIC_SIGNING_KEY_SIZE (QSC_DILITHIUM_PRIVATEKEY_SIZE)

#   define MCEL_ASYMMETRIC_VERIFY_KEY_SIZE (QSC_DILITHIUM_PUBLICKEY_SIZE)

#   define MCEL_ASYMMETRIC_SIGNATURE_SIZE (QSC_DILITHIUM_SIGNATURE_SIZE)
 
#   if defined(QSC_DILITHIUM_S1P44)
#       define MCEL_PARAMETER_SET 1U
#   elif defined(QSC_DILITHIUM_S3P65)
#       define MCEL_PARAMETER_SET 2U
#   elif defined(QSC_DILITHIUM_S5P87)
#       define MCEL_PARAMETER_SET 3U
#   else
#       error "The parameter set is not supported!"
#   endif
#   define mcel_signature_generate_keypair qsc_dilithium_generate_keypair
#   define mcel_signature_sign qsc_dilithium_sign
#   define mcel_signature_verify qsc_dilithium_verify
#else
#   define MCEL_ASYMMETRIC_SIGNING_KEY_SIZE (QSC_SPHINCSPLUS_PRIVATEKEY_SIZE)

#   define MCEL_ASYMMETRIC_VERIFY_KEY_SIZE (QSC_SPHINCSPLUS_PUBLICKEY_SIZE)

#   define MCEL_ASYMMETRIC_SIGNATURE_SIZE (QSC_SPHINCSPLUS_SIGNATURE_SIZE)

#   if defined(QSC_SPHINCSPLUS_S1S128SHAKERS)
#       define MCEL_PARAMETER_SET 4U
#   elif defined(QSC_SPHINCSPLUS_S3S192SHAKERS)
#       define MCEL_PARAMETER_SET 5U
#   elif defined(QSC_SPHINCSPLUS_S5S256SHAKERS)
#       define MCEL_PARAMETER_SET 6U
#   elif defined(QSC_SPHINCSPLUS_S6S512SHAKERS)
#       define MCEL_PARAMETER_SET 7U
#   else
#       error "The parameter set is not supported!"
#   endif

#   define udif_signature_generate_keypair qsc_sphincsplus_generate_keypair
#   define udif_signature_sign qsc_sphincsplus_sign
#   define udif_signature_verify qsc_sphincsplus_verify
#endif

#define MCEL_BLOCK_HASH_SIZE 32U

#define MCEL_BLOCK_HEADER_ENCODED_SIZE 62U

#define MCEL_BLOCK_ENCODED_FIXED_SIZE ((size_t)MCEL_BLOCK_HEADER_ENCODED_SIZE + ((size_t)MCEL_BLOCK_HASH_SIZE * 2U))

#define MCEL_BLOCK_KEYID_SIZE 32U

#define MCEL_BLOCK_VERSION 1U

#define MCEL_CHECKPOINT_HEADER_ENCODED_SIZE 62U

#define MCEL_CHECKPOINT_BUNDLE_FIXED_SIZE (MCEL_CHECKPOINT_HEADER_ENCODED_SIZE + (MCEL_BLOCK_HASH_SIZE * 2U))

#define MCEL_CHECKPOINT_BUNDLE_ENCODED_SIZE (MCEL_ASYMMETRIC_SIGNATURE_SIZE + MCEL_BLOCK_HASH_SIZE + MCEL_CHECKPOINT_BUNDLE_FIXED_SIZE)

#define MCEL_CHECKPOINT_KEYID_SIZE 32U

#define MCEL_CHECKPOINT_SIGNED_COMMIT_SIZE (MCEL_ASYMMETRIC_SIGNATURE_SIZE + MCEL_BLOCK_HASH_SIZE)

#define MCEL_CHECKPOINT_VERSION 1U

#define MCEL_KEYROTATE_PAYLOAD_VERSION 0x01U

#define MCEL_KEYROTATE_PAYLOAD_FIXED_SIZE (1U + 1U + (uint32_t)MCEL_CHECKPOINT_KEYID_SIZE + 2U)

#define MCEL_KEYROTATE_PAYLOAD_KEY_SIZE (MCEL_KEYROTATE_PAYLOAD_FIXED_SIZE + MCEL_ASYMMETRIC_VERIFY_KEY_SIZE)

#define MCEL_LEDGER_NAMESPACE_ID_MAX 64U

#define MCEL_PAYLOAD_MAX_SIZE 0xFFFFFFFFUL

#define MCEL_RCS256_KEY_SIZE 32U

#define MCEL_RCS256_MAC_SIZE 32U

#define MCEL_RCS_NONCE_SIZE 32U

#define MCEL_RCS_INFO_SIZE 48U

#define MCEL_RECORD_FLAG_ENCRYPTED 0x01U

#define MCEL_RECORD_VERSION 1U

#define MCEL_RECORD_KEYID_SIZE 32U

#define MCEL_RECORD_HEADER_ENCODED_SIZE 58U

#define MCEL_RECORD_TYPE_KEYROTATE 0x3U

#define MCEL_SIGNED_HASH_SIZE (MCEL_ASYMMETRIC_SIGNATURE_SIZE + MCEL_BLOCK_HASH_SIZE)

#if defined(QSC_SYSTEM_OS_WINDOWS)
#   define MCEL_STORE_LOC_BLOCKS "mcel\\blocks"
#else
#   define MCEL_STORE_LOC_BLOCKS "mcel/blocks"
#endif

#if defined(QSC_SYSTEM_OS_WINDOWS)
#   define MCEL_STORE_LOC_CHECKPOINTS "mcel\\checkpoints"
#else
#   define MCEL_STORE_LOC_CHECKPOINTS "mcel/checkpoints"
#endif

#if defined(QSC_SYSTEM_OS_WINDOWS)
#   define MCEL_STORE_LOC_HEAD "mcel\\head"
#else
#   define MCEL_STORE_LOC_HEAD "mcel/head"
#endif

#if defined(QSC_SYSTEM_OS_WINDOWS)
#   define MCEL_STORE_LOC_RECORDS "mcel\\records"
#else
#   define MCEL_STORE_LOC_RECORDS "mcel/records"
#endif

MCEL_EXPORT_API  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           
} mcel_record_types;

MCEL_EXPORT_API enum mcel_policy_ops
{
    mcel_policyop_append_record = 1U,        
    mcel_policyop_seal_checkpoint = 2U     
} mcel_policy_ops;

MCEL_EXPORT_API 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     
} mcel_policy_errors;

MCEL_EXPORT_API typedef struct mcel_store_callbacks
{
    void* context; 

    bool (*write)(void* context, const uint8_t* loc, size_t loclen, const uint8_t* data, size_t datalen);

    bool (*read)(void* context, const uint8_t* loc, size_t loclen, uint8_t* data, size_t datalen, size_t* outread);

    bool (*append)(void* context, const uint8_t* loc, size_t loclen, const uint8_t* data, size_t datalen, uint64_t* outpos);

    bool (*size)(void* context, const uint8_t* loc, size_t loclen, uint64_t* outlen);

    bool (*flush)(void* context, const uint8_t* loc, size_t loclen);
} mcel_store_callbacks;

MCEL_EXPORT_API typedef struct mcel_block_header
{
    uint8_t keyid[MCEL_BLOCK_KEYID_SIZE]; 
    uint64_t block_sequence;              
    uint64_t first_record_seq;              
    uint64_t timestamp;                        
    uint32_t record_count;                  
    uint8_t flags;                         
    uint8_t version;                     
} mcel_block_header;

MCEL_EXPORT_API typedef struct mcel_checkpoint_audit_item
{
    const uint8_t* bundle;                  
    size_t bundlelen;                      
} mcel_checkpoint_audit_item;

MCEL_EXPORT_API typedef struct mcel_checkpoint_header
{
    uint8_t keyid[MCEL_CHECKPOINT_KEYID_SIZE]; 
    uint64_t chk_sequence;                  
    uint64_t first_record_seq;              
    uint64_t timestamp;                     
    uint32_t record_count;                  
    uint8_t flags;                          
    uint8_t version;                        
} mcel_checkpoint_header;

MCEL_EXPORT_API typedef struct mcel_ledger_state
{
    mcel_store_callbacks store;                
    uint8_t nsid[MCEL_LEDGER_NAMESPACE_ID_MAX]; 
    size_t nsidlen;                         
    const uint8_t* publickey;               
    uint8_t head_commit[MCEL_BLOCK_HASH_SIZE]; 
    mcel_checkpoint_header head_header;     
    uint8_t have_head;                      
} mcel_ledger_state;

MCEL_EXPORT_API typedef struct mcel_policy
{
    size_t max_payload_size;                
    uint32_t allowed_record_mask;            
    uint8_t require_encryption;               
    uint8_t enforce_monotonic_time;           
    uint8_t enforce_monotonic_seq;         
    uint8_t enforce_keyid_link;               
} mcel_policy;

MCEL_EXPORT_API typedef struct mcel_policy_context
{
    uint8_t have_checkpoint;             
    mcel_checkpoint_header checkpoint;      
    uint64_t last_record_sequence;          
    uint64_t last_record_timestamp;            
} mcel_policy_context;

MCEL_EXPORT_API typedef struct mcel_record_header
{
    uint8_t keyid[MCEL_RECORD_KEYID_SIZE];   
    uint64_t sequence;                       
    uint64_t timestamp;                      
    uint32_t payload_len;                    
    uint32_t type;                           
    uint8_t flags;                           
    uint8_t version;                         
} mcel_record_header;

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

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);

MCEL_EXPORT_API size_t mcel_block_encoded_size(size_t reccount);

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

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);

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);

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);

MCEL_EXPORT_API size_t mcel_checkpoint_bundle_encoded_size(size_t siglen);

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);

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);

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

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);

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

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

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

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));

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));

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

MCEL_EXPORT_API size_t mcel_keyrotate_payload_size(size_t pubkeylen);

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);

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);

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

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);

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);

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);

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);

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

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);

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);

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);

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

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

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