crystal-pqc-constant v0.1.0

Constant-time Post-Quantum Cryptography (NIST FIPS 203 ML-KEM and FIPS 204 ML-DSA) for Crystal backed by OpenSSL 3.5+ and libsodium guarded memory.

GitLab Project Metadata:

• Description: Constant-time Post-Quantum Cryptography (NIST FIPS 203 ML-KEM and FIPS 204 ML-DSA) for Crystal backed by OpenSSL 3.5+ and libsodium guarded memory.
• Topics and Tags: crystal, crystal-lang, post-quantum-cryptography, pqc, ml-kem, ml-dsa, fips-203, fips-204, openssl, libsodium, gplv3

Overview

crystal-pqc-constant (Crystal::Pqc::Constant) is a standalone, zero-dependency Crystal shard providing production-grade post-quantum key encapsulation (NIST FIPS 203 ML-KEM) and digital signatures (NIST FIPS 204 ML-DSA). It binds directly to OpenSSL 3.5+ EVP_PKEY providers while isolating all long-lived private keys and 32-byte shared secrets inside libsodium guarded heap memory (sodium_malloc + sodium_mprotect_readonly).

Key Highlights

1. Zero Runtime Shard Dependencies: Links directly against system libcrypto (OpenSSL 3.5+) and libsodium with zero external Crystal shards.
2. NIST FIPS 203 (ML-KEM) Key Encapsulation: Supports ML-KEM-512 (Category 1), ML-KEM-768 (Category 3, default), and ML-KEM-1024 (Category 5) with implicit-rejection decapsulation and single-use SharedSecret#consume.
3. NIST FIPS 204 (ML-DSA) Digital Signatures: Supports ML-DSA-44 (Category 2), ML-DSA-65 (Category 3, default), and ML-DSA-87 (Category 5) detached signing and verification.
4. Guarded Memory Isolation: Secret keys and shared secrets are allocated in sodium_malloc canary-guarded pages, locked PROT_READ at rest via sodium_mprotect_readonly, synchronized with Sync::Mutex, and deterministically wiped via sodium_memzero prior to release.
5. Multi-Tier Documentation Suite: Complete Sphinx technical, functional ([FUNC-001]–[FUNC-007]), business, ADR, D2 visual diagrams, and compiler-generated API reference documentation.

Post-Quantum Cryptography Architecture

crystal-pqc-constant eliminates garbage-collector retention of sensitive key material by separating public parameters from guarded private keys (SecureBuffer):

NIST FIPS 203 (ML-KEM) Parameter Matrix

NIST FIPS 204 (ML-DSA) Parameter Matrix

Installation

Ensure OpenSSL 3.5+ (openssl-devel/openssl-dev) and libsodium (libsodium-devel/libsodium-dev) are installed on your system, then add crystal-pqc-constant to your application's shard.yml:

dependencies:
  crystal-pqc-constant:
    gitlab: renich/crystal-pqc-constant
    version: ~> 0.1.0

Then install the shard:

shards install

Usage

ML-KEM Key Encapsulation

require "crystal-pqc-constant"

alice = Crystal::Pqc::Constant::MLKEMKeyPair.generate(
  Crystal::Pqc::Constant::KEMVariant::MLKEM768
)
begin
  enc = Crystal::Pqc::Constant::MLKEMKeyPair.encapsulate(alice.public_key)
  dec_secret = alice.decapsulate(enc[:ciphertext])

  agreed = enc[:shared_secret].consume do |sender_secret|
    dec_secret.consume do |receiver_secret|
      Crystal::Pqc::Constant::Sodium.constant_time_equal?(sender_secret, receiver_secret)
    end
  end
  puts "Shared secret agreed: #{agreed}"
ensure
  alice.dispose
end

ML-DSA Digital Signatures

require "crystal-pqc-constant"

signer = Crystal::Pqc::Constant::MLDSAKeyPair.generate(
  Crystal::Pqc::Constant::DSAVariant::MLDSA65
)
begin
  message = "FIDO2 post-quantum assertion".to_slice
  signature = signer.sign(message)
  puts "Verified: #{signer.verify(message, signature)}"
ensure
  signer.dispose
end

Build System Targets

The repository includes a comprehensive, standard GNUmakefile:

Documentation

Full architectural blueprints, functional specifications, and operational playbooks are maintained under docs/:

Contributing & Code of Honor

All contributions must adhere to the Universal Code of Honor and Contributing Guidelines.

License

• Software: GNU General Public License v3.0 or later (LICENSE).
• Documentation: GNU Free Documentation License v1.3 or later (LICENSE-DOCS).

Copyleft © 2026 Rénich Bon Ćirić <renich@evalinux.com>.

Support & Donations

If you find this shard useful and wish to support its ongoing development, please consider donating: