pq_crypto 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dcc40bb87fcd74ce1d16bb32d99df894cb127e0c77c879cba7ec7d6ef8e099e8
+  data.tar.gz: 6baf54010794cca2d1a9f81f884f1a6db16355515f83ed1812baa57feeaf63dc
+SHA512:
+  metadata.gz: feb14e5bc0aefc8fa3b9b3d24083cd93923466d9bc1c5a1e4e527325f0290124be785da63aca97e342c9885e1e56b92e2637007a93c47d85ac950bee2317af71
+  data.tar.gz: 1a7773c9850dfea54df3897a6ee092f99258e25b0fa5393c977fa7e70c3eed309bca54044711501a6475f0d30ca56753eecaa768e87c9620a4e581b015c3332a

data/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        ruby: ["3.1", "3.2", "3.3", "3.4"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.26.0"
+
+      - name: Compile extension
+        run: bundle exec rake compile
+
+      - name: Run tests
+        run: bundle exec rake test

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.1.0]
+
+Initial public release.
+
+### Public API
+
+- Added primitive-first `PQCrypto::KEM` for pure `ML-KEM-768`.
+- Added primitive-first `PQCrypto::Signature` for `ML-DSA-65`.
+- Added `PQCrypto::HybridKEM` for the pq_crypto-specific `ML-KEM-768 + X25519 + HKDF-SHA256` hybrid combiner.
+- Added typed key objects with raw-byte import/export and `details`/supported-algorithm introspection.
+- Added `pqc_container_*` DER/PEM import/export for pq_crypto-specific key containers.
+- Documented that `pqc_container_*` containers use pq_crypto-local OIDs and are not a long-term external interoperability guarantee.
+- Added `PQCrypto::Testing` deterministic hooks for regression coverage.
+
+### Native / build
+
+- Vendored `PQClean` sources for `ML-KEM-768` and `ML-DSA-65`.
+- Integrated OpenSSL-backed conventional primitives for hybrid mode and utility operations.
+- Require OpenSSL 3.0 or later.
+
+### Testing
+
+- Added deterministic regression coverage for `ML-KEM-768` and `ML-DSA-65`.
+- Hardened native bindings by copying Ruby string inputs before running no-GVL native operations.
+- Tightened manual vendoring workflow to require an explicit pinned upstream URL, version label, strip prefix, and SHA-256.
+- Added primitive interop tests for OpenSSL and Go where toolchain support is available.
+- Added serialization hardening tests.

data/GET_STARTED.md

