pq_crypto 0.3.1 → 0.4.2

data/README.md

@@ -1,237 +1,101 @@
 # pq_crypto
 
 `pq_crypto` is a primitive-first Ruby gem for post-quantum cryptography.
+It provides small Ruby APIs for ML-KEM, ML-DSA, and one hybrid X-Wing KEM,
+with standard key serialization where available.
 
-It exposes three public building blocks:
-
-- `PQCrypto::KEM` — pure `ML-KEM-768` (FIPS 203)
-- `PQCrypto::Signature` — `ML-DSA-65` (FIPS 204)
-- `PQCrypto::HybridKEM` — `ML-KEM-768 + X25519` combined via the
-  [X-Wing](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/)
-  SHA3-256 combiner
-
-The gem is backed by vendored `PQClean` sources for `ML-KEM-768` /
-`ML-DSA-65` and by OpenSSL for `X25519` and `SHA3-256`. Every piece of
-conventional-crypto functionality goes through standard library calls
-(`EVP_*`, `RAND_bytes`, `CRYPTO_memcmp`, `BIO_f_base64`) — nothing
-roll-your-own where a library primitive exists.
-
-## Status
-
-- 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
+The gem intentionally stays close to cryptographic primitives. It does not
+provide protocol, session, transport, certificate-chain, or application-level
+handshake helpers.
 
 ## Installation
 
-Add the gem to your project and compile the extension:
+Add the gem to your `Gemfile`:
 
 ```ruby
 # Gemfile
 gem "pq_crypto"
 ```
 
