pq_crypto 0.6.5 → 0.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68e8c2cd661300cb364be85b4939787590eb88217a2f3cb3463e262b66c4c662
-  data.tar.gz: fef5359500d367c68b50b2a72b54cfc8980b3c6dfd6b0e132998212e34cbd47a
+  metadata.gz: cf8d3b17b9579ef551ef337aab16a9eb356846a36ff492577e2d728ec0e285e2
+  data.tar.gz: 26c3c3646d066617e37cb2cb1219e7ee5ca640488c84b480b6259461999b48e5
 SHA512:
-  metadata.gz: 12bfac65233efde5fa34a30df51494bc6da59985287ae2b3954b377dc9afa949f16b509e98db25d7af2a61a7f3b6a4e572b21f33ff85e797a153ee0e0dde10a0
-  data.tar.gz: 25ccfe8a57150355da41a115c401d7ccee2b10a0a6a42957f8335cd3c97024d14261188ee676bc6a122557f52a4ea5894d67062dace53f983b51b4244d9d1a6a
+  metadata.gz: bd58150566a566af1c3083ef2c72538acafb6b15c5ebe954d0d7af35f96cdf41a5f1fe17c8d3c956e29b3c51bd89b29ec24245749efbca82389b1d2dc3c91ede
+  data.tar.gz: 5d974df3a99f9284da5c5cdfff25ba1808dc083063c12f97db6b803a34aa15687a0cda9565c8617edd95015c8d23139181d56d69d2483a3ac17b2239bec3cba3

data/CHANGELOG.md

@@ -1,5 +1,238 @@
 # Changelog
 