@@ -0,0 +1,65 @@
+# Getting started with pq_crypto
+
+## 1. Build the extension
+
+```bash
+bundle install
+bundle exec rake compile
+```
+
+## 2. Generate an ML-KEM-768 keypair
+
+```ruby
+keypair = PQCrypto::KEM.generate(:ml_kem_768)
+```
+
+## 3. Encapsulate and decapsulate
+
+```ruby
+result = keypair.public_key.encapsulate
+shared_secret = keypair.secret_key.decapsulate(result.ciphertext)
+```
+
+## 4. Generate an ML-DSA-65 keypair
+
+```ruby
+sig = PQCrypto::Signature.generate(:ml_dsa_65)
+```
+
+## 5. Sign and verify
+
+```ruby
+signature = sig.secret_key.sign("message")
+sig.public_key.verify!("message", signature)
+```
+
+## 6. Optional hybrid KEM
+
+```ruby
+hybrid = PQCrypto::HybridKEM.generate(:ml_kem_768_x25519_hkdf_sha256)
+result = hybrid.public_key.encapsulate
+shared_secret = hybrid.secret_key.decapsulate(result.ciphertext)
+```
+
+This hybrid mode is pq_crypto-specific and not a general interoperability format.
+
+## 7. Serialize a key
+
+```ruby
+der = keypair.public_key.to_pqc_container_der
+imported = PQCrypto::KEM.public_key_from_pqc_container_der(der)
+```
+
+## 8. Inspect supported algorithms
+
+```ruby
+PQCrypto.supported_kems
+PQCrypto.supported_hybrid_kems
+PQCrypto.supported_signatures
+```
+
+## 9. Practical notes
+
+- OpenSSL 3.0+ is required.
+- `pqc_container_*` formats are pq_crypto-specific.
+- `PQCrypto::Testing` exposes deterministic helpers only for regression tests.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roman Haydarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# pq_crypto
+
+`pq_crypto` is a primitive-first Ruby gem for post-quantum cryptography.
+
+It currently exposes three public building blocks:
+
+- `PQCrypto::KEM` — pure `ML-KEM-768`
+- `PQCrypto::Signature` — `ML-DSA-65`
+- `PQCrypto::HybridKEM` — an optional custom hybrid KEM that combines `ML-KEM-768` and `X25519` with transcript-bound `HKDF-SHA256`
+
+The gem is backed by vendored `PQClean` sources for `ML-KEM-768` / `ML-DSA-65` and OpenSSL for conventional primitives such as `X25519` and `HKDF-SHA256`.
+
+## Status
+
+- first public release
+- primitive-first API only
+- no protocol/session helpers in the public surface
+- serialization uses pq_crypto-specific `pqc_container_*` wrappers
+- not audited
+- not yet positioned as production-ready
+
+## Installation
+
+Add the gem to your project and compile the extension:
+
+```ruby
+# Gemfile
+gem "pq_crypto"
+```
+
+```bash
+bundle install
+bundle exec rake compile
+```
+
+### Native dependencies
+
+- Ruby 3.1+
+- a C toolchain
+- OpenSSL **3.0 or later**
+
+## Primitive API
+
+### ML-KEM-768
+
+```ruby
+keypair = PQCrypto::KEM.generate(:ml_kem_768)
+result = keypair.public_key.encapsulate
+shared_secret = keypair.secret_key.decapsulate(result.ciphertext)
+```
+
+### ML-DSA-65
+
+```ruby
+keypair = PQCrypto::Signature.generate(:ml_dsa_65)
+signature = keypair.secret_key.sign("hello")
+keypair.public_key.verify!("hello", signature)
+```
+
+### Hybrid ML-KEM-768 + X25519
+
+```ruby
+keypair = PQCrypto::HybridKEM.generate(:ml_kem_768_x25519_hkdf_sha256)
+result = keypair.public_key.encapsulate
+shared_secret = keypair.secret_key.decapsulate(result.ciphertext)
+```
+
+`PQCrypto::HybridKEM` is a **custom pq_crypto construction**. It is not advertised as compatible with HPKE, TLS hybrid drafts, X-Wing, OpenSSL native PQ APIs, or any other external wire format.
+
+## Serialization
+
+Key import/export is available through pq_crypto-specific containers:
+
+- `to_pqc_container_der`
+- `to_pqc_container_pem`
+- `*_from_pqc_container_der`
+- `*_from_pqc_container_pem`
+
+Example:
+
+```ruby
+keypair = PQCrypto::KEM.generate(:ml_kem_768)
+der = keypair.public_key.to_pqc_container_der
+imported = PQCrypto::KEM.public_key_from_pqc_container_der(der)
+```
+
+These containers are **not real ASN.1 SPKI or PKCS#8**. They are intended for stable import/export inside `pq_crypto` itself and are not advertised as interoperable with external PKI tooling.
+
+## Introspection
+
+```ruby
+PQCrypto.version
+PQCrypto.backend
+PQCrypto.supported_kems
+PQCrypto.supported_hybrid_kems
+PQCrypto.supported_signatures
+PQCrypto::KEM.details(:ml_kem_768)
+PQCrypto::HybridKEM.details(:ml_kem_768_x25519_hkdf_sha256)
+PQCrypto::Signature.details(:ml_dsa_65)
+```
+
+## Testing helpers
+
+Deterministic test hooks are exposed under `PQCrypto::Testing` for regression coverage:
+
+- `ml_kem_keypair_from_seed`
+- `ml_kem_encapsulate_from_seed`
+- `ml_dsa_keypair_from_seed`
+- `ml_dsa_sign_from_seed`
+
+These helpers are intended for tests only.
+
+## Development
+
+Run the test suite with:
+
+```bash
+bundle exec rake test
+```
+
+Refresh vendored PQClean sources manually only when you intentionally update the vendor snapshot. The refresh script now has a safe pinned default and records the exact vendored snapshot in `ext/pqcrypto/vendor/.vendored`:
+
+```bash
+bundle exec ruby script/vendor_libs.rb
+```
+
+To intentionally change the upstream snapshot, override all four pinning inputs together:
+
+```bash
+PQCLEAN_VERSION=<full-git-commit> \
+PQCLEAN_URL=https://github.com/PQClean/PQClean/archive/<full-git-commit>.tar.gz \
+PQCLEAN_SHA256=<archive-sha256> \
+PQCLEAN_STRIP=PQClean-<full-git-commit> \
+  bundle exec ruby script/vendor_libs.rb
+```