+Then install it:
+
 ```bash
 bundle install
-bundle exec rake compile
-```
-
-### Native dependencies
-
-- Ruby 3.4.x
-- a C toolchain with C11 support (for `_Static_assert` / `_Thread_local`)
-- OpenSSL **3.0 or later** with SHA3-256 and SHAKE256 available (default provider)
-
-## Async / Fiber scheduler support
-
-`pq_crypto` does not require any gem-specific Async configuration. On
-Ruby 3.4, `sign` and `verify` use Ruby's scheduler-aware
-`rb_nogvl(..., RB_NOGVL_OFFLOAD_SAFE)` path automatically.
-
-That means:
-
-- without a Fiber scheduler, these methods fall back to the ordinary
-  no-GVL behavior;
-- with a scheduler that implements `blocking_operation_wait` (for
-  example `Async` with a worker pool), the blocking native work can
-  be moved off the event loop.
-
-This integration is intentionally limited to `sign` and `verify`; the
-faster primitive operations keep the lower-overhead path.
-
-Example with `Async`:
-
-```ruby
-require "async"
-require "pq_crypto"
-
-keypair = PQCrypto::Signature.generate(:ml_dsa_65)
-message = "hello" * 100_000
-
-reactor = Async::Reactor.new(worker_pool: true)
-root = reactor.async do |task|
-  task.async do
-    signature = keypair.secret_key.sign(message)
-    keypair.public_key.verify(message, signature)
-  end
-
-  task.async do
-    sleep 0.01
-    puts "event loop stayed responsive"
-  end
-end
-
-reactor.run
-root.wait
-reactor.close
-```
-
-## 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)    # => true / false
-keypair.public_key.verify!("hello", signature)   # raises on mismatch
-```
-
-Note: `verify` returns a plain boolean for normal outcomes. `verify!`
-raises `PQCrypto::VerificationError` when the signature does not
-match.
-
-### Hybrid ML-KEM-768 + X25519 (X-Wing)
-
-```ruby
-keypair = PQCrypto::HybridKEM.generate(:ml_kem_768_x25519_xwing)
-result = keypair.public_key.encapsulate
-shared_secret = keypair.secret_key.decapsulate(result.ciphertext)
 ```
 
-The implementation follows draft-10 key expansion: the X-Wing secret
-decapsulation key is a 32-byte seed expanded with SHAKE256 into ML-KEM
-and X25519 private material. The combiner is exactly:
+When working from a source checkout, compile the native extension before
+running tests or examples:
 
-```
-ss = SHA3-256( ss_M || ss_X || ct_X || pk_X || "\.//^\" )
+```bash
+bundle exec rake compile
+bundle exec rake test
 ```
 
-as specified by `draft-connolly-cfrg-xwing-kem-10`. See `SECURITY.md`
-for audit status and interoperability caveats.
+## What this gem provides
 
-## Serialization
+| Area | Capabilities |
+| --- | --- |
+| ML-KEM | Key generation, encapsulation, decapsulation, raw key import/export, SPKI public keys, PKCS#8 private keys. |
+| ML-DSA | Key generation, signing, verification, streaming signing/verification for large inputs, raw key import/export, SPKI public keys, PKCS#8 private keys. |
+| Hybrid KEM | ML-KEM-768 + X25519 using the X-Wing combiner. |
+| Serialization | Standard SPKI / PKCS#8 for NIST PQC keys, plus frozen `pqc_container_*` compatibility formats for the original algorithms. |
+| Safety helpers | Best-effort secret wiping and constant-time equality for key comparisons. |
+| Introspection | Supported algorithm lists, algorithm metadata, backend/version helpers. |
 
-Key import/export is available through pq_crypto-specific containers:
+## Supported algorithms
 
-- `to_pqc_container_der`
-- `to_pqc_container_pem`
-- `*_from_pqc_container_der`
-- `*_from_pqc_container_pem`
+| Family | Algorithms | Notes |
+| --- | --- | --- |
+| KEM | `:ml_kem_512`, `:ml_kem_768`, `:ml_kem_1024` | FIPS 203 ML-KEM. Standard SPKI public keys and PKCS#8 private keys. |
+| Signature | `:ml_dsa_44`, `:ml_dsa_65`, `:ml_dsa_87` | FIPS 204 ML-DSA. Standard SPKI public keys and PKCS#8 private keys. |
+| Hybrid KEM | `:ml_kem_768_x25519_xwing` | ML-KEM-768 + X25519 hybrid KEM using the X-Wing construction. |
 
-Example:
+Standard encodings use RFC 9935 OIDs for ML-KEM and RFC 9881 OIDs for
+ML-DSA. `AlgorithmIdentifier.parameters` are omitted, not encoded as `NULL`.
 
-```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.
+The `pqc_container_*` format is project-local and kept only for backward
+compatibility. It is not ASN.1, SPKI, or PKCS#8. It remains limited to the
+original algorithms:
 
-## Secure wiping
+- `:ml_kem_768`
+- `:ml_dsa_65`
+- `:ml_kem_768_x25519_xwing`
 
-`PQCrypto.secure_wipe(str)` zeros the bytes of a mutable Ruby string
-in place. Key objects hold a private copy of their bytes, so `wipe!`
-on a `SecretKey` zeroes **only** that internal copy — any prior Ruby
-string the caller holds is untouched. If you need to wipe the
-caller-side buffer, do so explicitly:
+## Requirements
 
-```ruby
-raw = File.binread(path)
-key = PQCrypto::KEM.secret_key_from_bytes(:ml_kem_768, raw)
-PQCrypto.secure_wipe(raw)  # scrub the original input
-# ... use key ...
-key.wipe!                  # scrub the key's internal copy
-```
+- Ruby 3.4 or later
+- a C toolchain with C11 support
+- OpenSSL 3.0 or later with SHA3-256 and SHAKE256 available
 
-## Constant-time comparison
+## Security status
 
-`==` on `PublicKey` / `SecretKey` instances uses OpenSSL
-`CRYPTO_memcmp` through a `PQCrypto.ct_equals` helper so comparisons
-do not leak timing information about a prefix match.
+`pq_crypto` is experimental and not audited. Treat it as a low-level primitive
+library, not a complete security protocol. See [`SECURITY.md`](SECURITY.md) for
+audit status, serialization caveats, hybrid-KEM notes, and interoperability
+warnings.
 
-Secret key `inspect` output is intentionally redacted and secret key
-objects do not expose a public `fingerprint` method. `wipe!` remains
-best-effort only: it clears the current Ruby string buffer owned by the
-key object, not every possible copy made by Ruby, OpenSSL, serialization,
-logging, or the garbage collector.
-
-## Introspection
+## Useful entry points
 
 ```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_xwing)
