pq_crypto 0.4.2 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65d8d9a5d3aeecaba257218dcae5bedb56c82283a4d4d34cdea4a5946c5d2b80
-  data.tar.gz: 210cd374801dd9f8ce7beafa4f5eb528c807bcedd3762977445849e2def7e215
+  metadata.gz: d5949078149668609462a1e9a3df7b7f767499311b998e4dd651be1d7865ddfc
+  data.tar.gz: 600fc91b9614aec5f7f61d8c3ab6d11643bbbf919941faf0508384e7ede9dce0
 SHA512:
-  metadata.gz: a2085b6a3b6b48389219b81fa8b7a0e656c6583587df9a52817fcf28e663210be744e9e6a121dbaccdb9d06e8ce12fc2ee7b84f581fb9ce4e4bd74273df6a4b5
-  data.tar.gz: b6e7e3737f0d052d045b6fd4c424f188f6eab01333bc86b8685c707b6a90c14f4af0ecc3cacad6e8ca36750d71694d11481e5d4e617fa41bdbfe68a19a5ea0c3
+  metadata.gz: 2ac70b6f37460e0a56b1601b59ba5660dda7e4c0c87cc03211c9497261b06f632856079622546f6c8b6db6cfff97b1a9355db879958985f48dfe296c5d729b80
+  data.tar.gz: 9e89256c60b8153518520438b77632eb232660ff88d0b0668cfb8aeea7a50875c2c7297773f3d469952129ccceb6e604e4f619cc4cc2ebbd458fdca9d50e837f

data/.github/workflows/ci.yml

@@ -1,12 +1,30 @@
 name: CI
 
 on:
-  push:
-    branches: ["**"]
   pull_request:
+  push:
+    branches: [main]
 
 jobs:
+  vendor-verify:
+    name: vendor-verify
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Verify vendored sources against pinned tree_sha256
+        run: bundle exec rake vendor:verify
+
   test:
+    needs: vendor-verify
     runs-on: ${{ matrix.os }}
 
     strategy:
@@ -30,6 +48,9 @@ jobs:
         with:
           go-version: "1.26.0"
 
+      - name: Verify vendored sources
+        run: bundle exec rake vendor:verify
+
       - name: Compile extension
         run: bundle exec rake compile
 
@@ -37,6 +58,7 @@ jobs:
         run: bundle exec rake test
 
   interop-openssl-3-5-required:
+    needs: vendor-verify
     name: interop-openssl-3.5-required
     runs-on: ubuntu-24.04
 
@@ -77,6 +99,9 @@ jobs:
         with:
           go-version: "1.26.0"
 
+      - name: Verify vendored sources
+        run: bundle exec rake vendor:verify
+
       - name: Compile extension
         run: bundle exec rake compile
 

data/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## [0.5.1] - 2026-05-04
+
+### Performance
+
+- Enabled native asm/SIMD paths for ML-DSA/ML-KEM where available.
+- Reduced Hybrid KEM X25519 overhead by reusing expanded/native key state and avoiding repeated private/public key reconstruction.
+- Moved hot crypto calls under `rb_nogvl` where applicable.
+- Optimized PEM export path by replacing BIO/streaming base64 with direct encode.
+- Reduced small-buffer streaming overhead by avoiding unnecessary `malloc`/`nogvl` work for tiny chunks.
+
+### Vendoring
+
+- Committed `mlkem-native` and `mldsa-native` sources to the repository. Builds no longer require git or network.
+- Pinned upstream by `commit` + `tree_sha256` in `script/vendor_libs.rb`; manifest signed with `manifest_sha256`.
+- Deterministic vendor tree (no symlinks, dotfiles, normalized mtime/permissions).
+- `script/vendor_libs.rb` now supports `--verify`, `--sync`, `--bump`.
+
+### Build
+
+- `extconf.rb` no longer auto-fetches upstream. Missing vendor aborts the build; opt in with `PQCRYPTO_AUTO_VENDOR=1`.
+
+### Rakefile
+
+- Added `vendor:verify`, `vendor:sync`, `vendor:bump`. Default task runs `vendor:verify` before `compile` and `test`.
+
+### CI
+
+- Added `vendor-verify` gating job; `vendor:verify` also runs in each test job before compile.
+
+### Repository
+
+- `.gitattributes` enforces `eol=lf` and marks vendor as binary (CRLF protection).
+- `.gitignore` no longer hides `sempls/`.
+
+## [0.5.0] - 2026-05-04
+
+### Changed — native backend migration
+
+- Replaced the PQClean runtime/build path with PQ Code Package `mlkem-native` and `mldsa-native` as the only ML-KEM / ML-DSA backend.
+- Removed the PQClean fallback entirely so backend failures are attributable to the new native path instead of mixed old/new implementations.
+- Updated the native extension build to require `ext/pqcrypto/vendor/mlkem-native/mlkem/mlkem_native.c` and `ext/pqcrypto/vendor/mldsa-native/mldsa/mldsa_native.c`.
+- Changed vendoring and gem packaging to keep only a minimal PQ Code Package source snapshot, avoiding upstream examples and symlink-heavy trees in packaged gems.
+- Switched native compilation to `-O3`; optional upstream native assembly remains opt-in through `PQCRYPTO_NATIVE_ASM=1`.
+- `PQCrypto.backend` now reports `:native_pq_code_package`.
+
+### Fixed
+
+- Corrected deterministic ML-DSA test signing on `mldsa-native` by passing the FIPS 204 pure-mode domain-separation prefix (`00 00` for an empty context) into `signature_internal`. This restores deterministic round-trip verification and ML-DSA siggen KAT compatibility.
+
+### Documentation
+
+- Updated README, GET_STARTED, SECURITY, and migration notes for the native-only backend and the no-PQClean policy.
+- Documented that `pqc_container_*` remains a compatibility serialization format while the cryptographic backend has moved to PQ Code Package native sources.
+
+### Migration notes
+
+- Source checkouts must refresh vendor sources with `bundle exec rake vendor` before compiling if `ext/pqcrypto/vendor/.vendored` is missing or stale.
+- This release intentionally does not support falling back to PQClean. If native sources are absent or incompatible, the extension build fails early.
+
 ## [0.4.2] - 2026-04-29
 
 ### Fixed

