pq_crypto 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9f15d910879cdfa645c90795ee80932a0261322401f42e05a0623ce938cfce7
-  data.tar.gz: 126bd8e2435fedfe9aa46b046bf98215e972f9fc81d5856414015357afee6bbf
+  metadata.gz: 534c420f62323e9ddb49b48acdfa7af869731e3273bda56637d6bfee753de8d7
+  data.tar.gz: f003494b4d33702a1b718dc6ded7a9f0612b315e41f0d739a5b2fe3ebba9d1d1
 SHA512:
-  metadata.gz: 154020cb51f31d414e83c09cf9a7cc410fc8395500a97777fb741ff77986f4e5ae2fda7e64e932eaf17eb9d653901a63f114d5710a672aa5f954e756c2509898
-  data.tar.gz: c2ea78f4b001a32d486f876832832248261bf42d80ddbbe5821faed59240d6d55c80e67ed486c4476a1e47ae5fd1d46cbf64fc0903f2483ff8c3cf34c15a2388
+  metadata.gz: 1a039325a13cf8c074741fb70edc1e66f4e4939727b4c1369665794bc6ed71ef1ed2ef50d9debd9064d850e4856fac166f325889a9df4bfd3d8849a2d7a918e9
+  data.tar.gz: 304888656181149eed84eca063e24eeb6c862819f6c54022e77b287ca4030b8602e9f61eb17809ad86ca0eea84796c6275a2afa12018ffdeaafc489c15c8f24a

