Main documentation page for the QSC Library.

QSC (Quantum Secure Cryptographic Solutions) is a compact, self-contained, and highly optimized cryptographic library written in C23. It is designed to provide next-generation, post-quantum secure cryptographic primitives for applications requiring long-term security against both classical and quantum adversaries. The library adheres to MISRA secure coding standards and is structured for clarity, ease of verification, and integration into secure communication platforms, including public-internet TLS stacks and PKI certificate infrastructure.

Overview: The QSC Library provides a comprehensive suite of cryptographic algorithms, a complete X.509 certificate infrastructure, and a broad set of system utilities:

Asymmetric Cryptography

Key Encapsulation Mechanisms (KEM):

ML-KEM (Kyber): Module-LWE based key encapsulation, NIST FIPS-203. Parameter sets ML-KEM-512, ML-KEM-768, and ML-KEM-1024. AVX2-accelerated implementations available.
Classic McEliece: Niederreiter dual-form code-based KEM, NIST PQC Round 3.
HQC: QC-MDPC code-based KEM, NIST PQC Round 4. AVX2-accelerated implementations available.
ECDH (X25519): Elliptic Curve Diffie-Hellman key exchange over Curve25519, RFC 7748.

Digital Signature Schemes:

ML-DSA (Dilithium): Module-lattice based signatures, NIST FIPS-204. Parameter sets ML-DSA-44, ML-DSA-65, and ML-DSA-87. AVX2-accelerated implementations available.
SLH-DSA (SPHINCS+): Stateless hash-based signatures, NIST FIPS-205.
Falcon: NTRU lattice-based compact signatures, NIST PQC Round 3. AVX2-accelerated implementations available.
ECDSA (P-256 / P-384 / P-521): Elliptic curve signatures over NIST P-256 (secp256r1), P-384 (secp384r1), and P-521 (secp521r1). RFC 6979 deterministic nonce generation (HMAC-SHA256, HMAC-SHA384, and HMAC-SHA512 respectively). Jacobian projective coordinates with Solinas and Barrett reduction. Interoperable with TLS 1.2/1.3 and public CA certificates. Standards: FIPS 186-5, RFC 6979, RFC 8422.
EdDSA (Ed25519): Edwards-curve digital signatures, RFC 8032.

Symmetric Cryptography

Authenticated Encryption (AEAD):

RCS: Wide-block Rijndael-based authenticated stream cipher with KMAC or QMAC authentication; 256-bit and 512-bit key variants. A proprietary QRCS construction.
CSX-512: ChaCha-derived authenticated stream cipher with 512-bit keys and KMAC or QMAC authentication. A proprietary QRCS construction.
AES-GCM: AES in Galois/Counter Mode (GMAC authentication); combines AES-CTR with GMAC.
AES-HBA: AES in Hash-Based Authentication mode; combines AES-CTR with KMAC authentication.

Classical Symmetric Ciphers:

AES: CBC, CTR, ECB, GCM, and HBA modes; hardware-accelerated via AES-NI and SIMD. FIPS-197, SP 800-38A/D.
ChaCha20-Poly1305: Standard 256-bit ChaCha stream cipher with Poly1305 MAC.

Hash Functions and MACs

SHA3: SHA3-256 and SHA3-512 (FIPS-202); SHAKE-128, SHAKE-256, and cSHAKE variants.
SHA2: SHA2-256 and SHA2-512 (FIPS-180-4).
KMAC: Keccak-based message authentication code (FIPS-202).
QMAC: Wide-block GF(2^256) polynomial MAC. A proprietary QRCS construction.
HMAC: SHA2-256 and SHA2-512 variants (FIPS-198-1).
Poly1305: High-speed Bernstein MAC.
GMAC: Galois/Counter Mode MAC.

Deterministic Random Bit Generators and Entropy

CSG: cSHAKE-based auto-seeding DRBG (csg.h).
HCG: HMAC-SHA2-based auto-seeding DRBG (hcg.h).
SHAKE / cSHAKE: FIPS-202 extensible output functions for key derivation and DRBG seeding.
SCB: SHAKE Cost-Based KDF; memory-hard passphrase derivation with configurable CPU and memory cost parameters. A proprietary QRCS construction (scb.h).
HKDF: Extract-and-expand KDF using HMAC-SHA2-256 and HMAC-SHA2-512.
ACP: Auto Entropy Collection Provider; aggregates multiple entropy sources (acp.h).
CSP: OS-native cryptographic entropy provider (csp.h).
RDP: Hardware entropy via Intel RDRAND and RDSEED (rdp.h).