data/GET_STARTED.md

@@ -359,17 +359,23 @@ keypair.secret_key == imported_secret_key
 Secret key `inspect` output is intentionally redacted, and secret key objects
 do not expose a public fingerprint method.
 
-## 13. Build-time Keccak backend
+## 13. Native backend
 
-The default build uses PQClean's scalar `common/fips202.c` backend:
+Since `0.5.0`, the build uses PQ Code Package `mlkem-native` / `mldsa-native`
+sources only. There is no PQClean fallback and no separate
+`PQCRYPTO_KECCAK_BACKEND` switch: Keccak/SHAKE comes from the selected PQ Code
+Package native source tree.
 
 ```bash
-PQCRYPTO_KECCAK_BACKEND=clean bundle exec rake compile
+bundle exec rake vendor
+bundle exec rake compile
 ```
 
-`PQCRYPTO_KECCAK_BACKEND=xkcp` is reserved for a separately vendored, reviewed,
-`fips202.h`-compatible XKCP adapter. If requested without that adapter, the
-build aborts instead of silently falling back to `clean`.
+To try the upstream native assembly backend, opt in explicitly:
+
+```bash
+PQCRYPTO_NATIVE_ASM=1 bundle exec rake compile
+```
 
 ## 14. Async / Fiber scheduler behavior
 
@@ -389,8 +395,8 @@ PQCrypto::Testing.ml_dsa_keypair_from_seed(seed)       # 32-byte seed
 PQCrypto::Testing.ml_dsa_sign_from_seed(message, sk, seed)
 ```
 
-These helpers are intended for tests only. They drive stock PQClean entrypoints
-and are not part of the normal application API.
+These helpers are intended for tests only. They drive deterministic PQ Code
+Package native entrypoints and are not part of the normal application API.
 
 ## 16. Development commands
 
@@ -400,20 +406,19 @@ Run the test suite:
 bundle exec rake test
 ```
 
-Refresh the pinned PQClean vendor snapshot only when intentionally updating
-vendored sources:
+Refresh the pinned PQ Code Package native vendor snapshot only when intentionally
+updating vendored sources. The vendoring script keeps a minimal, source-gem-safe
+snapshot: `mlkem-native/mlkem`, `mldsa-native/mldsa`, and upstream license/docs
+only. It intentionally omits examples and symlink-heavy upstream trees:
 
 ```bash
 bundle exec ruby script/vendor_libs.rb
 ```
 
-To intentionally change the upstream snapshot, override all pinning inputs
-together:
+To intentionally change the upstream snapshot, override the native package refs:
 
 ```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> \
+MLKEM_NATIVE_REF=<tag-or-commit> \
+MLDSA_NATIVE_REF=<tag-or-commit> \
   bundle exec ruby script/vendor_libs.rb
 ```

data/README.md

@@ -66,6 +66,31 @@ original algorithms:
 - Ruby 3.4 or later
 - a C toolchain with C11 support
 - OpenSSL 3.0 or later with SHA3-256 and SHAKE256 available
