capability.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
 */
 
#ifndef UDIF_CAPABILITY_H
#define UDIF_CAPABILITY_H
 
#include "udif.h"


#define UDIF_CAP_QUERY_EXIST (UINT64_C(1) << 0)

#define UDIF_CAP_QUERY_OWNER_BINDING (UINT64_C(1) << 1)

#define UDIF_CAP_QUERY_ATTR_BUCKET (UINT64_C(1) << 2)

#define UDIF_CAP_PROVE_MEMBERSHIP (UINT64_C(1) << 3)

#define UDIF_CAP_FORWARD_QUERY (UINT64_C(1) << 4)

#define UDIF_CAP_ADMIN_ENROLL (UINT64_C(1) << 5)

#define UDIF_CAP_ADMIN_SUSPEND (UINT64_C(1) << 6)

#define UDIF_CAP_ADMIN_RESUME (UINT64_C(1) << 7)

#define UDIF_CAP_ADMIN_REVOKE (UINT64_C(1) << 8)

#define UDIF_CAP_ADMIN_BRANCH_CREATE (UINT64_C(1) << 9)

#define UDIF_CAP_ADMIN_BRANCH_RETIRE (UINT64_C(1) << 10)

#define UDIF_CAP_REGISTRY_COMMIT (UINT64_C(1) << 11)

#define UDIF_CAP_TX_CREATE (UINT64_C(1) << 12)

#define UDIF_CAP_TX_ACCEPT (UINT64_C(1) << 13)

#define UDIF_CAP_LOG_ANCHOR_SEND (UINT64_C(1) << 14)

#define UDIF_CAP_LOG_ANCHOR_VERIFY (UINT64_C(1) << 15)

#define UDIF_CAP_TREATY_NEGOTIATE (UINT64_C(1) << 16)

#define UDIF_CAP_TREATY_QUERY_EXEC (UINT64_C(1) << 17)

#define UDIF_CAP_TREATY_QUERY_ORIGIN (UINT64_C(1) << 18)

#define UDIF_CAP_TELEMETRY_EXPORT (UINT64_C(1) << 19)

#define UDIF_CAP_ERROR_REPORT (UINT64_C(1) << 20)

#define UDIF_CAP_RESERVED_FUTURE_CORE_MASK (UINT64_C(0x00000000FFE00000))

#define UDIF_CAP_RESERVED_PROFILE_MASK (UINT64_C(0xFFFFFFFF00000000))

#define UDIF_CAP_QUERY_MASK \
    (UDIF_CAP_QUERY_EXIST | \
     UDIF_CAP_QUERY_OWNER_BINDING | \
     UDIF_CAP_QUERY_ATTR_BUCKET | \
     UDIF_CAP_PROVE_MEMBERSHIP)

#define UDIF_CAP_ADMIN_MASK \
    (UDIF_CAP_ADMIN_ENROLL | \
     UDIF_CAP_ADMIN_SUSPEND | \
     UDIF_CAP_ADMIN_RESUME | \
     UDIF_CAP_ADMIN_REVOKE | \
     UDIF_CAP_ADMIN_BRANCH_CREATE | \
     UDIF_CAP_ADMIN_BRANCH_RETIRE)

#define UDIF_CAP_TRANSACTION_MASK \
    (UDIF_CAP_REGISTRY_COMMIT | \
     UDIF_CAP_TX_CREATE | \
     UDIF_CAP_TX_ACCEPT)

#define UDIF_CAP_ANCHOR_MASK \
    (UDIF_CAP_LOG_ANCHOR_SEND | \
     UDIF_CAP_LOG_ANCHOR_VERIFY)

#define UDIF_CAP_TREATY_MASK \
    (UDIF_CAP_TREATY_NEGOTIATE | \
     UDIF_CAP_TREATY_QUERY_EXEC | \
     UDIF_CAP_TREATY_QUERY_ORIGIN)

#define UDIF_CAP_AUDIT_MASK \
    (UDIF_CAP_TELEMETRY_EXPORT | \
     UDIF_CAP_ERROR_REPORT)
 

#define UDIF_ROOT_CAPABILITIES \
    (UDIF_CAP_ADMIN_ENROLL | \
     UDIF_CAP_ADMIN_SUSPEND | \
     UDIF_CAP_ADMIN_RESUME | \
     UDIF_CAP_ADMIN_REVOKE | \
     UDIF_CAP_ADMIN_BRANCH_CREATE | \
     UDIF_CAP_ADMIN_BRANCH_RETIRE | \
     UDIF_CAP_LOG_ANCHOR_VERIFY)