data/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## [0.3.1] — 2026-04-24
+
+### Fixed — X-Wing draft-10 compatibility
+
+- Changed `:ml_kem_768_x25519_xwing` secret keys to the draft-10 32-byte
+  X-Wing decapsulation seed and derive ML-KEM/X25519 private material with
+  SHAKE256 during key generation and decapsulation.
+- Corrected the X-Wing combiner transcript to
+  `ss = SHA3-256( ss_M || ss_X || ct_X || pk_X || XWingLabel )`.
+- Updated the hybrid serialization OID to the X-Wing draft OID
+  `1.3.6.1.4.1.62253.25722`.
+- Redacted key `inspect` output, removed public secret-key fingerprints,
+  improved native extension load diagnostics, switched the extension build
+  flag to C11, and aligned docs with the implementation.
+
+## [0.3.0] — 2026-04-24
+
+**Breaking release.** Hybrid KEM keys, ciphertexts, and `pqc_container_*`
+blobs produced by 0.2.0 are not compatible with 0.3.0. Pure ML-KEM-768
+and ML-DSA-65 material is unaffected.
+
+### Changed — hybrid KEM (breaking)
+
+- Replaced the 0.2.0 ad-hoc `HKDF-SHA256`-with-double-transcript combiner
+  with a SHA3-256 X-Wing-inspired combiner. This was later corrected in
+  `0.3.1` to match draft-10 transcript order and 32-byte secret keys.
+- Renamed the hybrid algorithm symbol
+  `:ml_kem_768_x25519_hkdf_sha256` → `:ml_kem_768_x25519_xwing`.
+- Retired the 0.2.0 project-local hybrid OID
+  (`2.25.260242945110721168101139140490528778800`). 0.3.0 used
+  `2.25.318532651283923671095712569430174917109`; this was later replaced
+  in `0.3.1` by the X-Wing draft OID.
+
+### Changed — native code hygiene
+
+- Removed the copy of PQClean internal ML-DSA keypair and signature logic
+  that 0.2.0 used to implement deterministic test hooks. Tests now drive
+  the stock PQClean `crypto_sign_keypair` / `crypto_sign_signature`
+  through a new `randombytes()` override
+  (`ext/pqcrypto/pq_randombytes.c`) that swaps in a thread-local
+  seed-replay mode for the duration of a deterministic call and delegates
+  to `OpenSSL RAND_bytes` otherwise.
+- Deleted the non-FIPS 32-byte ML-KEM seed with HKDF expansion; the
+  deterministic ML-KEM keypair hook now accepts only the
+  FIPS 203 64-byte `d||z` seed.
+- Replaced `uint8_t*` → `hybrid_*_t*` strict-aliasing casts with
+  explicit `memcpy` into typed stack locals throughout the hybrid path.
+- Added `_Static_assert` guards on the byte-packed layout of
+  `hybrid_public_key_t`, `hybrid_secret_key_t`, and
+  `hybrid_ciphertext_t` so any future change that introduces padding
+  fails at compile time rather than silently shifting byte offsets.
+- Migrated PEM codec to OpenSSL `BIO_f_base64` with stricter PEM
+  header/footer framing and trailing-garbage checks.
+- Deleted the entire internal HKDF and SHA-256 helper paths that 0.2.0
+  used for its combiner; the X-Wing combiner is a single SHA3-256
+  invocation through `EVP_DigestUpdate`.
+- Tightened `extconf.rb`: the broad `-Wno-unused-parameter`
+  `-Wno-unused-function` `-Wno-strict-prototypes` `-Wno-pedantic`
+  `-Wno-c23-extensions` `-Wno-undef` suppressions now apply **only** to
+  vendored PQClean translation units; our own code compiles with the
+  strict warning set. Added a compile probe for `EVP_sha3_256`.
+
+### Changed — Ruby API
+
+- `Signature::PublicKey#verify` now returns `true` / `false` for normal
+  cryptographic outcomes. Previously an invalid signature surfaced
+  through a caught `VerificationError`; the native entrypoint no longer
+  raises for this case. `verify!` still raises on mismatch.
+- `PublicKey#==` / `SecretKey#==` on all key types now use OpenSSL
+  `CRYPTO_memcmp` through a new `PQCrypto.ct_equals` native helper, so
+  key equality checks no longer leak timing information about a
+  prefix-match.
+- `PublicKey#hash` and `SecretKey#hash` now hash a SHA-256 fingerprint
+  of the bytes instead of the raw bytes. The public secret-key fingerprint
+  method is removed in `0.3.1` to reduce accidental logging risk.
+- Native entrypoints and their `native_*` aliases are installed once via
+  the new `PQCrypto::NativeBindings` module instead of the ad-hoc
+  `unless method_defined?` guards on the singleton.
+- Renamed `Signature.validate_algorithm!` → `resolve_algorithm!` to
+  match `KEM` / `HybridKEM`.
+
+### Changed — packaging
+
+- Intended to change `required_ruby_version` from `">= 3.4.0.a"` to
+  `">= 3.4"`; the gemspec is aligned in `0.3.1`.
+- Version bumped to `0.3.0`.
+- `VerificationError` class is still defined (and still raised by
+  `verify!`) for backward compatibility, but the native `verify`
+  entrypoint no longer raises it.
+
+### Migration notes
+
+- Hybrid keys and ciphertexts must be regenerated with 0.3.0; old blobs
+  are rejected by the new container decoder.
+- Code referencing the old hybrid symbol must update to
+  `:ml_kem_768_x25519_xwing`. Pure ML-KEM and ML-DSA symbols are
+  unchanged.
+- Code relying on `verify` raising `VerificationError` should switch
+  to `verify!` or a `verify` + explicit `false` check.
+
 ## [0.2.0]
 
 ### Changed

data/GET_STARTED.md

@@ -30,18 +30,24 @@ sig = PQCrypto::Signature.generate(:ml_dsa_65)
 
 ```ruby
 signature = sig.secret_key.sign("message")
+
+sig.public_key.verify("message", signature)
 sig.public_key.verify!("message", signature)
 ```
 