data/SECURITY.md

@@ -0,0 +1,57 @@
+# Security notes
+
+## Scope of the public API
+
+`pq_crypto` 0.1.0 exposes a primitive-first public surface:
+
+- `PQCrypto::KEM` (`ML-KEM-768`)
+- `PQCrypto::Signature` (`ML-DSA-65`)
+- `PQCrypto::HybridKEM` (custom `ML-KEM-768 + X25519 + HKDF-SHA256` combiner)
+- `PQCrypto.secure_wipe`
+
+The gem does **not** publish protocol/session helpers as part of the supported public API in this release.
+
+## Audit status
+
+This project has not been audited. Treat it as experimental software.
+
+## Algorithm notes
+
+### ML-KEM-768 / ML-DSA-65
+
+The core post-quantum primitives are backed by vendored `PQClean` sources.
+
+### HybridKEM
+
+`PQCrypto::HybridKEM` is a pq_crypto-specific hybrid combiner. It is **not** claimed to be HPKE-, TLS-, or X-Wing-compatible.
+
+Use it only if you explicitly want this project-local construction.
+
+## Serialization
+
+`pqc_container_*` DER/PEM wrappers are pq_crypto-specific containers.
+
+They are:
+- not real SPKI
+- not real PKCS#8
+- not advertised as interoperable with OpenSSL, Go, Java, or PKI tooling
+
+The OIDs embedded in these containers are project-local UUID-derived OIDs under `2.25.*`. They are not registrations for interoperable standard key formats. Within the `pqc_container_*` format they are treated as part of pq_crypto's own serialized container schema, not as external interoperability identifiers.
+
+Future releases may replace these project-local identifiers if pq_crypto adopts standardized external container formats. Persisted `pqc_container_*` blobs should therefore be treated as pq_crypto-local artifacts, not as a long-term interoperability format.
+
+## Memory wiping
+
+`PQCrypto.secure_wipe` clears mutable Ruby strings in place. Ruby copies, GC behavior, and prior derived copies may still leave sensitive material elsewhere in process memory.
+
+## OpenSSL baseline
+
+`pq_crypto` requires OpenSSL **3.0 or later**.
+
+OpenSSL is used for conventional primitives and plumbing such as:
+- `X25519`
+- `HKDF-SHA256`
+
+## Threading
+
+Concurrent read-only operations on primitive key objects are supported. Native calls copy Ruby string inputs before releasing the GVL, so normal concurrent use does not rely on Ruby string storage remaining pinned in place. Deterministic testing helpers remain test-only utilities and should not be treated as a general multi-threading contract.

data/ext/pqcrypto/extconf.rb

