pq_crypto 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcc40bb87fcd74ce1d16bb32d99df894cb127e0c77c879cba7ec7d6ef8e099e8
-  data.tar.gz: 6baf54010794cca2d1a9f81f884f1a6db16355515f83ed1812baa57feeaf63dc
+  metadata.gz: 15356ea593b25eefd75360992b4b716df348601a5198b8085e271e866e431371
+  data.tar.gz: b9667b1d123009b44009b8819f02c1f2855bd5117bd6142faa36cef3bcd4bf22
 SHA512:
-  metadata.gz: feb14e5bc0aefc8fa3b9b3d24083cd93923466d9bc1c5a1e4e527325f0290124be785da63aca97e342c9885e1e56b92e2637007a93c47d85ac950bee2317af71
-  data.tar.gz: 1a7773c9850dfea54df3897a6ee092f99258e25b0fa5393c977fa7e70c3eed309bca54044711501a6475f0d30ca56753eecaa768e87c9620a4e581b015c3332a
+  metadata.gz: 722560e27ea481d4f9acaee6798b3a34c06796d5d365a2164cb6ca612917e1b6db0e06e36c74b7624b1f33a78ab3e91930f3e67b5e67988363c4498cba24e585
+  data.tar.gz: 843fdee9d26cca30bfe5e6013a759713a062f9d63b08544ea5727b86b3b94e9b58dab0a201d52d0fe2e94c6aedb6ec7c770743bab65ea6d1fbf8545a71d81abc

data/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
-        ruby: ["3.1", "3.2", "3.3", "3.4"]
+        ruby: ["3.4", "4.0"]
 
     steps:
       - name: Checkout

data/CHANGELOG.md

@@ -1,5 +1,107 @@
 # Changelog
 
+## [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 the **X-Wing** construction from
+  [draft-connolly-cfrg-xwing-kem](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/):
+  `ss = SHA3-256( XWingLabel || ss_M || ss_X || ct_X || pk_X )`, where
+  `XWingLabel` is the 6-byte ASCII string `\.//^\`.
+- 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`). The new OID
+  (`2.25.318532651283923671095712569430174917109`) identifies the X-Wing
+  combiner. `pqc_container_*` blobs carry the new OID; decoding a 0.2.0
+  hybrid container now fails fast with `SerializationError`.
+
+### 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 from `EVP_EncodeBlock` / `EVP_DecodeBlock` to the
+  streaming `EVP_EncodeUpdate` / `EVP_DecodeUpdate` API, which rejects
+  invalid base64 characters rather than treating them as zeros.
+- 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.
+- `SecretKey#hash` (and `PublicKey#hash` for symmetry) now hash a
+  SHA-256 fingerprint of the bytes instead of the raw bytes, and a
+  public `#fingerprint` method is exposed.
+- 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
+
+- `required_ruby_version` from `">= 3.4.0.a"` to `">= 3.4"`.
+- 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
+
+- Raised the minimum supported Ruby to the 3.4 series.
+- Switched `PQCrypto::Signature::SecretKey#sign` and `PQCrypto::Signature::PublicKey#verify` to Ruby 3.4's scheduler-aware `rb_nogvl(..., RB_NOGVL_OFFLOAD_SAFE)` path.
+- Left the faster KEM and key-generation operations on the existing lower-overhead no-GVL path.
+- Removed gem-specific scheduler configuration; runtime behavior now follows the active Ruby Fiber scheduler automatically.
+
+### Testing
+
+- Added Async integration tests that verify sibling `task.async` work keeps making progress while `sign` and `verify` run under an Async worker-pool-enabled reactor.
+- Updated CI to target the supported Ruby 3.4 series.
+
 ## [0.1.0]
 
 Initial public release.

data/GET_STARTED.md

@@ -30,18 +30,21 @@ 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 hybrid mode follows `draft-connolly-cfrg-xwing-kem`. See
+`SECURITY.md` for audit status.
 
 ## 7. Serialize a key
 
@@ -50,16 +53,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`, streaming `EVP_Encode*` /
+`EVP_Decode*`) — 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
@@ -35,9 +40,53 @@ bundle exec rake compile
 
 ### Native dependencies
 
-- Ruby 3.1+
-- a C toolchain
-- OpenSSL **3.0 or later**
+- Ruby 3.4.x
+- a C toolchain with C11 support (for `_Static_assert` / `_Thread_local`)
+- OpenSSL **3.0 or later** with SHA3-256 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
 
@@ -54,18 +103,31 @@ 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 combiner is exactly:
+
+```
+ss = SHA3-256( "\.//^\" || ss_M || ss_X || ct_X || pk_X )
+```
+
+as specified by `draft-connolly-cfrg-xwing-kem`. See `SECURITY.md` for
+audit status and interoperability caveats.
 
 ## Serialization
 
@@ -84,7 +146,31 @@ 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.
 
 ## Introspection
 
@@ -95,20 +181,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
 
@@ -118,13 +208,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` 0.3.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::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,96 @@ 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`](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/):
 
-Use it only if you explicitly want this project-local construction.
+    ss = SHA3-256( XWingLabel || ss_M || ss_X || ct_X || pk_X )
+
+where `XWingLabel = "\.//^\"` (6 ASCII bytes). The hybrid public key,
+secret key, and ciphertext are the byte concatenations of the ML-KEM
+and X25519 halves exactly as specified by X-Wing.
+
+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 **not** yet part of a cross-language X-Wing interop test
+suite; wire-format claims for this release are limited to "follows the
+X-Wing draft as of version 10." External interoperability should 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 OIDs embedded in these containers are project-local UUID-derived
+OIDs under `2.25.*`. They are part of pq_crypto's own serialized
+container schema, not 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.
+The hybrid OID used by 0.2.0
+(`2.25.260242945110721168101139140490528778800`) is retired in 0.3.0
+because the combiner semantics changed (0.2.0 used an ad-hoc
+HKDF-SHA256 combiner; 0.3.0 uses X-Wing / SHA3-256). The new hybrid
+OID is `2.25.318532651283923671095712569430174917109`. A 0.2.0 hybrid
+container is rejected at decode time in 0.3.0.
 
 ## 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 the streaming `EVP_Encode*` /
+  `EVP_Decode*` API, which rejects invalid base64 rather than treating
+  it as zeros.
 
 ## 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

@@ -5,8 +5,7 @@ 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"
+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/
 
@@ -52,7 +51,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 +63,16 @@ 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)
+
+  $CFLAGS << " -DHAVE_OPENSSL_EVP_H -DHAVE_OPENSSL_RAND_H"
 end
 
 def configure_pqclean(vendor_dir)
@@ -82,7 +90,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 +100,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 +125,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 +146,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 +154,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;
+}