+## [0.6.7] - 2026-08-10
+
+### Fixed
+
+- **DER parsers could raise exceptions outside the `PQCrypto::Error` hierarchy.**
+  `OpenSSL::ASN1.decode` raises more than `OpenSSL::ASN1::ASN1Error`, and
+  re-encoding a successfully decoded object can fail as well. Three shapes
+  escaped the previous handling in `PQCrypto::SPKI`:
+
+  - `"\x0A\x01\xFF"` (ENUMERATED) raised `OpenSSL::OpenSSLError`
+  - `"\x17\x00"` / `"\x18\x00"` (empty UTCTIME / GENERALIZEDTIME) raised `TypeError`
+  - `"\x10\x00"` (universal SEQUENCE tag without the constructed bit) decoded
+    cleanly but raised `TypeError` from the `to_der` round trip used for the
+    trailing-data check
+
+  `TypeError` does not descend from `OpenSSL::OpenSSLError`, so widening the
+  rescue to the OpenSSL base class alone was not sufficient. Both rescue sites
+  now catch `OpenSSL::OpenSSLError, TypeError`, and `SPKI.decode_der` is guarded
+  end to end rather than only around the decode call.
+
+  Impact: code written as `rescue PQCrypto::Error` around key loading could be
+  bypassed by malformed input. No memory-safety consequence. Covered by a
+  systematic tag sweep over 1,280 DER shapes × three entry points
+  (`Key.from_der`, `SPKI.decode_der`, `PKCS8.decode_der`).
+
+### Added
+
+- **FIPS 203 key validation for ML-KEM (boundary diagnostics).** mlkem-native
+  v2 exposes `check_pk` and `check_sk`, which this gem did not use. Both are
+  now wired in and run when a `PQCrypto::KEM::PublicKey` or `SecretKey` is
+  constructed:
+
+  - public keys get the Section 7.2 modulus check (coefficients in `[0,q-1]`)
+  - secret keys get the Section 7.3 hash check (`H(pk)` embedded in the sk)
+
+  Scope limits (intentional, matching FIPS 203):
+
+  - these checks are **diagnostics at import**, not a substitute for the
+    checks already performed inside encapsulation / decapsulation
+  - Section 7.3 does **not** detect a corrupted IND-CPA secret (`dk`) when
+    the embedded `H(pk)` is still intact — `#valid?` can still be true
+  - X-Wing public keys validate only the ML-KEM-768 half; the X25519 half is
+    unrestricted. X-Wing secret keys are 32-byte seeds and are not structure-
+    checked
+
+  `#valid?` is exposed on both key classes. Failures raise
+  `PQCrypto::InvalidKeyError`. Public-key internal buffers are frozen after
+  construction to block post-validation mutation; secret-key buffers stay
+  mutable so `#wipe!` can still zero them in place.
+
+  New C API: `pq_mlkem{,512,1024}_check_public_key` / `_check_secret_key`,
+  plus `PQ_ERROR_INVALID_PUBLIC_KEY` (-11) and `PQ_ERROR_INVALID_SECRET_KEY`
+  (-12). Upstream OOM (`-2`) is mapped to `PQ_ERROR_NOMEM` rather than
+  “invalid key”.
+
+- **ML-DSA secret-key structure check on import.** Expanded ML-DSA secret
+  keys are validated via upstream `pk_from_sk` (coefficient norms, recomputed
+  `t0`, and `tr = H(pk)`). This matches the check mldsa-native documents for
+  importers and is enforced on `Signature::SecretKey` construction with
+  `#valid?` exposed. Public keys remain length-checked only (FIPS 204 has no
+  ML-KEM-style modulus check for the public key).
+
+  The check runs on import only. Keys produced by this process's own key
+  generation are valid by construction, and `pk_from_sk` re-derives the public
+  key, so validating them would roughly double the cost of every ML-DSA
+  keypair. Upstream also documents `pk_from_sk` as leaking secret-key validity
+  through its return value and timing.
+
+  New C API: `pq_mldsa{,44,87}_check_secret_key`.
+
+- **`PQCRYPTO_KEYGEN_PCT=1` build option.** Enables the FIPS 140-3 pairwise
+  consistency test in both backends (`MLK_CONFIG_KEYGEN_PCT` /
+  `MLD_CONFIG_KEYGEN_PCT`): after generating a keypair it is exercised to catch
+  a faulty RNG or memory corruption at generation time. Upstream ships this
+  opt-in because it makes key generation noticeably more expensive, and it stays
+  opt-in here for the same reason. The selected setting is reported in the
+  build configuration banner.
+
+- **`require_encrypted:` for PKCS#8 loading.** Supplying a passphrase states an
+  expectation that the key at rest is encrypted, but an unencrypted
+  PrivateKeyInfo was previously accepted and the passphrase left unused. An
+  encrypted key file replaced with a plaintext one therefore loaded without
+  complaint.
+
+  `require_encrypted: true` enforces that the input is an
+  EncryptedPrivateKeyInfo (DER content, not PEM label — relabeling a plaintext
+  key as `ENCRYPTED PRIVATE KEY` does not satisfy the policy). Available on
+  `PKCS8.decode_der` / `decode_pem`, `Key.from_der` / `from_pem`, and
+  `secret_key_from_pkcs8_der` / `_pem` on both `KEM` and `Signature`.
+
+  Limits (documented so the flag is not over-read):
+
+  - default is `false`; other loaders (`from_bytes`, `pqc_container_*`) are
+    unchanged
+  - the flag checks **format**, not passphrase strength (empty passphrase and
+    low PBKDF iterations still count as encrypted)
+  - the value must be a real boolean (`true`/`false`); strings like `"false"`
+    raise `ArgumentError` instead of being treated as truthy
+
+## [0.6.6] - 2026-08-10
+
+### Changed
+
+- update native mlkem `v1.3.0` -> `v2.0.0` and mldsa `v1.0.0-beta2` -> `v2.0.0`
+
+  `mldsa-native` v2.0.0 is that project's first stable release; it is numbered
+  `2` only to align its API and configuration with `mlkem-native` v2. Upstream
+  now guarantees that non-experimental APIs and configuration options stay
+  stable until a `v3`.
+
+  No cryptographic output changed. All six `kat-sha256` values in the upstream
+  `META.yml` files are identical to the previously vendored versions, and the
+  vendored ML-KEM-768 keygen, ML-DSA-65 keygen and ML-DSA-65 siggen KAT vectors
+  reproduce byte-for-byte. This release is purely an API migration.
+
+### Breaking upstream changes handled
+
+- **`siglen` removed from the ML-DSA signing and verification APIs.** Upstream
+  signatures are always exactly `MLDSA_BYTES(level)`, so `signature`,
+  `signature_internal`, `verify`, `signature_extmu` and `verify_extmu` no longer
+  carry a length parameter. Fifteen declarations in
+  `ext/pqcrypto/pqcrypto_native_api.h` were updated accordingly.
+
+  The `pq_crypto` C API is deliberately *not* changed to match: `pq_sign`,
+  `pq_verify`, `pq_sign_mu` and `pq_verify_mu` keep their length parameters.
+  The adaptation happens at the vendor boundary instead.
+
+- **`pq_crypto` now owns the signing output length.** Because the backend no
+  longer reports it, every signing wrapper sets `*signature_len` itself from a
+  compile-time constant and clears it to `0` when the signing operation fails,
+  reproducing the pre-v2 behaviour. This affects `pq_sign`, `pq_mldsa44_sign`,
+  `pq_mldsa87_sign`, the level-agnostic deterministic helper
+  `pq_testing_mldsa_sign_from_seed_with`, and `pq_sign_mu`.
+
+  Argument-validation failures (`PQ_ERROR_BUFFER`) still leave `*signature_len`
+  untouched, exactly as before, since the pointer itself may be the invalid one.
+
+- **`pq_crypto` now validates signature length before verifying (security
+  relevant).** Prior to v2, `mldsa-native` rejected a wrongly sized signature
+  itself via `if (siglen != MLDSA_BYTES) return -1;`, and `pq_crypto` relied on
+  that. In v2 the verification entry points take a fixed-size array and read
+  `MLDSA_BYTES(level)` bytes unconditionally, so a short caller-supplied buffer
+  would be an out-of-bounds read. `pq_verify`, `pq_mldsa44_verify` and
+  `pq_mldsa87_verify` now enforce the exact length and return `PQ_ERROR_VERIFY`
+  otherwise; the Ruby bindings additionally reject the wrong length before
+  copying the buffer.
+
+  This was not exploitable in 0.6.5 or earlier: the previously vendored
+  `mldsa-native` performed the check. It is a latent contract dependency that a
+  naive port to v2 would have turned into a real memory-safety bug. Verified
+  with AddressSanitizer: removing this check alone reproduces a
+  `heap-buffer-overflow` read inside `pqcr_mldsa65_verify_internal`.
+
+  Observable Ruby behaviour is unchanged: a wrongly sized signature is a failed
+  verification (`false`), never an `ArgumentError`.
+
+- **ExternalMu callbacks adapted rather than re-typed.** Six new adapters,
+  `pq_mldsa{44,65,87}_{signature,verify}_extmu_compat`, sit between the
+  pre-v2 callback contract and the fixed-size v2 API. `pq_sign_mu` and
+  `pq_verify_mu` therefore keep their existing signatures and no consumer of the
+  C interface has to change.
+
+- **`MLK_CONFIG_NO_SUPERCOP` / `MLD_CONFIG_NO_SUPERCOP` removed upstream**
+  along with the SUPERCOP `crypto_*` aliases themselves. The define is no longer
+  passed by `extconf.rb`. Upstream has no guard against the stale macro, so it
+  would have been a silently dead `-D` rather than a build failure.
+
+- **Legacy `MLK_CONFIG_API_*` / `MLD_CONFIG_API_*` configuration removed
+  upstream.** The extension build already used the modern `*_CONFIG_*` macros;
+  only `test/native_api_conformance` still used the legacy path and has been
+  converted.
+
+Upstream breaking changes that do not affect this gem, checked explicitly: the
+SUPERCOP `crypto_*` and signed-message APIs (never used), the split of
+`*_ERR_FAIL` into specific error codes (all call sites compare against `0`), the
+`*_SYS_CAP_*` and `*_USE_NATIVE_FIPS202_*` renames (only relevant to custom
+backends), and the raised `MLD_CONFIG_MAX_SIGNING_ATTEMPTS` floor of 821, which
+this build does not set. `MLD_CONFIG_KEYGEN_PCT` / `MLK_CONFIG_KEYGEN_PCT`
+remain opt-in upstream and are not enabled here, so key generation gains no new
+failure mode or cost.
+
+### Testing
+
+- `test/native_api_conformance` reworked. It previously proved size agreement
+  via `_Static_assert` and, through the double declaration of upstream and
+  gem headers, prototype agreement. It could not detect a symbol that upstream
+  removed entirely, because it only ever compiled to an object file and both a
+  plain compile and a relocatable link tolerate unresolved symbols. The harness
+  now also builds the vendored objects with the same flags `extconf.rb` uses
+  (including which level owns the shared code) and diffs `nm -u` on the probe
+  object against the symbols the vendored build actually defines.
+
+- Conformance now covers `pqcr_mlkem_shake256` and `pqcr_mlkem_sha3_256`, the
+  extension's only dependency on a non-public part of `mlkem-native` (they back
+  the X-Wing key expansion and combiner). They were absent from `probes[]`
+  entirely, and because they are not declared in `mlkem_native.h` the
+  double-declaration check could not reach them either. The shared-level
+  conformance unit now includes the internal `src/fips202/fips202.h` so that
+  prototype drift in these two is caught as well.
+
+- Added `test/c_api`, direct tests for the `pq_crypto` C API, runnable under
+  AddressSanitizer via `PQCRYPTO_SANITIZE=address test/c_api/run.sh`. The Ruby
+  bindings pre-set `call.signature_len` before invoking the signing entry points
+  and read the same field back afterwards, so a wrapper that stopped writing
+  `*signature_len` would leave the entire Ruby suite green. That contract, and
+  the new signature-length validation, now have coverage that does not go
+  through Ruby.
+
+- `rake test` now runs the native API conformance and C API checks alongside the
+  Ruby suite.
+
+- The C API tests were themselves audited by mutation testing: each contract
+  this release changes was deliberately broken in turn and the suite had to
+  fail. That found three checks which passed against broken code and have been
+  rewritten:
+
+  - The ML-DSA-44 output-length check was phrased as "signing failed OR the
+    length is right" and reused the ML-DSA-65 secret key, so a
+    `pq_mldsa44_sign` that always returned an error satisfied it. ML-DSA-44 and
+    -87 now have their own key material and unconditional assertions.
+  - The ExternalMu failure check used a stub callback that cleared `*siglen`
+    itself, so it passed even when the real adapter had stopped doing so. It now
+    drives the genuine backend error path by exhausting the thread-local test
+    seed in `pq_randombytes.c`, which makes `randombytes()` fail. The same
+    technique gives `pq_sign` real coverage of its own error path.
+  - The verify adapters' length guards were unreachable through `pq_verify_mu`,
+    which validates the length first, so they were never exercised. They are now
+    called directly.
+
+  Two further gaps were closed: `pq_sign`'s recovery after a transient RNG
+  failure is now asserted, and a poisoned `*signature_len` that was set but
+  never checked is now checked.
+
 ## [0.6.5] - 2026-08-04
 
 ### Changed