-PQCrypto::Signature.details(:ml_dsa_65)
-```
-
-## Testing helpers
-
-Deterministic test hooks are exposed under `PQCrypto::Testing` for
-regression coverage:
-
-- `ml_kem_keypair_from_seed` — requires a 64-byte `d||z` seed (FIPS 203)
-- `ml_kem_encapsulate_from_seed` — requires a 32-byte seed
-- `ml_dsa_keypair_from_seed` — requires a 32-byte seed
-- `ml_dsa_sign_from_seed` — requires a 32-byte seed
-
-These helpers are intended for tests only. They work by installing a
-thread-local seed-replay mode inside the gem's `randombytes()` for
-the duration of the call, then call the stock PQClean entrypoints.
-No internal PQClean algorithm logic is reimplemented in this gem.
-
-## Development
-
-Run the test suite with:
+PQCrypto.supported_hybrid_kems
 
-```bash
-bundle exec rake test
+PQCrypto::KEM.generate(:ml_kem_768)
+PQCrypto::Signature.generate(:ml_dsa_65)
+PQCrypto::HybridKEM.generate(:ml_kem_768_x25519_xwing)
 ```
 
-Refresh vendored PQClean sources manually only when you intentionally
-update the vendor snapshot. The refresh script has a safe pinned
-default and records the exact vendored snapshot in
-`ext/pqcrypto/vendor/.vendored`:
+## More examples
 
-```bash
-bundle exec ruby script/vendor_libs.rb
-```
+Detailed usage examples live in [`GET_STARTED.md`](GET_STARTED.md):
 
-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
-```
+- generating keys
+- ML-KEM encapsulation / decapsulation
+- ML-DSA signing / verification
+- streaming ML-DSA for large files
+- SPKI and PKCS#8 serialization
+- `pqc_container_*` compatibility serialization
+- secure wiping and practical safety notes

data/SECURITY.md

@@ -4,125 +4,144 @@
 
 `pq_crypto` exposes a primitive-first public surface:
 
-- `PQCrypto::KEM` (`ML-KEM-768`)
-- `PQCrypto::Signature` (`ML-DSA-65`)
-- `PQCrypto::HybridKEM` (`ML-KEM-768 + X25519` via the X-Wing combiner)
+- `PQCrypto::KEM` — ML-KEM-512, ML-KEM-768, ML-KEM-1024
+- `PQCrypto::Signature` — ML-DSA-44, ML-DSA-65, ML-DSA-87
+- `PQCrypto::HybridKEM` — ML-KEM-768 + X25519 via the X-Wing combiner
 - `PQCrypto.secure_wipe`
-- `PQCrypto.ct_equals` (constant-time byte-string comparison)
+- `PQCrypto.ct_equals`
 
-The gem does **not** publish protocol/session helpers as part of the
-supported public API.
+The gem does not publish protocol/session helpers as part of the supported
+public API.
 
 ## Audit status
 
 This project has not been audited. Treat it as experimental software.
 
+The test surface includes deterministic regression tests, NIST ACVP KAT test
+infrastructure, and OpenSSL 3.5+ interoperability tests for standard SPKI /
+PKCS#8 encodings where the linked OpenSSL exposes the corresponding ML-KEM /
+ML-DSA EVP support. These tests improve compatibility coverage but are not a
+substitute for a security audit.
+
 ## Algorithm notes
 
-### ML-KEM-768 / ML-DSA-65
+### 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 only. Internal PQClean symbols are not called from this
-gem.
+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.
 
 ### HybridKEM
 
-`PQCrypto::HybridKEM` implements the **X-Wing** construction from
-[`draft-connolly-cfrg-xwing-kem-10`](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/).
-
-The X-Wing secret decapsulation key is a 32-byte seed. It is expanded
-with SHAKE256 into the ML-KEM-768 and X25519 private material used
-internally for decapsulation. The public key and ciphertext are the
-fixed-length concatenations specified by the draft.
+`PQCrypto::HybridKEM` implements the X-Wing construction from
+`draft-connolly-cfrg-xwing-kem-10`.
 
-    ss = SHA3-256( ss_M || ss_X || ct_X || pk_X || XWingLabel )
+The X-Wing secret decapsulation key is a 32-byte seed. It is expanded with
+SHAKE256 into the ML-KEM-768 and X25519 private material used internally for
+decapsulation. The public key and ciphertext are the fixed-length
+concatenations specified by the draft.
 
-where `XWingLabel = "\.//^\"` (6 ASCII bytes).
+```text
+ss = SHA3-256( ss_M || ss_X || ct_X || pk_X || XWingLabel )
+```
 
