encoding.h

Go to the documentation of this file.

/* 2020-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 QSC_ENCODING_H
#define QSC_ENCODING_H
 
#include "qsccommon.h"
 
QSC_CPLUSPLUS_ENABLED_START

 
/* ========================================================================== */
/*                        BER Tag-Class Constants                             */
/* ========================================================================== */

#define QSC_ENCODING_BER_CLASS_UNIVERSAL 0x00U

#define QSC_ENCODING_BER_CLASS_APPLICATION 0x40U

#define QSC_ENCODING_BER_CLASS_CONTEXT_SPECIFIC 0x80U

#define QSC_ENCODING_BER_CLASS_PRIVATE 0xC0U

#define QSC_BER_ENCODING_INDEFINITE_LENGTH ((size_t)-1)
 
/* ========================================================================== */
/*                    Universal ASN.1 Tag-Number Enumeration                  */
/* ========================================================================== */

typedef enum
{
    BER_ASN1_EOC               = 0x00U, 
    BER_ASN1_BOOLEAN           = 0x01U, 
    BER_ASN1_INTEGER           = 0x02U, 
    BER_ASN1_BIT_STRING        = 0x03U, 
    BER_ASN1_OCTET_STRING      = 0x04U, 
    BER_ASN1_NULL              = 0x05U, 
    BER_ASN1_OBJECT_IDENTIFIER = 0x06U, 
    BER_ASN1_OBJECT_DESCRIPTOR = 0x07U, 
    BER_ASN1_EXTERNAL          = 0x08U, 
    BER_ASN1_REAL              = 0x09U, 
    BER_ASN1_ENUMERATED        = 0x0AU, 
    BER_ASN1_EMBEDDED_PDV      = 0x0BU, 
    BER_ASN1_UTF8_STRING       = 0x0CU, 
    BER_ASN1_RELATIVE_OID      = 0x0DU, 
    /* Tags 14 (0x0E) and 15 (0x0F) are reserved by X.680. */
    BER_ASN1_SEQUENCE          = 0x10U, 
    BER_ASN1_SET               = 0x11U, 
    BER_ASN1_NUMERIC_STRING    = 0x12U, 
    BER_ASN1_PRINTABLE_STRING  = 0x13U, 
    BER_ASN1_T61_STRING        = 0x14U, 
    BER_ASN1_VIDEOTEX_STRING   = 0x15U, 
    BER_ASN1_IA5_STRING        = 0x16U, 
    BER_ASN1_UTCTIME           = 0x17U, 
    BER_ASN1_GENERALIZEDTIME   = 0x18U, 
    BER_ASN1_GRAPHIC_STRING    = 0x19U, 
    BER_ASN1_VISIBLE_STRING    = 0x1AU, 
    BER_ASN1_GENERAL_STRING    = 0x1BU, 
    BER_ASN1_UNIVERSAL_STRING  = 0x1CU, 
    BER_ASN1_CHARACTER_STRING  = 0x1DU, 
    BER_ASN1_BMP_STRING        = 0x1EU  
} qsc_encoding_ber_asn1_tag_t;
 
/* ========================================================================== */
/*                         BER Element Structure                              */
/* ========================================================================== */

QSC_EXPORT_API typedef struct qsc_encoding_ber_element
{
    uint8_t tagclass;       
    bool constructed;       
    uint32_t tagnumber;     
    bool indefinite;        
    size_t length;          
    uint8_t* value;         
    struct qsc_encoding_ber_element** children; 
    size_t    ccount;       
} qsc_encoding_ber_element;
 
/* ========================================================================== */
/*                            Base64 Functions                                */
/* ========================================================================== */

QSC_EXPORT_API bool qsc_encoding_base64_decode(uint8_t* output, size_t otplen, const char* input, size_t inplen);

QSC_EXPORT_API size_t qsc_encoding_base64_decoded_size(const char* input, size_t length);

QSC_EXPORT_API bool qsc_encoding_base64_encode(char* output, size_t otplen, const uint8_t* input, size_t inplen);

QSC_EXPORT_API size_t qsc_encoding_base64_encoded_size(size_t length);

QSC_EXPORT_API bool qsc_encoding_base64_is_valid_char(char value);
 
/* ========================================================================== */
/*                           BER Decode Functions                             */
/* ========================================================================== */

QSC_EXPORT_API qsc_encoding_ber_element* qsc_encoding_ber_decode_element(const uint8_t* buffer, size_t buflen, size_t* consumed);

QSC_EXPORT_API size_t qsc_encoding_ber_decode_length(const uint8_t* buffer, size_t buflen, size_t* length, bool* indef);

QSC_EXPORT_API size_t qsc_encoding_ber_decode_tag(const uint8_t* buffer, size_t buflen, uint8_t* tagclass, bool* construct, uint32_t* tagnum);
 
/* ========================================================================== */
/*                           BER Encode Functions                             */
/* ========================================================================== */

QSC_EXPORT_API size_t qsc_encoding_ber_encode_element(qsc_encoding_ber_element* element, uint8_t* buffer, size_t buflen);

QSC_EXPORT_API size_t qsc_encoding_ber_encode_length(size_t length, uint8_t* buffer, size_t buflen);

QSC_EXPORT_API size_t qsc_encoding_ber_encode_tag(uint8_t tagclass, bool construct, uint32_t tagnum, uint8_t* buffer, size_t buflen);

QSC_EXPORT_API void qsc_encoding_ber_free_element(qsc_encoding_ber_element* element);
 
/* ========================================================================== */
/*                           DER Functions                                    */
/* ========================================================================== */

QSC_EXPORT_API qsc_encoding_ber_element* qsc_encoding_der_decode_element(const uint8_t* buffer, size_t buflen, size_t* consumed);

QSC_EXPORT_API size_t qsc_encoding_der_encode_element(qsc_encoding_ber_element* element, uint8_t* buffer, size_t buflen);
 
/* ========================================================================== */
/*                        Hexadecimal Functions                               */
/* ========================================================================== */

QSC_EXPORT_API bool qsc_encoding_hex_decode(const char* input, size_t inplen, uint8_t* output, size_t otplen, size_t* declen);

QSC_EXPORT_API bool qsc_encoding_hex_encode(const uint8_t* input, size_t inplen, char* output, size_t otplen);
 
/* ========================================================================== */
/*                           PEM Functions                                    */
/* ========================================================================== */

QSC_EXPORT_API bool qsc_encoding_pem_decode(const char* input, size_t inplen, uint8_t* output, size_t otplen, size_t* declen);

QSC_EXPORT_API bool qsc_encoding_pem_encode(const char* label, char* output, size_t otplen, const uint8_t* data, size_t datalen);
 
/* ========================================================================== */
/*                          Debug Self-Test Function                          */
/* ========================================================================== */
 
#if defined(QSC_DEBUG_MODE)
QSC_EXPORT_API bool qsc_encoding_tests(void);
#endif
 
QSC_CPLUSPLUS_ENABLED_END
 
#endif