data/README.md

@@ -88,9 +88,11 @@ bundle exec rake compile
 ```
 
 Upstream pins are recorded in `ext/pqcrypto/vendor/.vendored` and enforced by
-`bundle exec rake vendor:verify`. `mlkem-native` is pinned at `v1.3.0`, which
-upstream describes as the last release before a breaking `v2`; `release/v1.3` is
-the upstream support branch. `mldsa-native` is pinned at `v1.0.0-beta2`.
+`bundle exec rake vendor:verify`. Both `mlkem-native` and `mldsa-native` are
+pinned at `v2.0.0`. For `mldsa-native` this is the first stable release; it
+carries the major version `2` only so that its API and configuration line up
+with `mlkem-native` v2. Upstream guarantees that APIs and configuration options
+not marked experimental stay stable until a `v3`.
 
 The default build uses the portable native source path. Upstream native assembly
 can be tested explicitly with:
@@ -99,6 +101,13 @@ can be tested explicitly with:
 PQCRYPTO_NATIVE_ASM=1 bundle exec rake compile
 ```
 
+The FIPS 140-3 pairwise consistency test is available but off by default,
+because it makes key generation noticeably more expensive:
+
+```bash
+PQCRYPTO_KEYGEN_PCT=1 bundle exec rake compile
+```
+
 ## Security status
 
 `pq_crypto` is experimental and not audited. Treat it as a low-level primitive
