pq_crypto 0.3.2 → 0.5.0

data/README.md

@@ -1,284 +1,127 @@
 # 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
-- streaming ML-DSA signing/verification is available for large IO inputs
-- 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)
-
-### Build-time Keccak backend
-
-The default build uses PQClean's scalar `common/fips202.c` backend:
+When working from a source checkout, compile the native extension before
+running tests or examples:
 
 ```bash
-PQCRYPTO_KECCAK_BACKEND=clean 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`.
-This avoids mixing OpenSSL EVP SHAKE state with PQClean SHAKE state and
-keeps output-byte compatibility explicit.
-
-## 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
-
-One-shot signing keeps the existing API:
-
-```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
-```
-
-For large inputs, use streaming IO so the message does not need to be
-materialized as one Ruby string:
-
-```ruby
-signature = File.open("document.bin", "rb") do |io|
-  keypair.secret_key.sign_io(io, chunk_size: 1 << 20)
-end
-
-ok = File.open("document.bin", "rb") do |io|
-  keypair.public_key.verify_io(io, signature, chunk_size: 1 << 20)
-end
+bundle exec rake compile
+bundle exec rake test
 ```
 
-`sign_io` / `verify_io` use pure ML-DSA with an internal FIPS 204
-ExternalMu flow. They are not HashML-DSA/prehash shortcuts and do not
-expose public `sign_mu` / `verify_mu` APIs. With the default empty
-context, streaming signatures verify with `verify(message, signature)`
-and one-shot signatures verify with `verify_io(io, signature)`.
+## What this gem provides
 
-Optional context is supported and must match on verify:
+| 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. |
 
-```ruby
-ctx = "invoice-v1".b
-signature = File.open("document.bin", "rb") { |io| keypair.secret_key.sign_io(io, context: ctx) }
-ok = File.open("document.bin", "rb") { |io| keypair.public_key.verify_io(io, signature, context: ctx) }
-```
+## Supported algorithms
 
-`chunk_size` must be positive. `context` is limited to 255 bytes by
-FIPS 204. `verify_io!` raises `PQCrypto::VerificationError` on mismatch.
+| 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. |
 
-Note: `verify` returns a plain boolean for normal outcomes. `verify!`
-raises `PQCrypto::VerificationError` when the signature does not
-match.
+Standard encodings use RFC 9935 OIDs for ML-KEM and RFC 9881 OIDs for
+ML-DSA. `AlgorithmIdentifier.parameters` are omitted, not encoded as `NULL`.
 
-### Hybrid ML-KEM-768 + X25519 (X-Wing)
+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:
 
-```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:
+- `:ml_kem_768`
+- `:ml_dsa_65`
+- `:ml_kem_768_x25519_xwing`
 
-```
-ss = SHA3-256( ss_M || ss_X || ct_X || pk_X || "\.//^\" )
-```
+## Requirements
 
-as specified by `draft-connolly-cfrg-xwing-kem-10`. See `SECURITY.md`
-for audit status and interoperability caveats.
+- 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`
 
-## Serialization
+## Native backend
 
-Key import/export is available through pq_crypto-specific containers:
+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.
 
-- `to_pqc_container_der`
-- `to_pqc_container_pem`
-- `*_from_pqc_container_der`
-- `*_from_pqc_container_pem`
+From a source checkout, refresh the native vendor snapshot before compiling:
 
-Example:
-
-```ruby
-keypair = PQCrypto::KEM.generate(:ml_kem_768)
-der = keypair.public_key.to_pqc_container_der
-imported = PQCrypto::KEM.public_key_from_pqc_container_der(der)
+```bash
+bundle exec rake vendor
+bundle exec rake compile
 ```
 
-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 default build uses the portable native source path. Upstream native assembly
+can be tested explicitly with:
 
-## 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
+```bash
+PQCRYPTO_NATIVE_ASM=1 bundle exec rake compile
 ```
 
-## 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`:
-
-```bash
-bundle exec ruby script/vendor_libs.rb
-```
+## More examples
 
-To intentionally change the upstream snapshot, override all four
-pinning inputs together:
+Detailed usage examples live in [`GET_STARTED.md`](GET_STARTED.md):
 
-```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
+- native backend / vendoring notes
+- secure wiping and practical safety notes

data/SECURITY.md

@@ -4,125 +4,150 @@
 
 `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.
+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.
 
-### HybridKEM
+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.
 
-`PQCrypto::HybridKEM` implements the **X-Wing** construction from
-[`draft-connolly-cfrg-xwing-kem-10`](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/).
+### HybridKEM
 
-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 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 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
 
-`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
 
-`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.