-X-Wing as specified has a proof of classical IND-CCA security under
-the strong Diffie-Hellman assumption for X25519 (in the ROM), and
-post-quantum IND-CCA security in the standard model assuming ML-KEM-768
-is IND-CCA secure and SHA3-256 behaves as a PRF.
+where `XWingLabel = "\.//^\"`.
 
-This gem is intended to match the X-Wing draft as of version 10. External
-interoperability should still be verified against the reference
+External interoperability should be verified against the reference
 implementation before relying on it.
 
-### Deterministic test hooks
+## Serialization formats
 
-`PQCrypto::Testing` deterministic helpers drive the stock PQClean
-`crypto_sign_keypair` / `crypto_sign_signature` (for ML-DSA) and
-`crypto_kem_keypair_derand` / `crypto_kem_enc_derand` (for ML-KEM)
-against a caller-supplied seed. 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 directly to OpenSSL `RAND_bytes`. No
-internal PQClean algorithm logic is reimplemented in this gem.
+### pq_crypto-local `pqc_container_*`
 
-## Serialization
+`pqc_container_*` DER/PEM wrappers are pq_crypto-specific containers. They are:
 
-`pqc_container_*` DER/PEM wrappers are pq_crypto-specific containers.
+- not ASN.1
+- not SPKI
+- not PKCS#8
+- not advertised as interoperable with OpenSSL, Go, Java, or PKI tooling
 
-They are:
+This format is frozen for backward compatibility and remains limited to the
+original three algorithms:
 
-- not real SPKI
-- not real PKCS#8
-- not advertised as interoperable with OpenSSL, Go, Java, or PKI tooling
+- `:ml_kem_768`
+- `:ml_dsa_65`
+- `:ml_kem_768_x25519_xwing`
+
+### Standard SPKI / PKCS#8
+
+ML-KEM and ML-DSA use standard SPKI public-key and PKCS#8 private-key encodings
+for the NIST parameter sets. AlgorithmIdentifier parameters are absent, not
+encoded as `NULL`.
+
+| Algorithm | Standard OID | Reference |
+| --- | --- | --- |
+| ML-KEM-512 | `2.16.840.1.101.3.4.4.1` | RFC 9935 |
+| ML-KEM-768 | `2.16.840.1.101.3.4.4.2` | RFC 9935 |
+| ML-KEM-1024 | `2.16.840.1.101.3.4.4.3` | RFC 9935 |
+| ML-DSA-44 | `2.16.840.1.101.3.4.3.17` | RFC 9881 |
+| ML-DSA-65 | `2.16.840.1.101.3.4.3.18` | RFC 9881 |
+| ML-DSA-87 | `2.16.840.1.101.3.4.3.19` | RFC 9881 |
+
+`PQCrypto::KEM.details` / `PQCrypto::Signature.details` keep `:oid` as the
+legacy `pqc_container_*` OID for backward compatibility. Use
+`PQCrypto::AlgorithmRegistry.standard_oid` for the standard OID.
 
-The `pqc_container_*` envelope itself is project-specific. ML-KEM and
-ML-DSA currently use project-local UUID-derived OIDs under `2.25.*`.
-Hybrid X-Wing uses the draft X-Wing OID `1.3.6.1.4.1.62253.25722`.
+## ML-DSA seed-format imports
 
-The hybrid OID used by 0.2.0
-(`2.25.260242945110721168101139140490528778800`) is retired. The
-intermediate 0.3.0 project-local hybrid OID
-(`2.25.318532651283923671095712569430174917109`) is also retired in
-favor of the draft X-Wing OID. Older hybrid containers are rejected at
-decode time.
+ML-DSA seed and both-form PKCS#8 imports are disabled by default. To import
+these encodings, callers must explicitly set:
+
+```ruby
+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
+expandedKey half does not match the seed-derived key.
+
+## 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
+directly to OpenSSL `RAND_bytes`.
 
 ## Memory wiping
 
-`PQCrypto.secure_wipe` clears mutable Ruby strings in place. Ruby key
-objects (`PublicKey`, `SecretKey`) take a copy of the bytes passed into
-their constructor and expose `#wipe!` to zero only that internal copy
-— any prior Ruby string the caller still holds is untouched. Ruby
-garbage collection and prior derived copies may still leave sensitive
-material elsewhere in process memory.
+`PQCrypto.secure_wipe` clears mutable Ruby strings in place. Ruby key objects
+take a copy of the bytes passed into their constructor and expose `#wipe!` to
+zero only that internal copy. Ruby garbage collection and prior derived copies
+may still leave sensitive material elsewhere in process memory.
+
+Secret key objects redact `inspect` output and intentionally do not expose a
+public `fingerprint` method. This avoids accidental logging of raw secret bytes
+or stable secret-derived identifiers.
 
 ## OpenSSL baseline
 