@@ -123,8 +132,12 @@ PQCrypto::Signature.secret_key_from_seed(:ml_dsa_65, seed_32_bytes)
 
 PQCrypto::HybridKEM.generate(:ml_kem_768_x25519_xwing)
 PQCrypto::Key.from_pem(pem, passphrase: passphrase)
+PQCrypto::Key.from_pem(pem, passphrase: passphrase, require_encrypted: true)
+keypair.public_key.valid?  # ML-KEM structure check; ML-DSA public keys are length-only
+keypair.secret_key.valid?
 ```
 
+
 ## More examples
 
 Detailed usage examples live in [`GET_STARTED.md`](GET_STARTED.md):

data/SECURITY.md

@@ -127,6 +127,52 @@ into `mldsa-native` `signature_internal`; for an empty context this prefix is
 Outside of test-only deterministic calls, production randomness delegates
 directly to OpenSSL `RAND_bytes`.
 
+## Key import validation (0.6.7+)
+
+ML-KEM public/secret keys and ML-DSA secret keys are structure-checked when
+the corresponding Ruby key objects are constructed:
+
+| Object | Check | Source |
+| --- | --- | --- |
+| `KEM::PublicKey` | FIPS 203 §7.2 modulus check | `check_pk` |
+| `KEM::SecretKey` | FIPS 203 §7.3 `H(pk)` check | `check_sk` |
+| `Signature::SecretKey` | norms / `t0` / `tr` consistency | `pk_from_sk` |
+| `Signature::PublicKey` | length only | — |
+| X-Wing public key | ML-KEM-768 half only | `check_pk` |
+| X-Wing secret key | none (32-byte seed) | — |
+
+These are **import diagnostics**. Encapsulation, decapsulation, signing, and
+verification still apply their own backend checks. A true `#valid?` result
+does not prove full cryptographic integrity of every field (for example an
+ML-KEM secret key with a corrupted IND-CPA `dk` but intact `H(pk)` still
+passes §7.3).
+
+The checks run on import. Keys produced by this process's own key generation
+are valid by construction and are not re-checked, because the ML-DSA check
+re-derives the public key and would roughly double the cost of every keypair.
+
+The ML-DSA check (`pk_from_sk`) is documented upstream as leaking whether the
+secret key is valid, through both its return value and its timing.
+
+`require_encrypted:` applies only to the PKCS#8 branch. `PQCrypto::Key.from_der`
+and `.from_pem` also accept SPKI public keys, and for those inputs the flag has
+no effect and is silently ignored.
+
+Public-key internal buffers are frozen after construction. Secret-key buffers
+remain mutable so `#wipe!` can zero them.
+
+### `require_encrypted:`
+
+`require_encrypted: true` on PKCS#8 loaders rejects plaintext PrivateKeyInfo
+and requires EncryptedPrivateKeyInfo (classified from DER, not PEM labels).
+It does **not**:
+
+- apply to `from_bytes` / `pqc_container_*` loaders
+- enforce passphrase quality or PBKDF iteration count
+- default on (default remains `false`)
+
+The flag must be a boolean; non-boolean values raise `ArgumentError`.
+
 ## Memory wiping
 
 `PQCrypto.secure_wipe` clears mutable Ruby strings in place. Ruby key objects

data/ext/pqcrypto/extconf.rb

@@ -84,6 +84,8 @@ def env_bool(name, default)
   end
 end
 
+KEYGEN_PCT = env_bool("PQCRYPTO_KEYGEN_PCT", false)
+
 NATIVE_ASM = env_bool("PQCRYPTO_NATIVE_ASM", native_asm_supported_by_default?)
 NATIVE_ARITH = env_bool("PQCRYPTO_NATIVE_ARITH", NATIVE_ASM)
 NATIVE_FIPS202 = env_bool("PQCRYPTO_NATIVE_FIPS202", NATIVE_ASM)
@@ -524,8 +526,12 @@ def native_flags(kind, level, shared:)
   flags << "-D#{prefix}_CONFIG_MULTILEVEL_BUILD"
   flags << "-D#{prefix}_CONFIG_PARAMETER_SET=#{level}"
   flags << "-D#{prefix}_CONFIG_NAMESPACE_PREFIX=#{ns}"
-  flags << "-D#{prefix}_CONFIG_NO_SUPERCOP"
+  # NOTE: MLK/MLD_CONFIG_NO_SUPERCOP was removed in mlkem-native v2.0.0 and
+  # mldsa-native v2.0.0 along with the SUPERCOP crypto_* aliases themselves.
+  # Upstream has no guard against the stale define, so passing it would be a
+  # silently dead -D rather than a build error. Do not reintroduce it.
   flags << (shared ? "-D#{prefix}_CONFIG_MULTILEVEL_WITH_SHARED" : "-D#{prefix}_CONFIG_MULTILEVEL_NO_SHARED")