+- vendored minimal PQ Code Package native snapshot in `ext/pqcrypto/vendor`
+
+## Native backend
+
+Version `0.5.0` moves ML-KEM and ML-DSA to PQ Code Package
+`mlkem-native` / `mldsa-native` sources. PQClean is no longer built and there
+is no runtime or build-time PQClean fallback. The repository and source gem
+ship a minimal vendor snapshot containing only the `mlkem/` and `mldsa/` source
+trees plus license/docs; upstream examples, tests, proofs, `.git` directories,
+and symlink-heavy trees are intentionally omitted. If the native vendor snapshot
+is missing, the extension build fails early.
+
+From a source checkout, refresh the native vendor snapshot before compiling:
+
+```bash
+bundle exec rake vendor
+bundle exec rake compile
+```
+
+The default build uses the portable native source path. Upstream native assembly
+can be tested explicitly with:
+
+```bash
+PQCRYPTO_NATIVE_ASM=1 bundle exec rake compile
+```
 
 ## Security status
 
@@ -98,4 +123,5 @@ Detailed usage examples live in [`GET_STARTED.md`](GET_STARTED.md):
 - streaming ML-DSA for large files
 - SPKI and PKCS#8 serialization
 - `pqc_container_*` compatibility serialization
+- native backend / vendoring notes
 - secure wiping and practical safety notes

data/SECURITY.md

@@ -27,9 +27,14 @@ substitute for a security audit.
 
 ### ML-KEM / ML-DSA
 
-The post-quantum primitives are backed by vendored `PQClean` sources and called
-through PQClean's public `crypto_kem_*` and `crypto_sign_*` entrypoints. The gem
-does not reimplement ML-KEM, ML-DSA, SHAKE, or Keccak.
+As of `0.5.0`, the post-quantum primitives are backed by vendored PQ Code
+Package `mlkem-native` and `mldsa-native` sources. PQClean is not built and
+there is intentionally no PQClean fallback.
+
+The gem calls the native package entrypoints for ML-KEM key generation,
+encapsulation, decapsulation, ML-DSA key generation, signing, verification, and
+test-only deterministic hooks. It does not reimplement ML-KEM, ML-DSA, SHAKE,
+or Keccak.
 
 ### HybridKEM
 
@@ -96,22 +101,23 @@ these encodings, callers must explicitly set:
 PQCrypto::PKCS8.allow_ml_dsa_seed_format = true
 ```
 
-This opt-in exists because PQClean exposes no public ML-DSA
-`crypto_sign_keypair_derand` entrypoint. The implementation therefore reuses the
-same thread-local seed-replay `randombytes()` path introduced for KAT tests to
-expand the RFC 9881 seed into an expanded private key. The replay buffer is
-thread-local, cleared immediately after expansion, and remains inactive for all
-normal production randomness paths.
-
-For `both` encodings, the decoder expands the seed and rejects the key if the
+This opt-in remains explicit because seed and both-form imports are more
+sensitive than expanded-key imports: the decoder expands the seed into an
+expanded private key and, for `both` encodings, rejects the key if the
 expandedKey half does not match the seed-derived key.
 
+The expansion path uses the vendored `mldsa-native` deterministic keypair
+entrypoints rather than a `randombytes()` seed-replay fallback.
+
 ## Deterministic test hooks
 
-`PQCrypto::Testing` deterministic helpers drive the stock PQClean entrypoints
-against caller-supplied seeds. For ML-DSA, which has no derand API upstream, the
-gem installs a thread-local seed-replay buffer inside its `randombytes()`
-implementation; outside of a test call the same `randombytes()` entry delegates
+`PQCrypto::Testing` deterministic helpers drive the vendored PQ Code Package
+native deterministic entrypoints against caller-supplied seeds. ML-DSA
+deterministic signing passes the FIPS 204 pure-mode domain-separation prefix
+into `mldsa-native` `signature_internal`; for an empty context this prefix is
+`00 00`.
+
+Outside of test-only deterministic calls, production randomness delegates
 directly to OpenSSL `RAND_bytes`.
 
 ## Memory wiping
@@ -135,7 +141,7 @@ OpenSSL is used for:
 - SHA3-256 for the X-Wing combiner
 - RAND_bytes as the production entropy source for `randombytes()`
 - CRYPTO_memcmp for constant-time comparison
-- Base64 encode/decode for PEM via OpenSSL BIOs
+- Base64 encode/decode for PEM
 
 OpenSSL 3.5+ is additionally used in interop tests when ML-KEM / ML-DSA EVP
 support is available.