X.509 Certificate Infrastructure: QSC provides a complete, dependency-free X.509 PKI layer covering the full certificate lifecycle. The implementation is built on a strict DER/BER-capable ASN.1 engine and enforces the requirements of RFC 5280, X.690, and RFC 6125. Both classical ECDSA and post-quantum ML-DSA certificate profiles are supported natively.

Parsing and Decoding:

x509cert.h: DER-encoded X.509 certificate decoder. Populates a qsc_x509_certificate structure and preserves the raw TBSCertificate span for signature verification without re-serialisation.
x509name.h: Issuer and subject Name parsing; decodes relative distinguished name sequences into typed attribute lists; supports multi-valued RDNs; RFC 5280 §7.1 canonical comparison with Unicode NFC normalisation.
x509time.h: Decodes ASN.1 UTCTime and GeneralizedTime into normalised qsc_x509_time structures; provides validity interval comparison.
x509spki.h: Decodes SubjectPublicKeyInfo for ECDSA (P-256, P-384, P-521), ML-DSA (44/65/87), and ML-KEM (512/768/1024) key types; validates key sizes against expected parameter set sizes.
x509sig.h: Decodes certificate signature AlgorithmIdentifiers for ECDSA and ML-DSA profiles; unpacks ECDSA DER SEQUENCE(INTEGER, INTEGER) signatures into fixed-width buffers; validates ML-DSA signature length against the active parameter set.
x509ext.h: Decodes and queries all standard certificate extensions: BasicConstraints, KeyUsage, ExtendedKeyUsage, SubjectKeyIdentifier, AuthorityKeyIdentifier, SubjectAltName, IssuerAltName, CRLDistributionPoints, AuthorityInfoAccess, SubjectInfoAccess, and CertificatePolicies.
x509crl.h: X.509 CRL parsing and entry lookup; decodes v1 and v2 CRLs including cRLNumber, deltaCRLIndicator, issuingDistributionPoint, and per-entry reasonCode and invalidityDate extensions.
x509csr.h: PKCS#10 certificate signing request decoding and verification.
x509pem.h: PEM decoding for certificates, CRLs, CSRs, PKCS#8 private keys, SEC 1 EC keys, and ML-DSA/ML-KEM key types; multi-certificate PEM bundle support.

Certificate and CRL Generation:

x509certwrite.h: X.509 v3 certificate builder and signing interface; constructs TBSCertificate fields, attaches extensions, signs with a caller-supplied private key, and produces DER or PEM output.
x509crlwrite.h: X.509 CRL builder, signing, and PEM encoding interface; constructs TBSCertList fields and adds revocation entries with optional reason codes.
x509csr.h: PKCS#10 CSR encoding; constructs certification requests from a SubjectPublicKeyInfo and Distinguished Name and signs with a caller-supplied key.
x509write.h: Low-level ASN.1 DER writing helpers for primitive values, composite objects, SPKI structures, and standard extension payloads; used internally by the certificate and CRL builders.

Verification and Trust:

x509verify.h: Semantic certificate verification; TBSCertificate/outer signature algorithm consistency; validity interval evaluation; issuer-subject name linkage; BasicConstraints and KeyUsage enforcement for CAs; KEM-key/CA-flag conflict detection; path length constraint enforcement; duplicate extension detection; RFC 6125-compliant hostname and IP address matching; critical extension enforcement; revocation integration.
x509sigver.h: Binds the verification layer to QSC's ECDSA (P-256/P-384/P-521) and ML-DSA (44/65/87) signature APIs; implements qsc_x509_signature_verify_callback for use with qsc_x509_certificate_verify and qsc_x509_chain_verify.
x509host.h: RFC 6125-compliant DNS name matching with wildcard support and IDNA guard; IPv4 and IPv6 address matching against SubjectAltName IP entries; CN fallback suppressed whenever any SAN extension is present.
x509store.h: Trust-anchor store and certificate chain construction; manages qsc_x509_trust_anchor records; provides chain anchoring, self-signed detection, and anchor lookup used by qsc_x509_chain_verify.

Revocation:

x509rev.h: Unified revocation policy interface integrating CRL and OCSP status checking; supports REQUIRE_VALID_CRL, BEST_EFFORT, and DISABLED revocation modes.
x509revext.h: Extended revocation helpers for delta-CRL application and stapled OCSP verification; applies delta CRLs against a base CRL and validates OCSP staple tokens.
x509ocsp.h: OCSP response parsing and online certificate status validation; decodes BasicOCSPResponse, verifies the responder signature, and maps the result to a qsc_x509_revocation_status value.
x509aia.h: Decodes and queries the AuthorityInfoAccess and SubjectInfoAccess extensions; extracts OCSP responder URIs and CA Issuers URIs for online revocation and chain building.