+  flags << "-D#{prefix}_CONFIG_KEYGEN_PCT" if KEYGEN_PCT
   flags << "-D#{prefix}_CONFIG_USE_NATIVE_BACKEND_ARITH" if NATIVE_ARITH
   flags << "-D#{prefix}_CONFIG_USE_NATIVE_BACKEND_FIPS202" if NATIVE_FIPS202
   flags.join(" ")
@@ -612,6 +618,7 @@ puts "Vendor ASM arch flags: #{VENDOR_ASM_ARCH_FLAGS.empty? ? '(none)' : VENDOR_
 if x86_64_host? && (NATIVE_ARITH || NATIVE_FIPS202)
   puts "x86_64 native backend: AVX2 build flags enabled"
 end
+puts "Keygen PCT (FIPS 140-3): #{KEYGEN_PCT ? 'enabled' : 'disabled'}"
 puts "PQClean fallback: removed"
 puts "Output: pqcrypto/pqcrypto_secure"
 puts "===================================="

data/ext/pqcrypto/pq_externalmu.c

@@ -66,6 +66,41 @@ int pq_mldsa_compute_tr_from_public_key(uint8_t *tr_out, const uint8_t *public_k
     return pq_shake256(tr_out, PQ_MLDSA_TRBYTES, public_key, public_key_len);
 }
 