-`pq_crypto` requires OpenSSL **3.0 or later**.
+`pq_crypto` requires OpenSSL 3.0 or later.
 
 OpenSSL is used for:
 
-- `X25519` key generation and key agreement (`EVP_PKEY_*`)
-- `SHA3-256` (X-Wing combiner, via `EVP_sha3_256`)
-- `RAND_bytes` (production entropy source for `randombytes()`)
-- `CRYPTO_memcmp` (constant-time comparison used by `PQCrypto.ct_equals`)
-- Base64 encode/decode for PEM via OpenSSL `BIO_f_base64`, with strict
-  header/footer framing and trailing-garbage checks.
-
-## Secret key display and wiping
-
-Secret key objects redact `inspect` output and intentionally do not expose
-a public `fingerprint` method. This avoids accidental logging of raw secret
-bytes or stable secret-derived identifiers.
+- X25519 key generation and key agreement
+- 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
 
-`wipe!` is best-effort only. It wipes the current Ruby string buffer held
-by the key object; it cannot guarantee erasure of copies made by Ruby,
-OpenSSL, native wrapper buffers, serialization, logging, crash dumps, or
-the garbage collector.
+OpenSSL 3.5+ is additionally used in interop tests when ML-KEM / ML-DSA EVP
+support is available.
 
 ## 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.
-
-The deterministic test hooks use a thread-local seed-replay mode
-around `randombytes()`, so a test running on one thread does not
-affect production callers on other threads. The deterministic helpers
-remain test-only utilities and should not be relied on as a general
-multi-threading contract.
+Mutating operations such as `wipe!` must not race with other uses of the same
+object.

data/ext/pqcrypto/extconf.rb

@@ -2,6 +2,27 @@
 # frozen_string_literal: true
 
 require "mkmf"
+require_relative "../../lib/pq_crypto/version"
+
+def generate_version_header!
+  version = PQCrypto::VERSION
+  unless version.match?(/\A[0-9A-Za-z][0-9A-Za-z._+-]*\z/)
+    abort "Invalid PQCrypto::VERSION for C header: #{version.inspect}"
+  end
+
+  header = File.join(__dir__, "pqcrypto_version.h")
+  File.write(header, <<~C)
+    /* Generated by extconf.rb from lib/pq_crypto/version.rb. Do not edit. */
+    #ifndef PQCRYPTO_VERSION_H
+    #define PQCRYPTO_VERSION_H
+
+    #define PQCRYPTO_VERSION #{version.dump}
+
+    #endif
+  C
+end
+
+generate_version_header!
 
 $CFLAGS << " -std=c11 -Wall -Wextra -O2"
 $CFLAGS << " -fstack-protector-strong -D_FORTIFY_SOURCE=2"
@@ -11,6 +32,9 @@ $LDFLAGS << " -Wl,-no_warn_duplicate_libraries" if RbConfig::CONFIG["host_os"] =
 
 USE_SYSTEM = arg_config("--use-system-libraries") || ENV["PQCRYPTO_USE_SYSTEM_LIBRARIES"]
 
+KECCAK_BACKEND = (ENV["PQCRYPTO_KECCAK_BACKEND"] || "clean").strip.downcase
+SUPPORTED_KECCAK_BACKENDS = %w[clean xkcp].freeze
+
 SANITIZE = ENV["PQCRYPTO_SANITIZE"]
 
 if SANITIZE && !SANITIZE.strip.empty?
@@ -85,27 +109,77 @@ def configure_openssl!
   $CFLAGS << " -DHAVE_OPENSSL_EVP_H -DHAVE_OPENSSL_RAND_H"
 end
 