-## 6. Optional hybrid KEM
+## 6. Hybrid KEM (X-Wing)
 
 ```ruby
-hybrid = PQCrypto::HybridKEM.generate(:ml_kem_768_x25519_hkdf_sha256)
+hybrid = PQCrypto::HybridKEM.generate(:ml_kem_768_x25519_xwing)
 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.
+The raw X-Wing secret key exported by this API is the draft-10 32-byte
+decapsulation seed, not the expanded ML-KEM/X25519 private material.
+
+The hybrid mode follows `draft-connolly-cfrg-xwing-kem`. See
+`SECURITY.md` for audit status.
 
 ## 7. Serialize a key
 
@@ -50,16 +56,20 @@ der = keypair.public_key.to_pqc_container_der
 imported = PQCrypto::KEM.public_key_from_pqc_container_der(der)
 ```
 
+`pqc_container_*` formats are pq_crypto-specific.
+
 ## 8. Inspect supported algorithms
 
 ```ruby
-PQCrypto.supported_kems
-PQCrypto.supported_hybrid_kems
-PQCrypto.supported_signatures
+PQCrypto.supported_kems           # => [:ml_kem_768]
+PQCrypto.supported_hybrid_kems    # => [:ml_kem_768_x25519_xwing]
+PQCrypto.supported_signatures     # => [:ml_dsa_65]
 ```
 
 ## 9. Practical notes
 
-- OpenSSL 3.0+ is required.
-- `pqc_container_*` formats are pq_crypto-specific.
-- `PQCrypto::Testing` exposes deterministic helpers only for regression tests.
+- OpenSSL 3.0+ with SHA3-256 is required.
+- `PQCrypto::Testing` exposes deterministic helpers only for
+  regression tests.
+- Key equality uses constant-time comparison. `#hash` returns a
+  hash derived from a SHA-256 fingerprint, not the raw bytes.

data/README.md

@@ -2,17 +2,22 @@
 
 `pq_crypto` is a primitive-first Ruby gem for post-quantum cryptography.
 
-It currently exposes three public building blocks:
+It 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`
+- `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 OpenSSL for conventional primitives such as `X25519` and `HKDF-SHA256`.
+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
 
-- first public release
 - primitive-first API only
 - no protocol/session helpers in the public surface
 - serialization uses pq_crypto-specific `pqc_container_*` wrappers
@@ -36,19 +41,25 @@ bundle exec rake compile
 ### Native dependencies
 
 - Ruby 3.4.x
-- a C toolchain
-- OpenSSL **3.0 or later**
+- 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.
+`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.
+- 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.
+This integration is intentionally limited to `sign` and `verify`; the
+faster primitive operations keep the lower-overhead path.
 
 Example with `Async`:
 
@@ -92,18 +103,33 @@ shared_secret = keypair.secret_key.decapsulate(result.ciphertext)
 ```ruby
 keypair = PQCrypto::Signature.generate(:ml_dsa_65)
 signature = keypair.secret_key.sign("hello")