#define UDIF_BC_CAPABILITIES \
    (UDIF_CAP_FORWARD_QUERY | \
     UDIF_CAP_ADMIN_ENROLL | \
     UDIF_CAP_ADMIN_SUSPEND | \
     UDIF_CAP_ADMIN_RESUME | \
     UDIF_CAP_ADMIN_REVOKE | \
     UDIF_CAP_ADMIN_BRANCH_CREATE | \
     UDIF_CAP_ADMIN_BRANCH_RETIRE | \
     UDIF_CAP_LOG_ANCHOR_SEND | \
     UDIF_CAP_LOG_ANCHOR_VERIFY | \
     UDIF_CAP_TELEMETRY_EXPORT | \
     UDIF_CAP_ERROR_REPORT)

#define UDIF_GC_CAPABILITIES \
    (UDIF_CAP_FORWARD_QUERY | \
     UDIF_CAP_ADMIN_ENROLL | \
     UDIF_CAP_ADMIN_SUSPEND | \
     UDIF_CAP_ADMIN_RESUME | \
     UDIF_CAP_ADMIN_REVOKE | \
     UDIF_CAP_REGISTRY_COMMIT | \
     UDIF_CAP_LOG_ANCHOR_SEND | \
     UDIF_CAP_TELEMETRY_EXPORT | \
     UDIF_CAP_ERROR_REPORT)

#define UDIF_CLIENT_CAPABILITIES \
    (UDIF_CAP_QUERY_EXIST | \
     UDIF_CAP_QUERY_OWNER_BINDING | \
     UDIF_CAP_QUERY_ATTR_BUCKET | \
     UDIF_CAP_PROVE_MEMBERSHIP | \
     UDIF_CAP_REGISTRY_COMMIT | \
     UDIF_CAP_TX_CREATE | \
     UDIF_CAP_TX_ACCEPT | \
     UDIF_CAP_ERROR_REPORT)

#define UDIF_CAP_CORE_DEFINED_MASK \
    (UDIF_CAP_QUERY_EXIST | \
     UDIF_CAP_QUERY_OWNER_BINDING | \
     UDIF_CAP_QUERY_ATTR_BUCKET | \
     UDIF_CAP_PROVE_MEMBERSHIP | \
     UDIF_CAP_FORWARD_QUERY | \
     UDIF_CAP_ADMIN_ENROLL | \
     UDIF_CAP_ADMIN_SUSPEND | \
     UDIF_CAP_ADMIN_RESUME | \
     UDIF_CAP_ADMIN_REVOKE | \
     UDIF_CAP_ADMIN_BRANCH_CREATE | \
     UDIF_CAP_ADMIN_BRANCH_RETIRE | \
     UDIF_CAP_REGISTRY_COMMIT | \
     UDIF_CAP_TX_CREATE | \
     UDIF_CAP_TX_ACCEPT | \
     UDIF_CAP_LOG_ANCHOR_SEND | \
     UDIF_CAP_LOG_ANCHOR_VERIFY | \
     UDIF_CAP_TREATY_NEGOTIATE | \
     UDIF_CAP_TREATY_QUERY_EXEC | \
     UDIF_CAP_TREATY_QUERY_ORIGIN | \
     UDIF_CAP_TELEMETRY_EXPORT | \
     UDIF_CAP_ERROR_REPORT)

#define UDIF_TREATY_ORIGIN_CAPABILITIES (UDIF_CAP_FORWARD_QUERY | UDIF_CAP_TREATY_QUERY_ORIGIN)

#define UDIF_TREATY_EXEC_CAPABILITIES (UDIF_CAP_TREATY_QUERY_EXEC)

#define UDIF_TREATY_ADMIN_CAPABILITIES (UDIF_CAP_TREATY_NEGOTIATE)

#define UDIF_CAP_NONE (UINT64_C(0))

#define UDIF_CAP_ALL_CORE (UDIF_CAP_CORE_DEFINED_MASK)

#define UDIF_CAPABILITY_POLICY_SIZE 8U

#define UDIF_CAPABILITY_ENCODED_SIZE (UDIF_CRYPTO_HASH_SIZE + \
    UDIF_CRYPTO_MAC_SIZE + \
    UDIF_SERIAL_NUMBER_SIZE + \
    UDIF_SERIAL_NUMBER_SIZE + \
    UDIF_CAPABILITY_BITMAP_SIZE + \
    UDIF_VALID_TIME_SIZE + \
    UDIF_CAPABILITY_BITMAP_SIZE + \
    UDIF_CAPABILITY_POLICY_SIZE)