+def configure_keccak_backend(vendor_dir, common_dir)
+  abort "Unsupported PQCRYPTO_KECCAK_BACKEND=#{KECCAK_BACKEND.inspect}. Supported: #{SUPPORTED_KECCAK_BACKENDS.join(", ")}" unless SUPPORTED_KECCAK_BACKENDS.include?(KECCAK_BACKEND)
+
+  case KECCAK_BACKEND
+  when "clean"
+    {
+      name: "clean",
+      include_dirs: [],
+      source_group: ["pqclean_common", [File.join(common_dir, "fips202.c")]]
+    }
+  when "xkcp"
+    # The optimized backend must provide the same fips202.h-compatible API as
+    # PQClean's common/fips202.c. Do not substitute OpenSSL EVP SHAKE here: the
+    # PQClean SHAKE state layout is part of the ML-KEM/ML-DSA call graph.
+    xkcp_dir = File.join(vendor_dir, "xkcp")
+    adapter_source = File.join(xkcp_dir, "pqclean_fips202_xkcp.c")
+
+    abort <<~MSG unless File.exist?(adapter_source)
+      PQCRYPTO_KECCAK_BACKEND=xkcp was requested, but no reviewed XKCP adapter was found.
+
+      Expected:
+        #{adapter_source}
+
+      Refusing to fall back silently to the clean backend. Vendor a fips202.h-compatible
+      XKCP adapter first, then run the full SHAKE-dependent KAT/regression test matrix.
+    MSG
+
+    {
+      name: "xkcp",
+      include_dirs: [xkcp_dir],
+      source_group: ["xkcp_keccak", [adapter_source]]
+    }
+  end
+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")
+  mlkem_dirs = {
+    "pqclean_mlkem512" => File.join(pqclean_dir, "crypto_kem", "ml-kem-512", "clean"),
+    "pqclean_mlkem768" => File.join(pqclean_dir, "crypto_kem", "ml-kem-768", "clean"),
+    "pqclean_mlkem1024" => File.join(pqclean_dir, "crypto_kem", "ml-kem-1024", "clean")
+  }
+  mldsa_dirs = {
+    "pqclean_mldsa44" => File.join(pqclean_dir, "crypto_sign", "ml-dsa-44", "clean"),
+    "pqclean_mldsa65" => File.join(pqclean_dir, "crypto_sign", "ml-dsa-65", "clean"),
+    "pqclean_mldsa87" => File.join(pqclean_dir, "crypto_sign", "ml-dsa-87", "clean")
+  }
   common_dir = File.join(pqclean_dir, "common")
 
-  include_dirs = [mlkem_dir, mldsa_dir, common_dir]
+  keccak_config = configure_keccak_backend(vendor_dir, common_dir)
+
+  include_dirs = [*mlkem_dirs.values, *mldsa_dirs.values, common_dir, *keccak_config[:include_dirs]]
   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].map { |name| File.join(common_dir, name) }
+  mlkem_source_groups = mlkem_dirs.map do |prefix, dir|
+    [prefix, Dir.glob(File.join(dir, "*.c")).sort]
+  end
+  mldsa_source_groups = mldsa_dirs.map do |prefix, dir|
+    [prefix, Dir.glob(File.join(dir, "*.c")).sort]
+  end
+  common_sources = %w[sha2.c sp800-185.c].map { |name| File.join(common_dir, name) }
 
   source_groups = [
-    ["pqclean_mlkem", mlkem_sources],
-    ["pqclean_mldsa", mldsa_sources],
-    ["pqclean_common", common_sources]
+    *mlkem_source_groups,
+    *mldsa_source_groups,
+    ["pqclean_common", common_sources],
+    keccak_config[:source_group]
   ]
 
   return nil unless source_groups.all? { |_, sources| sources.all? { |path| File.exist?(path) } }
@@ -115,6 +189,7 @@ def configure_pqclean(vendor_dir)
 
   {
     include_dirs: include_dirs,
+    keccak_backend: keccak_config[:name],
     source_groups: source_groups
   }
 end
@@ -165,6 +240,7 @@ 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 (randombytes overridden by pq_randombytes.c)"
+puts "Keccak backend: #{pqclean_config[:keccak_backend]}"
 puts "Output: pqcrypto/pqcrypto_secure"
 puts "===================================="