-keypair.public_key.verify!("hello", signature)
+
+keypair.public_key.verify("hello", signature)    # => true / false
+keypair.public_key.verify!("hello", signature)   # raises on mismatch
 ```
 
-### Hybrid ML-KEM-768 + X25519
+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_hkdf_sha256)
+keypair = PQCrypto::HybridKEM.generate(:ml_kem_768_x25519_xwing)
 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.
+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:
+
+```
+ss = SHA3-256( ss_M || ss_X || ct_X || pk_X || "\.//^\" )
+```
+
+as specified by `draft-connolly-cfrg-xwing-kem-10`. See `SECURITY.md`
+for audit status and interoperability caveats.
 
 ## Serialization
 
@@ -122,7 +148,37 @@ 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.
+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.
+
+## Secure wiping
+
+`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:
+
+```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
+```
+
+## Constant-time comparison
+
+`==` 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.
+
+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
 
@@ -133,20 +189,24 @@ 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::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:
+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`
+- `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.
+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
 
@@ -156,13 +216,17 @@ Run the test suite with:
 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`:
+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`:
 
 ```bash
 bundle exec ruby script/vendor_libs.rb
 ```
 
-To intentionally change the upstream snapshot, override all four pinning inputs together:
+To intentionally change the upstream snapshot, override all four
+pinning inputs together:
 
 ```bash
 PQCLEAN_VERSION=<full-git-commit> \

data/SECURITY.md

@@ -2,14 +2,16 @@
 
 ## Scope of the public API
 
-`pq_crypto` 0.1.0 exposes a primitive-first public surface:
+`pq_crypto` 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::HybridKEM` (`ML-KEM-768 + X25519` via the X-Wing combiner)
 - `PQCrypto.secure_wipe`
+- `PQCrypto.ct_equals` (constant-time byte-string comparison)
 
-The gem does **not** publish protocol/session helpers as part of the supported public API in this release.
+The gem does **not** publish protocol/session helpers as part of the
+supported public API.
 
 ## Audit status
 
@@ -19,39 +21,108 @@ This project has not been audited. Treat it as experimental software.
 
 ### ML-KEM-768 / ML-DSA-65
 
-The core post-quantum primitives are backed by vendored `PQClean` sources.
+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.
 
 ### HybridKEM
 
-`PQCrypto::HybridKEM` is a pq_crypto-specific hybrid combiner. It is **not** claimed to be HPKE-, TLS-, or X-Wing-compatible.
+`PQCrypto::HybridKEM` implements the **X-Wing** construction from
+[`draft-connolly-cfrg-xwing-kem-10`](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/).
 
-Use it only if you explicitly want this project-local construction.
+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.
+
+    ss = SHA3-256( ss_M || ss_X || ct_X || pk_X || XWingLabel )
+
+where `XWingLabel = "\.//^\"` (6 ASCII bytes).
+
+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.
+
+This gem is intended to match the X-Wing draft as of version 10. External
+interoperability should still be verified against the reference
+implementation before relying on it.
+
+### Deterministic test hooks
+
+`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.
 
 ## 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.
+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`.
 
-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.
+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.
 
 ## 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.
+`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.
 
 ## OpenSSL baseline
 
 `pq_crypto` requires OpenSSL **3.0 or later**.
 
-OpenSSL is used for conventional primitives and plumbing such as:
-- `X25519`
-- `HKDF-SHA256`
+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.
+
+`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.
 
 ## 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.
+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.

data/ext/pqcrypto/extconf.rb

@@ -3,10 +3,9 @@
 
 require "mkmf"
 
-$CFLAGS << " -std=c99 -Wall -Wextra -O2"
+$CFLAGS << " -std=c11 -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"
+VENDOR_ONLY_CFLAGS = "-Wno-unused-parameter -Wno-unused-function -Wno-strict-prototypes -Wno-pedantic -Wno-c23-extensions -Wno-undef"
 
 $LDFLAGS << " -Wl,-no_warn_duplicate_libraries" if RbConfig::CONFIG["host_os"] =~ /darwin/
 
@@ -16,6 +15,7 @@ SANITIZE = ENV["PQCRYPTO_SANITIZE"]
 
 if SANITIZE && !SANITIZE.strip.empty?
   sanitize = SANITIZE.strip
+  $CFLAGS.gsub!(/\s-D_FORTIFY_SOURCE=\d+/, "")
   $CFLAGS << " -O1 -g -fno-omit-frame-pointer -fsanitize=#{sanitize}"
   $LDFLAGS << " -fsanitize=#{sanitize}"
 end
@@ -52,7 +52,7 @@ def configure_openssl!
   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")
+  abort "openssl/crypto.h is required" unless have_header("openssl/crypto.h")
 
   version_check = <<~SRC
     #include <openssl/opensslv.h>
@@ -64,7 +64,25 @@ def configure_openssl!
 
   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"
+  sha3_check = <<~SRC
+    #include <openssl/evp.h>
+    int main(void) {
+        const EVP_MD *md = EVP_sha3_256();
+        return md == NULL ? 1 : 0;
+    }
+  SRC
+  abort "OpenSSL SHA3-256 is required (X-Wing combiner)" unless try_compile(sha3_check)
+
+  shake_check = <<~SRC
+    #include <openssl/evp.h>
+    int main(void) {
+        const EVP_MD *md = EVP_shake256();
+        return md == NULL ? 1 : 0;
+    }
+  SRC
+  abort "OpenSSL SHAKE256 is required (X-Wing key expansion)" unless try_compile(shake_check)
+
+  $CFLAGS << " -DHAVE_OPENSSL_EVP_H -DHAVE_OPENSSL_RAND_H"
 end
 
 def configure_pqclean(vendor_dir)
@@ -82,7 +100,7 @@ def configure_pqclean(vendor_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) }
+  common_sources = %w[fips202.c sha2.c sp800-185.c].map { |name| File.join(common_dir, name) }
 
   source_groups = [
     ["pqclean_mlkem", mlkem_sources],
@@ -92,7 +110,7 @@ def configure_pqclean(vendor_dir)
 
   return nil unless source_groups.all? { |_, sources| sources.all? { |path| File.exist?(path) } }
 
-  $CFLAGS << " -DHAVE_PQCLEAN -Wno-undef"
+  $CFLAGS << " -DHAVE_PQCLEAN"
   include_dirs.each { |dir| $CPPFLAGS << " -I#{dir}" }
 
   {
@@ -117,7 +135,7 @@ def inject_pqclean_sources!(pqclean_config)
       build_rules << <<~RULE
         #{object}: #{source}
         	$(ECHO) compiling #{source}
-        	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -c $(CSRCFLAG)$<
+        	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) #{VENDOR_ONLY_CFLAGS} $(COUTFLAG)$@ -c $(CSRCFLAG)$<
       RULE
     end
   end
@@ -138,9 +156,6 @@ def inject_pqclean_sources!(pqclean_config)
   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
@@ -149,7 +164,7 @@ 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 "PQClean: vendored (randombytes overridden by pq_randombytes.c)"
 puts "Output: pqcrypto/pqcrypto_secure"
 puts "===================================="
 

data/ext/pqcrypto/pq_randombytes.c

@@ -0,0 +1,56 @@
+#include "pqcrypto_secure.h"
+
+#include <stdint.h>
+#include <string.h>
+
+#include <openssl/rand.h>
+#include "randombytes.h"
+
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L
+#define PQ_THREAD_LOCAL _Thread_local
+#elif defined(__GNUC__) || defined(__clang__)
+#define PQ_THREAD_LOCAL __thread
+#else
+#define PQ_THREAD_LOCAL
+#endif
+
+static PQ_THREAD_LOCAL const uint8_t *pq_test_seed_ptr = NULL;
+static PQ_THREAD_LOCAL size_t pq_test_seed_remaining = 0;
+
+void pq_testing_set_seed(const uint8_t *seed, size_t len) {
+    pq_test_seed_ptr = seed;
+    pq_test_seed_remaining = (seed != NULL) ? len : 0;
+}
+
+void pq_testing_clear_seed(void) {
+    pq_test_seed_ptr = NULL;
+    pq_test_seed_remaining = 0;
+}
+
+int pq_testing_seed_active(void) {
+    return pq_test_seed_ptr != NULL;
+}
+
+int randombytes(uint8_t *output, size_t n) {
+    if (output == NULL) {
+        return -1;
+    }
+
+    if (pq_test_seed_ptr != NULL) {
+        if (pq_test_seed_remaining < n) {
+            return -1;
+        }
+        memcpy(output, pq_test_seed_ptr, n);
+        pq_test_seed_ptr += n;
+        pq_test_seed_remaining -= n;
+        return 0;
+    }
+
+    if (n > INT_MAX) {
+        return -1;
+    }
+    if (RAND_bytes(output, (int)n) != 1) {
+        return -1;
+    }
+    return 0;
+}