+#define PQ_DEFINE_SIGNATURE_EXTMU_COMPAT(level, native, sig_bytes)                                \
+    int pq_mldsa##level##_signature_extmu_compat(uint8_t *sig, size_t *siglen, const uint8_t *mu, \
+                                                 const uint8_t *sk) {                             \
+        if (sig == NULL || siglen == NULL || mu == NULL || sk == NULL) {                          \
+            return -1;                                                                            \
+        }                                                                                         \
+        if (native##_signature_extmu(sig, mu, sk) != 0) {                                         \
+            *siglen = 0;                                                                          \
+            return -1;                                                                            \
+        }                                                                                         \
+        *siglen = (size_t)(sig_bytes);                                                            \
+        return 0;                                                                                 \
+    }
+
+PQ_DEFINE_SIGNATURE_EXTMU_COMPAT(44, pqcr_mldsa44, MLDSA44_BYTES)
+PQ_DEFINE_SIGNATURE_EXTMU_COMPAT(65, pqcr_mldsa65, MLDSA65_BYTES)
+PQ_DEFINE_SIGNATURE_EXTMU_COMPAT(87, pqcr_mldsa87, MLDSA87_BYTES)
+
+#undef PQ_DEFINE_SIGNATURE_EXTMU_COMPAT
+
+#define PQ_DEFINE_VERIFY_EXTMU_COMPAT(level, native, sig_bytes)                         \
+    int pq_mldsa##level##_verify_extmu_compat(const uint8_t *sig, size_t siglen,        \
+                                              const uint8_t *mu, const uint8_t *pk) {   \
+        if (sig == NULL || mu == NULL || pk == NULL || siglen != (size_t)(sig_bytes)) { \
+            return -1;                                                                  \
+        }                                                                               \
+        return native##_verify_extmu(sig, mu, pk);                                      \
+    }
+
+PQ_DEFINE_VERIFY_EXTMU_COMPAT(44, pqcr_mldsa44, MLDSA44_BYTES)
+PQ_DEFINE_VERIFY_EXTMU_COMPAT(65, pqcr_mldsa65, MLDSA65_BYTES)
+PQ_DEFINE_VERIFY_EXTMU_COMPAT(87, pqcr_mldsa87, MLDSA87_BYTES)
+
+#undef PQ_DEFINE_VERIFY_EXTMU_COMPAT
+
 int pq_sign_mu(uint8_t *signature, size_t *signature_len, const uint8_t *mu,
                const uint8_t *secret_key,
                int (*signature_extmu)(uint8_t *, size_t *, const uint8_t *, const uint8_t *)) {

data/ext/pqcrypto/pqcrypto_native_api.h

@@ -15,49 +15,62 @@
  *   MLD_CONFIG_NAMESPACE_PREFIX=pqcr_mldsa
  * and MLK/MLD_CONFIG_MULTILEVEL_BUILD enabled. Do not add PQClean aliases here:
  * we want one backend only so build/runtime failures point at the new stack.
+ *
+ * mldsa-native v2.0.0 removed the `siglen` in/out parameter from the signing
+ * and verification APIs: signatures are always exactly MLDSA_BYTES(level) and
+ * the buffer size is part of the API contract rather than a runtime value.
+ *
+ * Two consequences for every caller in this extension:
+ *   1. Signing no longer reports the produced length. Each pq_crypto wrapper
+ *      sets its own *signature_len from the compile-time constant, and clears
+ *      it to 0 on failure, preserving the pre-v2 pq_crypto contract.
+ *   2. Verification no longer rejects a wrongly sized signature. The caller
+ *      MUST check the length itself before handing the buffer to
+ *      pqcr_mldsa*_verify / pqcr_mldsa*_verify_extmu, which read
+ *      MLDSA_BYTES(level) bytes unconditionally.
  */
 
-#define MLKEM512_SECRETKEYBYTES     1632
-#define MLKEM512_PUBLICKEYBYTES     800
-#define MLKEM512_CIPHERTEXTBYTES    768
-#define MLKEM512_SHAREDSECRETBYTES  32
+#define MLKEM512_SECRETKEYBYTES    1632
+#define MLKEM512_PUBLICKEYBYTES    800
+#define MLKEM512_CIPHERTEXTBYTES   768
+#define MLKEM512_SHAREDSECRETBYTES 32
 
-#define MLKEM768_SECRETKEYBYTES     2400
-#define MLKEM768_PUBLICKEYBYTES     1184
-#define MLKEM768_CIPHERTEXTBYTES    1088
-#define MLKEM768_SHAREDSECRETBYTES  32
+#define MLKEM768_SECRETKEYBYTES    2400
+#define MLKEM768_PUBLICKEYBYTES    1184
+#define MLKEM768_CIPHERTEXTBYTES   1088
+#define MLKEM768_SHAREDSECRETBYTES 32
 
 #define MLKEM1024_SECRETKEYBYTES    3168
 #define MLKEM1024_PUBLICKEYBYTES    1568
 #define MLKEM1024_CIPHERTEXTBYTES   1568
 #define MLKEM1024_SHAREDSECRETBYTES 32
 
-#define MLKEM_PUBLICKEYBYTES        MLKEM768_PUBLICKEYBYTES
-#define MLKEM_SECRETKEYBYTES        MLKEM768_SECRETKEYBYTES
-#define MLKEM_CIPHERTEXTBYTES       MLKEM768_CIPHERTEXTBYTES
-#define MLKEM_SHAREDSECRETBYTES     MLKEM768_SHAREDSECRETBYTES
-
-#define MLDSA44_SECRETKEYBYTES      2560
-#define MLDSA44_PUBLICKEYBYTES      1312
-#define MLDSA44_BYTES               2420
-
-#define MLDSA65_SECRETKEYBYTES      4032
-#define MLDSA65_PUBLICKEYBYTES      1952
-#define MLDSA65_BYTES               3309
-
-#define MLDSA87_SECRETKEYBYTES      4896
-#define MLDSA87_PUBLICKEYBYTES      2592
-#define MLDSA87_BYTES               4627
-
-#define MLDSA_PUBLICKEYBYTES        MLDSA65_PUBLICKEYBYTES
-#define MLDSA_SECRETKEYBYTES        MLDSA65_SECRETKEYBYTES
-#define MLDSA_BYTES                 MLDSA65_BYTES
-#define MLDSA_SEEDBYTES             32
-#define MLDSA_RNDBYTES              32
-#define MLDSA_TRBYTES               64
-#define MLDSA_CRHBYTES              64
+#define MLKEM_PUBLICKEYBYTES    MLKEM768_PUBLICKEYBYTES
+#define MLKEM_SECRETKEYBYTES    MLKEM768_SECRETKEYBYTES
+#define MLKEM_CIPHERTEXTBYTES   MLKEM768_CIPHERTEXTBYTES
+#define MLKEM_SHAREDSECRETBYTES MLKEM768_SHAREDSECRETBYTES
+
+#define MLDSA44_SECRETKEYBYTES 2560
+#define MLDSA44_PUBLICKEYBYTES 1312
+#define MLDSA44_BYTES          2420
+
+#define MLDSA65_SECRETKEYBYTES 4032
+#define MLDSA65_PUBLICKEYBYTES 1952
+#define MLDSA65_BYTES          3309
+
+#define MLDSA87_SECRETKEYBYTES 4896
+#define MLDSA87_PUBLICKEYBYTES 2592
+#define MLDSA87_BYTES          4627
+
+#define MLDSA_PUBLICKEYBYTES              MLDSA65_PUBLICKEYBYTES
+#define MLDSA_SECRETKEYBYTES              MLDSA65_SECRETKEYBYTES
+#define MLDSA_BYTES                       MLDSA65_BYTES
+#define MLDSA_SEEDBYTES                   32
+#define MLDSA_RNDBYTES                    32
+#define MLDSA_TRBYTES                     64
+#define MLDSA_CRHBYTES                    64
 #define MLDSA_DOMAIN_SEPARATION_MAX_BYTES (2 + 255 + 11 + 64)
-#define MLDSA_PREHASH_NONE          0
+#define MLDSA_PREHASH_NONE                0
 
 /* mlkem-native symbols: namespace prefix pqcr_mlkem + level suffix. */
 int pqcr_mlkem512_keypair(uint8_t *pk, uint8_t *sk);
@@ -65,18 +78,24 @@ int pqcr_mlkem512_keypair_derand(uint8_t *pk, uint8_t *sk, const uint8_t *coins)
 int pqcr_mlkem512_enc(uint8_t *ct, uint8_t *ss, const uint8_t *pk);
 int pqcr_mlkem512_enc_derand(uint8_t *ct, uint8_t *ss, const uint8_t *pk, const uint8_t *coins);
 int pqcr_mlkem512_dec(uint8_t *ss, const uint8_t *ct, const uint8_t *sk);
+int pqcr_mlkem512_check_pk(const uint8_t *pk);
+int pqcr_mlkem512_check_sk(const uint8_t *sk);
 
 int pqcr_mlkem768_keypair(uint8_t *pk, uint8_t *sk);
 int pqcr_mlkem768_keypair_derand(uint8_t *pk, uint8_t *sk, const uint8_t *coins);
 int pqcr_mlkem768_enc(uint8_t *ct, uint8_t *ss, const uint8_t *pk);
 int pqcr_mlkem768_enc_derand(uint8_t *ct, uint8_t *ss, const uint8_t *pk, const uint8_t *coins);
 int pqcr_mlkem768_dec(uint8_t *ss, const uint8_t *ct, const uint8_t *sk);
+int pqcr_mlkem768_check_pk(const uint8_t *pk);
+int pqcr_mlkem768_check_sk(const uint8_t *sk);
 
 int pqcr_mlkem1024_keypair(uint8_t *pk, uint8_t *sk);
 int pqcr_mlkem1024_keypair_derand(uint8_t *pk, uint8_t *sk, const uint8_t *coins);
 int pqcr_mlkem1024_enc(uint8_t *ct, uint8_t *ss, const uint8_t *pk);
 int pqcr_mlkem1024_enc_derand(uint8_t *ct, uint8_t *ss, const uint8_t *pk, const uint8_t *coins);
 int pqcr_mlkem1024_dec(uint8_t *ss, const uint8_t *ct, const uint8_t *sk);
+int pqcr_mlkem1024_check_pk(const uint8_t *pk);
+int pqcr_mlkem1024_check_sk(const uint8_t *sk);
 
 void pqcr_mlkem_shake256(uint8_t *output, size_t outlen, const uint8_t *input, size_t inlen);
 void pqcr_mlkem_sha3_256(uint8_t *output, const uint8_t *input, size_t inlen);
@@ -84,58 +103,55 @@ void pqcr_mlkem_sha3_256(uint8_t *output, const uint8_t *input, size_t inlen);
 /* mldsa-native symbols: namespace prefix pqcr_mldsa + level suffix. */
 int pqcr_mldsa44_keypair(uint8_t *pk, uint8_t *sk);
 int pqcr_mldsa44_keypair_internal(uint8_t *pk, uint8_t *sk, const uint8_t seed[MLDSA_SEEDBYTES]);
-int pqcr_mldsa44_signature(uint8_t *sig, size_t *siglen, const uint8_t *m, size_t mlen,
-                           const uint8_t *ctx, size_t ctxlen, const uint8_t *sk);
-int pqcr_mldsa44_signature_internal(uint8_t *sig, size_t *siglen, const uint8_t *m,
-                                    size_t mlen, const uint8_t *pre, size_t prelen,
-                                    const uint8_t rnd[MLDSA_RNDBYTES], const uint8_t *sk,
-                                    int externalmu);
-int pqcr_mldsa44_verify(const uint8_t *sig, size_t siglen, const uint8_t *m, size_t mlen,
-                        const uint8_t *ctx, size_t ctxlen, const uint8_t *pk);
-size_t pqcr_mldsa44_prepare_domain_separation_prefix(
-    uint8_t prefix[MLDSA_DOMAIN_SEPARATION_MAX_BYTES], const uint8_t *ph, size_t phlen,
-    const uint8_t *ctx, size_t ctxlen, int hashalg);
-int pqcr_mldsa44_signature_extmu(uint8_t *sig, size_t *siglen, const uint8_t mu[MLDSA_CRHBYTES],
-                                 const uint8_t *sk);
-int pqcr_mldsa44_verify_extmu(const uint8_t *sig, size_t siglen, const uint8_t mu[MLDSA_CRHBYTES],
+int pqcr_mldsa44_signature(uint8_t *sig, const uint8_t *m, size_t mlen, const uint8_t *ctx,
+                           size_t ctxlen, const uint8_t *sk);
+int pqcr_mldsa44_signature_internal(uint8_t *sig, const uint8_t *m, size_t mlen, const uint8_t *pre,
+                                    size_t prelen, const uint8_t rnd[MLDSA_RNDBYTES],
+                                    const uint8_t *sk, int externalmu);
+int pqcr_mldsa44_verify(const uint8_t *sig, const uint8_t *m, size_t mlen, const uint8_t *ctx,
+                        size_t ctxlen, const uint8_t *pk);
+size_t
+pqcr_mldsa44_prepare_domain_separation_prefix(uint8_t prefix[MLDSA_DOMAIN_SEPARATION_MAX_BYTES],
+                                              const uint8_t *ph, size_t phlen, const uint8_t *ctx,
+                                              size_t ctxlen, int hashalg);
+int pqcr_mldsa44_signature_extmu(uint8_t *sig, const uint8_t mu[MLDSA_CRHBYTES], const uint8_t *sk);
+int pqcr_mldsa44_verify_extmu(const uint8_t *sig, const uint8_t mu[MLDSA_CRHBYTES],
                               const uint8_t *pk);
 int pqcr_mldsa44_pk_from_sk(uint8_t *pk, const uint8_t *sk);
 
 int pqcr_mldsa65_keypair(uint8_t *pk, uint8_t *sk);
 int pqcr_mldsa65_keypair_internal(uint8_t *pk, uint8_t *sk, const uint8_t seed[MLDSA_SEEDBYTES]);
-int pqcr_mldsa65_signature(uint8_t *sig, size_t *siglen, const uint8_t *m, size_t mlen,
-                           const uint8_t *ctx, size_t ctxlen, const uint8_t *sk);
-int pqcr_mldsa65_signature_internal(uint8_t *sig, size_t *siglen, const uint8_t *m,
-                                    size_t mlen, const uint8_t *pre, size_t prelen,
-                                    const uint8_t rnd[MLDSA_RNDBYTES], const uint8_t *sk,
-                                    int externalmu);
-int pqcr_mldsa65_verify(const uint8_t *sig, size_t siglen, const uint8_t *m, size_t mlen,
-                        const uint8_t *ctx, size_t ctxlen, const uint8_t *pk);
-size_t pqcr_mldsa65_prepare_domain_separation_prefix(
-    uint8_t prefix[MLDSA_DOMAIN_SEPARATION_MAX_BYTES], const uint8_t *ph, size_t phlen,
-    const uint8_t *ctx, size_t ctxlen, int hashalg);
-int pqcr_mldsa65_signature_extmu(uint8_t *sig, size_t *siglen, const uint8_t mu[MLDSA_CRHBYTES],
-                                 const uint8_t *sk);
-int pqcr_mldsa65_verify_extmu(const uint8_t *sig, size_t siglen, const uint8_t mu[MLDSA_CRHBYTES],
+int pqcr_mldsa65_signature(uint8_t *sig, const uint8_t *m, size_t mlen, const uint8_t *ctx,
+                           size_t ctxlen, const uint8_t *sk);
+int pqcr_mldsa65_signature_internal(uint8_t *sig, const uint8_t *m, size_t mlen, const uint8_t *pre,
+                                    size_t prelen, const uint8_t rnd[MLDSA_RNDBYTES],
+                                    const uint8_t *sk, int externalmu);
+int pqcr_mldsa65_verify(const uint8_t *sig, const uint8_t *m, size_t mlen, const uint8_t *ctx,
+                        size_t ctxlen, const uint8_t *pk);
+size_t
+pqcr_mldsa65_prepare_domain_separation_prefix(uint8_t prefix[MLDSA_DOMAIN_SEPARATION_MAX_BYTES],
+                                              const uint8_t *ph, size_t phlen, const uint8_t *ctx,
+                                              size_t ctxlen, int hashalg);
+int pqcr_mldsa65_signature_extmu(uint8_t *sig, const uint8_t mu[MLDSA_CRHBYTES], const uint8_t *sk);
+int pqcr_mldsa65_verify_extmu(const uint8_t *sig, const uint8_t mu[MLDSA_CRHBYTES],
                               const uint8_t *pk);
 int pqcr_mldsa65_pk_from_sk(uint8_t *pk, const uint8_t *sk);
 
 int pqcr_mldsa87_keypair(uint8_t *pk, uint8_t *sk);
 int pqcr_mldsa87_keypair_internal(uint8_t *pk, uint8_t *sk, const uint8_t seed[MLDSA_SEEDBYTES]);
-int pqcr_mldsa87_signature(uint8_t *sig, size_t *siglen, const uint8_t *m, size_t mlen,
-                           const uint8_t *ctx, size_t ctxlen, const uint8_t *sk);
-int pqcr_mldsa87_signature_internal(uint8_t *sig, size_t *siglen, const uint8_t *m,
-                                    size_t mlen, const uint8_t *pre, size_t prelen,
-                                    const uint8_t rnd[MLDSA_RNDBYTES], const uint8_t *sk,
-                                    int externalmu);
-int pqcr_mldsa87_verify(const uint8_t *sig, size_t siglen, const uint8_t *m, size_t mlen,
-                        const uint8_t *ctx, size_t ctxlen, const uint8_t *pk);
-size_t pqcr_mldsa87_prepare_domain_separation_prefix(
-    uint8_t prefix[MLDSA_DOMAIN_SEPARATION_MAX_BYTES], const uint8_t *ph, size_t phlen,
-    const uint8_t *ctx, size_t ctxlen, int hashalg);
-int pqcr_mldsa87_signature_extmu(uint8_t *sig, size_t *siglen, const uint8_t mu[MLDSA_CRHBYTES],
-                                 const uint8_t *sk);
-int pqcr_mldsa87_verify_extmu(const uint8_t *sig, size_t siglen, const uint8_t mu[MLDSA_CRHBYTES],
+int pqcr_mldsa87_signature(uint8_t *sig, const uint8_t *m, size_t mlen, const uint8_t *ctx,
+                           size_t ctxlen, const uint8_t *sk);
+int pqcr_mldsa87_signature_internal(uint8_t *sig, const uint8_t *m, size_t mlen, const uint8_t *pre,
+                                    size_t prelen, const uint8_t rnd[MLDSA_RNDBYTES],
+                                    const uint8_t *sk, int externalmu);
+int pqcr_mldsa87_verify(const uint8_t *sig, const uint8_t *m, size_t mlen, const uint8_t *ctx,
+                        size_t ctxlen, const uint8_t *pk);
+size_t
+pqcr_mldsa87_prepare_domain_separation_prefix(uint8_t prefix[MLDSA_DOMAIN_SEPARATION_MAX_BYTES],
+                                              const uint8_t *ph, size_t phlen, const uint8_t *ctx,
+                                              size_t ctxlen, int hashalg);
+int pqcr_mldsa87_signature_extmu(uint8_t *sig, const uint8_t mu[MLDSA_CRHBYTES], const uint8_t *sk);
+int pqcr_mldsa87_verify_extmu(const uint8_t *sig, const uint8_t mu[MLDSA_CRHBYTES],
                               const uint8_t *pk);
 int pqcr_mldsa87_pk_from_sk(uint8_t *pk, const uint8_t *sk);