Key and Bundle Management:

x509key.h: Private key decoding, size validation, and certificate-key matching for PKCS#8 OneAsymmetricKey and SEC 1 ECPrivateKey structures covering ECDSA and ML-DSA key types.
x509keywrite.h: Private key encoding and PEM conversion; serialises ECDSA and ML-DSA private keys to PKCS#8 DER or SEC 1 DER and wraps the result in PEM armour.
x509pkcs12.h: PKCS#12 bundle parsing and encrypted private-key decryption; decodes PFX structures containing certificate chains and password-protected private keys using AES-256-CBC or 3DES.
x509pem.h: PEM encoding for certificates, CRLs, CSRs, PKCS#8 private keys, SEC 1 EC keys, and ML-DSA/ML-KEM key types.

Supported Certificate Signature Profiles:

Profile	Signature OID	Public Key Type	Parameter
ecdsa-with-SHA256	1.2.840.10045.4.3.2	id-ecPublicKey	prime256v1 (P-256)
ecdsa-with-SHA384	1.2.840.10045.4.3.3	id-ecPublicKey	secp384r1 (P-384)
ecdsa-with-SHA512	1.2.840.10045.4.3.4	id-ecPublicKey	secp521r1 (P-521)
id-ML-DSA-44	2.16.840.1.101.3.4.3.17	id-ML-DSA-44	ML-DSA parameter 44
id-ML-DSA-65	2.16.840.1.101.3.4.3.18	id-ML-DSA-65	ML-DSA parameter 65
id-ML-DSA-87	2.16.840.1.101.3.4.3.19	id-ML-DSA-87	ML-DSA parameter 87

ASN.1 and Encoding Infrastructure:

encoding.h: Full BER and DER encode/decode engine with correct definite-length constructed element handling; Base64, hex, and PEM encoding primitives. Strict X.690 compliance: rejects indefinite-length encodings in DER contexts; enforces minimal INTEGER encoding; validates unused-bits fields in BIT STRINGs.
asn1.h: Typed decoding helpers built on encoding.h; strict DER BOOLEAN enforcement (0x00 / 0xFF only); OID first-arc validation (arcs 0-2 per X.660); full 64-bit unsigned INTEGER support including 9-byte representations; sequence and set structural validators.
oid.h: OID registry with encoded values, dotted-decimal names, and descriptive strings for all algorithm and extension identifiers used by the X.509 layer.
x509types.h: Normalised in-memory structures for all X.509 objects; buffer constants sized for the largest current PQC profile (ML-DSA-87: 4627-byte signature, 2592-byte public key).

System Utilities

Memory, Data, and File Management:

memutils.h: SIMD-optimised memory operations: copy, clear, XOR, compare, and secure erase.
arrayutils.h: Byte array manipulation and conversion utilities.
stringutils.h: Safe string handling and conversion functions.
intutils.h: Integer endian conversion, bit manipulation, and arithmetic helpers.
donna128.h: Portable 128-bit integer arithmetic.
fileutils.h: File I/O, size, existence, and path operations.
folderutils.h: Directory creation, enumeration, and management.
qsort.h: Constant-time and standard quicksort implementations.

Encoding Utilities:

encoding.h: BER/DER engine; Base64 encode/decode (RFC 4648); hex encode/decode; PEM encode/decode with header/footer label validation (RFC 7468).

Networking:

socket.h, socketbase.h, socketflags.h: Cross-platform TCP/IP socket primitives.
netutils.h: Network address resolution and interface utilities.
socketclient.h: Asynchronous TCP socket client.
socketserver.h: High-performance asynchronous multi-threaded TCP socket server.
ipinfo.h: Local and remote IP address information queries.

Concurrency and System:

async.h: Asynchronous task execution.
threadpool.h: Managed thread pool for concurrent workloads.
cpuidex.h: CPU feature detection (SIMD capability, cache topology, RDRAND availability).
sysutils.h: OS version, memory, and processor statistics.
timerex.h: High-resolution performance timers.
timestamp.h: UTC and local timestamp generation.
event.h: Synchronisation event primitives.
consoleutils.h: Console input/output and formatting helpers.
winutils.h: Windows-specific platform utilities.

Data Structures:

collection.h: Keyed generic collection (dictionary/map).
list.h: Dynamic generic list.
queue.h: Generic FIFO queue.

Self-Test:

selftest.h: Built-in integrity and performance verification routines for all cryptographic primitives.

Architecture and Performance