@@ -0,0 +1,157 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "mkmf"
+
+$CFLAGS << " -std=c99 -Wall -Wextra -O2"
+$CFLAGS << " -fstack-protector-strong -D_FORTIFY_SOURCE=2"
+$CFLAGS << " -Wno-c23-extensions -Wno-strict-prototypes -Wno-pedantic"
+$CFLAGS << " -Wno-unused-parameter -Wno-unused-function"
+
+$LDFLAGS << " -Wl,-no_warn_duplicate_libraries" if RbConfig::CONFIG["host_os"] =~ /darwin/
+
+USE_SYSTEM = arg_config("--use-system-libraries") || ENV["PQCRYPTO_USE_SYSTEM_LIBRARIES"]
+
+SANITIZE = ENV["PQCRYPTO_SANITIZE"]
+
+if SANITIZE && !SANITIZE.strip.empty?
+  sanitize = SANITIZE.strip
+  $CFLAGS << " -O1 -g -fno-omit-frame-pointer -fsanitize=#{sanitize}"
+  $LDFLAGS << " -fsanitize=#{sanitize}"
+end
+
+def configure_compiler_environment
+  return unless RUBY_PLATFORM.include?("darwin")
+
+  dir_config("homebrew", "/opt/homebrew")
+  $CPPFLAGS << " -I/opt/homebrew/include"
+  $LDFLAGS << " -L/opt/homebrew/lib"
+end
+
+def find_vendor_dir
+  candidates = [
+    File.join(__dir__, "vendor"),
+    File.expand_path("../../ext/pqcrypto/vendor", __dir__),
+    File.join(Dir.pwd, "ext", "pqcrypto", "vendor")
+  ]
+
+  dir = __dir__
+  6.times do
+    candidates << File.join(dir, "ext", "pqcrypto", "vendor")
+    dir = File.dirname(dir)
+  end
+
+  candidates.find { |path| File.exist?(File.join(path, ".vendored")) }
+            &.then { |path| File.expand_path(path) }
+end
+
+def configure_openssl!
+  configure_compiler_environment
+
+  abort "OpenSSL libcrypto is required" unless have_library("crypto")
+  abort "OpenSSL libssl is required" unless have_library("ssl")
+  abort "openssl/evp.h is required" unless have_header("openssl/evp.h")
+  abort "openssl/rand.h is required" unless have_header("openssl/rand.h")
+  abort "openssl/kdf.h is required" unless have_header("openssl/kdf.h")
+
+  version_check = <<~SRC
+    #include <openssl/opensslv.h>
+    #if OPENSSL_VERSION_NUMBER < 0x30000000L
+    #error "OpenSSL 3.0 or later is required"
+    #endif
+    int main(void) { return 0; }
+  SRC
+
+  abort "OpenSSL 3.0 or later is required" unless try_compile(version_check)
+
+  $CFLAGS << " -DHAVE_OPENSSL_EVP_H -DHAVE_OPENSSL_RAND_H -DHAVE_OPENSSL_KDF_H"
+end
+
+def configure_pqclean(vendor_dir)
+  return nil unless vendor_dir
+
+  pqclean_dir = File.join(vendor_dir, "pqclean")
+  return nil unless Dir.exist?(pqclean_dir)
+
+  mlkem_dir = File.join(pqclean_dir, "crypto_kem", "ml-kem-768", "clean")
+  mldsa_dir = File.join(pqclean_dir, "crypto_sign", "ml-dsa-65", "clean")
+  common_dir = File.join(pqclean_dir, "common")
+
+  include_dirs = [mlkem_dir, mldsa_dir, common_dir]
+  return nil unless include_dirs.all? { |dir| Dir.exist?(dir) }
+
+  mlkem_sources = Dir.glob(File.join(mlkem_dir, "*.c")).sort
+  mldsa_sources = Dir.glob(File.join(mldsa_dir, "*.c")).sort
+  common_sources = %w[fips202.c sha2.c sp800-185.c randombytes.c].map { |name| File.join(common_dir, name) }
+
+  source_groups = [
+    ["pqclean_mlkem", mlkem_sources],
+    ["pqclean_mldsa", mldsa_sources],
+    ["pqclean_common", common_sources]
+  ]
+
+  return nil unless source_groups.all? { |_, sources| sources.all? { |path| File.exist?(path) } }
+
+  $CFLAGS << " -DHAVE_PQCLEAN -Wno-undef"
+  include_dirs.each { |dir| $CPPFLAGS << " -I#{dir}" }
+
+  {
+    include_dirs: include_dirs,
+    source_groups: source_groups
+  }
+end
+
+def inject_pqclean_sources!(pqclean_config)
+  return unless pqclean_config
+
+  makefile = File.read("Makefile")
+
+  vendor_objects = []
+  build_rules = []
+
+  pqclean_config[:source_groups].each do |prefix, sources|
+    sources.each do |source|
+      base = File.basename(source, ".c").tr("-", "_")
+      object = "#{prefix}_#{base}.o"
+      vendor_objects << object
+      build_rules << <<~RULE
+        #{object}: #{source}
+        	$(ECHO) compiling #{source}
+        	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+      RULE
+    end
+  end
+
+  objects_line = makefile.lines.find { |line| line.start_with?("OBJS = ") }
+  raise "Could not find OBJS line in generated Makefile" unless objects_line
+
+  makefile.sub!(objects_line, objects_line.chomp + " #{vendor_objects.join(' ')}\n")
+
+  unless makefile.include?("# vendored pqclean objects")
+    rules_block = "\n# vendored pqclean objects\n" + build_rules.join("\n") + "\n"
+    anchor = "$(OBJS): $(HDRS) $(ruby_headers)\n"
+    raise "Could not find OBJS dependency anchor in generated Makefile" unless makefile.include?(anchor)
+
+    makefile.sub!(anchor, anchor + rules_block)
+  end
+
+  File.write("Makefile", makefile)
+end
+
+have_func("getrandom", "sys/random.h")
+have_func("arc4random_buf", "stdlib.h")
+
+vendor_dir = USE_SYSTEM ? nil : find_vendor_dir
+
+puts
+puts "=== PQCrypto build configuration ==="
+configure_openssl!
+pqclean_config = configure_pqclean(vendor_dir)
+puts "OpenSSL: system"
+abort "PQClean vendored sources are required. Run: bundle exec rake vendor" unless pqclean_config
+puts "PQClean: vendored"
+puts "Output: pqcrypto/pqcrypto_secure"
+puts "===================================="
+
+create_makefile("pqcrypto/pqcrypto_secure")
+inject_pqclean_sources!(pqclean_config)