#define UDIF_CAPABILITY_SIGNED_SIZE (UDIF_SERIAL_NUMBER_SIZE + \
    UDIF_SERIAL_NUMBER_SIZE + \
    UDIF_CAPABILITY_BITMAP_SIZE + \
    UDIF_VALID_TIME_SIZE + \
    UDIF_CAPABILITY_BITMAP_SIZE + \
    UDIF_CAPABILITY_POLICY_SIZE)

UDIF_EXPORT_API typedef struct udif_capability
{
    uint8_t digest[UDIF_CRYPTO_HASH_SIZE];       
    uint8_t tag[UDIF_CRYPTO_MAC_SIZE];           
    uint8_t issuedby[UDIF_SERIAL_NUMBER_SIZE];   
    uint8_t issuedto[UDIF_SERIAL_NUMBER_SIZE];   
    uint64_t scopebitmap;                        
    uint64_t validto;                            
    uint64_t verbsbitmap;                        
    uint64_t policy;                          
} udif_capability;
 

 
static const char UDIF_CAPABILITY_ERROR_STRINGS[][UDIF_ERROR_STRING_SIZE] =
{
    "No error",
    "Capability denied by policy",
    "Empty capability mask",
    "Conflicting capability bits"
};


typedef enum udif_capability_id
{
    udif_capability_issue_certificate = 0x00U,  
    udif_capability_revoke_certificate = 0x01U,   
    udif_capability_issue_token = 0x02U,     
    udif_capability_validate_token = 0x03U,       
    udif_capability_register_issuer = 0x04U, 
    udif_capability_rotate_keys = 0x05U,     
    udif_capability_directory_query = 0x06U, 
    udif_capability_audit_logging_access = 0x07U,   
    udif_capability_admin = 0x08U              
} udif_capability_id;

typedef enum udif_capability_verbs
{
    udif_capability_query_exist = 0U,            
    udif_capability_query_owner_binding = 1U,    
    udif_capability_query_attr_bucket = 2U,        
    udif_capability_prove_membership = 3U,      
    udif_capability_forward_query = 4U,            
    udif_capability_admin_enroll = 5U,          
    udif_capability_admin_suspend = 6U,            
    udif_capability_admin_resume = 7U,          
    udif_capability_admin_revoke = 8U,          
    udif_capability_admin_branch_create = 9U,    
    udif_capability_admin_branch_retire = 10U,   
    udif_capability_registry_commit = 11U,       
    udif_capability_tx_create = 12U,            
    udif_capability_tx_accept = 13U,            
    udif_capability_logging_anchor_send = 14U,  
    udif_capability_logging_anchor_verify = 15U,
    udif_capability_treaty_negotiate = 16U,     
    udif_capability_treaty_query_exec = 17U,    
    udif_capability_treaty_query_origin = 18U,  
    udif_capability_telemetry_export = 19U,     
    udif_capability_error_report = 20U          
} udif_capability_verbs;

typedef enum udif_capability_scopes
{
    udif_scope_local = 0U,                      
    udif_scope_intra_domain = 1U,                
    udif_scope_treaty = 2U                     
} udif_capability_scopes;

#define UDIF_CAPABILITY_ALL UINT64_C(0x00000000001FFFFF)

UDIF_EXPORT_API bool udif_capability_allows_scope(const udif_capability* capability, uint32_t scope);

UDIF_EXPORT_API bool udif_capability_allows_verb(const udif_capability* capability, uint32_t verb);

UDIF_EXPORT_API void udif_capability_clear(udif_capability* capability);

UDIF_EXPORT_API udif_errors udif_capability_create(udif_capability* capability, uint32_t verbsbitmap, uint32_t scopebitmap, const uint8_t* issuedto,
    const uint8_t* issuedby, uint64_t validto, uint32_t policy, const uint8_t* issuerkey);

UDIF_EXPORT_API udif_errors udif_capability_compute_digest(uint8_t* digest, const udif_capability* capability);

UDIF_EXPORT_API udif_errors udif_capability_deserialize(udif_capability* capability, const uint8_t* input, size_t inplen);

UDIF_EXPORT_API bool udif_capability_grants_permission(const udif_capability* capability, uint32_t verb, uint32_t scope, uint64_t ctime);

UDIF_EXPORT_API bool udif_capability_is_expired(const udif_capability* capability, uint64_t ctime);

UDIF_EXPORT_API udif_errors udif_capability_serialize(uint8_t* output, size_t outlen, const udif_capability* capability);

UDIF_EXPORT_API bool udif_capability_verify(const udif_capability* capability, const uint8_t* issuerkey);
 
#endif