QSC uses a dual implementation strategy for all performance-critical algorithms:

Reference path: Clean, portable C23 code that compiles on any conforming compiler, providing a readable and auditable baseline.
SIMD-optimised path: AVX, AVX2, and AVX-512 intrinsic implementations that activate automatically when the appropriate instruction set is enabled at compile time. Acceleration is applied across AES (AES-NI), RCS, CSX, SHA3/SHAKE/Keccak, ML-KEM, ML-DSA, Falcon, SLH-DSA, HQC, and all memory utility operations.

The ECDSA P-256, P-384, and P-521 implementations use Jacobian projective coordinates with the a=-3 doubling shortcut, Solinas reduction for field arithmetic, and Barrett reduction for scalar arithmetic mod n. RFC 6979 deterministic nonce generation means no entropy source is required during signing.

Supported Platforms

QSC has been thoroughly tested on:

Windows 10 / 11 / Server (Visual Studio 2022, MSVC v143+)
Ubuntu Linux (GCC 11+)
macOS (Apple Clang via Xcode 14+)

References and Standards

NIST FIPS-202 (SHA-3/SHAKE): https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf
NIST FIPS-203 (ML-KEM / Kyber): https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf
NIST FIPS-204 (ML-DSA / Dilithium): https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.204.pdf
NIST FIPS-205 (SLH-DSA / SPHINCS+): https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.205.pdf
NIST FIPS-197 (AES): https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197.pdf
NIST FIPS-180-4 (SHA-2): https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf
NIST FIPS-186-5 (ECDSA): https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf
NIST FIPS-198-1 (HMAC): https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.198-1.pdf
NIST SP 800-38A/D (AES modes): https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38a.pdf
RFC 5280 (X.509 Certificates): https://www.rfc-editor.org/rfc/rfc5280
RFC 6125 (Hostname Verification): https://www.rfc-editor.org/rfc/rfc6125
RFC 6960 (OCSP): https://www.rfc-editor.org/rfc/rfc6960
RFC 6979 (Deterministic ECDSA): https://www.rfc-editor.org/rfc/rfc6979
RFC 7468 (PEM Formats): https://www.rfc-editor.org/rfc/rfc7468
RFC 7748 (X25519 / ECDH): https://www.rfc-editor.org/rfc/rfc7748
RFC 8032 (EdDSA / Ed25519): https://www.rfc-editor.org/rfc/rfc8032
RFC 8422 (ECDSA in TLS): https://www.rfc-editor.org/rfc/rfc8422
ITU-T X.660 (OID arcs): https://www.itu.int/rec/T-REC-X.660
ITU-T X.690 (DER/BER encoding): https://www.itu.int/rec/T-REC-X.690
PKCS#10 (CSR format): https://www.rfc-editor.org/rfc/rfc2986
PKCS#12 (PFX bundles): https://www.rfc-editor.org/rfc/rfc7292
Classic McEliece Specification: https://www.randombit.net/mceliece/mceliece-spec.pdf
ChaCha Stream Cipher: https://cr.yp.to/chacha/chacha-20080120.pdf
Intel CPUID Reference: https://software.intel.com/content/www/us/en/develop/articles/intel-64-architecture-cpuid-instruction.html
Intel Intrinsics Guide: https://www.intel.com/content/www/us/en/develop/documentation/intrinsics-guide/

Keywords: Cryptography, Post-Quantum, Asymmetric Cryptography, Symmetric Cryptography, Digital Signature, Key Encapsulation, Key Exchange, Hash Function, MAC, DRBG, Entropy, X.509, PKI, TLS, CRL, OCSP, PKCS10, PKCS12, ASN.1, DER, BER, PEM, OID, ML-KEM, ML-DSA, SLH-DSA, Falcon, McEliece, HQC, ECDSA, ECDH, EdDSA, AES, ChaCha20, SIMD, AVX, AVX2, AVX512, Secure Memory, MISRA, QSC.

Example: Refer to the module-specific headers (e.g., aes.h, sha3.h, kyber.h, dilithium.h, falcon.h, ecdsa.h, ecdh.h, x509cert.h, x509verify.h, x509pem.h, etc.) for detailed usage examples and API documentation.

Remarks: QSC is designed to serve as the foundational cryptographic solution for secure, post-quantum communications and is continuously updated to incorporate emerging cryptographic research and standards. The X.509 layer is intentionally structured so that structural and policy checks remain independent of the cryptographic backend, enabling straightforward extension to new signature algorithm profiles as post-quantum standards evolve.

Author: John G. Underhill

Date: 2026-03-28

Version: 1.1.0.2b