data/ext/pqcrypto/mldsa_api.h

@@ -0,0 +1,51 @@
+#ifndef MLDSA_API_H
+#define MLDSA_API_H
+
+#ifdef HAVE_PQCLEAN
+#include <stddef.h>
+#include <stdint.h>
+
+#define PQCLEAN_MLDSA65_CLEAN_CRYPTO_ALGNAME "ML-DSA-65"
+
+int PQCLEAN_MLDSA65_CLEAN_crypto_sign_keypair(uint8_t *pk, uint8_t *sk);
+
+int PQCLEAN_MLDSA65_CLEAN_crypto_sign_signature_ctx(uint8_t *sig, size_t *siglen,
+        const uint8_t *m, size_t mlen,
+        const uint8_t *ctx, size_t ctxlen,
+        const uint8_t *sk);
+
+int PQCLEAN_MLDSA65_CLEAN_crypto_sign_ctx(uint8_t *sm, size_t *smlen,
+        const uint8_t *m, size_t mlen,
+        const uint8_t *ctx, size_t ctxlen,
+        const uint8_t *sk);
+
+int PQCLEAN_MLDSA65_CLEAN_crypto_sign_verify_ctx(const uint8_t *sig, size_t siglen,
+        const uint8_t *m, size_t mlen,
+        const uint8_t *ctx, size_t ctxlen,
+        const uint8_t *pk);
+
+int PQCLEAN_MLDSA65_CLEAN_crypto_sign_open_ctx(uint8_t *m, size_t *mlen,
+        const uint8_t *sm, size_t smlen,
+        const uint8_t *ctx, size_t ctxlen,
+        const uint8_t *pk);
+
+int PQCLEAN_MLDSA65_CLEAN_crypto_sign_signature(uint8_t *sig, size_t *siglen,
+        const uint8_t *m, size_t mlen,
+        const uint8_t *sk);
+
+int PQCLEAN_MLDSA65_CLEAN_crypto_sign(uint8_t *sm, size_t *smlen,
+                                      const uint8_t *m, size_t mlen,
+                                      const uint8_t *sk);
+
+int PQCLEAN_MLDSA65_CLEAN_crypto_sign_verify(const uint8_t *sig, size_t siglen,
+        const uint8_t *m, size_t mlen,
+        const uint8_t *pk);
+
+int PQCLEAN_MLDSA65_CLEAN_crypto_sign_open(uint8_t *m, size_t *mlen,
+        const uint8_t *sm, size_t smlen,
+        const uint8_t *pk);
+
+
+#endif
+
+#endif

data/ext/pqcrypto/mlkem_api.h

@@ -0,0 +1,21 @@
+#ifndef MLKEM_API_H
+#define MLKEM_API_H
+
+#ifdef HAVE_PQCLEAN
+#include <stdint.h>
+
+#define PQCLEAN_MLKEM768_CLEAN_CRYPTO_SECRETKEYBYTES  2400
+#define PQCLEAN_MLKEM768_CLEAN_CRYPTO_PUBLICKEYBYTES  1184
+#define PQCLEAN_MLKEM768_CLEAN_CRYPTO_CIPHERTEXTBYTES 1088
+#define PQCLEAN_MLKEM768_CLEAN_CRYPTO_BYTES           32
+#define PQCLEAN_MLKEM768_CLEAN_CRYPTO_ALGNAME "ML-KEM-768"
+
+int PQCLEAN_MLKEM768_CLEAN_crypto_kem_keypair(uint8_t *pk, uint8_t *sk);
+int PQCLEAN_MLKEM768_CLEAN_crypto_kem_enc(uint8_t *ct, uint8_t *ss, const uint8_t *pk);
+int PQCLEAN_MLKEM768_CLEAN_crypto_kem_dec(uint8_t *ss, const uint8_t *ct, const uint8_t *sk);
+int PQCLEAN_MLKEM768_CLEAN_crypto_kem_keypair_derand(uint8_t *pk, uint8_t *sk, const uint8_t *coins);
+int PQCLEAN_MLKEM768_CLEAN_crypto_kem_enc_derand(uint8_t *ct, uint8_t *ss, const uint8_t *pk, const uint8_t *coins);
+
+#endif
+
+#endif