pq_crypto 0.6.6 → 0.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 273b83c96db2314540118b933a9f70a22c954e59a6fb38377f7c6cd1f337d698
-  data.tar.gz: 0a6f4b88a3aefde58049f41f582548aa10f2aa939e98a8b60791ff23c8a5be0e
+  metadata.gz: cf8d3b17b9579ef551ef337aab16a9eb356846a36ff492577e2d728ec0e285e2
+  data.tar.gz: 26c3c3646d066617e37cb2cb1219e7ee5ca640488c84b480b6259461999b48e5
 SHA512:
-  metadata.gz: f4905490a34b75ae7548a896cbb379b135c7615dfba9dca564add76892fb6074a6e0a12220ca3158417ea3264c2dcb2dc432b0a49fa91f8429eaebeef966d895
-  data.tar.gz: 854941b5a331956cba2aa91ef1777148f9a93713eec6ce746fe01475b126b69f409ad0dbcf631a1db5c7c09d127d55053d59585850bcf06a8047f8b2ae14adec
+  metadata.gz: bd58150566a566af1c3083ef2c72538acafb6b15c5ebe954d0d7af35f96cdf41a5f1fe17c8d3c956e29b3c51bd89b29ec24245749efbca82389b1d2dc3c91ede
+  data.tar.gz: 5d974df3a99f9284da5c5cdfff25ba1808dc083063c12f97db6b803a34aa15687a0cda9565c8617edd95015c8d23139181d56d69d2483a3ac17b2239bec3cba3

data/CHANGELOG.md

@@ -1,5 +1,104 @@
 # 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

data/README.md

@@ -101,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
@@ -125,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)
@@ -529,6 +531,7 @@ def native_flags(kind, level, shared:)
   # 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(" ")
@@ -615,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/pqcrypto_native_api.h

@@ -78,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);

data/ext/pqcrypto/pqcrypto_ruby_secure.c

@@ -718,6 +718,12 @@ __attribute__((noreturn)) static void pq_raise_general_error(int err) {
     case PQ_ERROR_OPENSSL:
         rb_raise(ePQCryptoError, "OpenSSL error");
         break;
+    case PQ_ERROR_INVALID_PUBLIC_KEY:
+        rb_raise(ePQCryptoError, "Invalid public key");
+        break;
+    case PQ_ERROR_INVALID_SECRET_KEY:
+        rb_raise(ePQCryptoError, "Invalid secret key");
+        break;
     default:
         rb_raise(ePQCryptoError, "Unknown error: %d", err);
         break;
@@ -765,6 +771,28 @@ static VALUE pq_run_kem_keypair_from_seed(void *(*nogvl)(void *), VALUE seed, si
     X(ml_kem_1024, MLKEM1024_PUBLICKEYBYTES, MLKEM1024_SECRETKEYBYTES, MLKEM1024_CIPHERTEXTBYTES, \
       MLKEM1024_SHAREDSECRETBYTES)
 
+static VALUE pq_run_key_check(int (*check)(const uint8_t *), VALUE key, size_t expected_len) {
+    uint8_t *buffer;
+    size_t copied_len = 0;
+    int result;
+
+    StringValue(key);
+    if ((size_t)RSTRING_LEN(key) != expected_len) {
+        return Qfalse;
+    }
+
+    buffer = pq_copy_ruby_string(key, &copied_len);
+    result = check(buffer);
+    pq_secure_wipe(buffer, copied_len);
+    free(buffer);
+
+    if (result == PQ_ERROR_NOMEM) {
+        rb_raise(rb_eNoMemError, "Memory allocation failed");
+    }
+
+    return result == PQ_SUCCESS ? Qtrue : Qfalse;
+}
+
 #define PQ_DEFINE_RUBY_KEM(rb_name, pk_bytes, sk_bytes, ct_bytes, ss_bytes)                   \
     static VALUE pqcrypto_##rb_name##_keypair(VALUE self) {                                   \
         (void)self;                                                                           \
@@ -787,6 +815,41 @@ static VALUE pq_run_kem_keypair_from_seed(void *(*nogvl)(void *), VALUE seed, si
                                       secret_key, sk_bytes, ss_bytes);                        \
     }
 
+#define PQ_DEFINE_RUBY_KEM_CHECK(rb_name, c_name)                               \
+    static VALUE pqcrypto_##rb_name##_check_public_key(VALUE self, VALUE key) { \
+        (void)self;                                                             \
+        return pq_run_key_check(pq_##c_name##_check_public_key, key,            \
+                                (size_t)c_name##_PUBLICKEYBYTES_VALUE);         \
+    }                                                                           \
+    static VALUE pqcrypto_##rb_name##_check_secret_key(VALUE self, VALUE key) { \
+        (void)self;                                                             \
+        return pq_run_key_check(pq_##c_name##_check_secret_key, key,            \
+                                (size_t)c_name##_SECRETKEYBYTES_VALUE);         \
+    }
+
+#define mlkem_PUBLICKEYBYTES_VALUE     PQ_MLKEM_PUBLICKEYBYTES
+#define mlkem_SECRETKEYBYTES_VALUE     PQ_MLKEM_SECRETKEYBYTES
+#define mlkem512_PUBLICKEYBYTES_VALUE  MLKEM512_PUBLICKEYBYTES
+#define mlkem512_SECRETKEYBYTES_VALUE  MLKEM512_SECRETKEYBYTES
+#define mlkem1024_PUBLICKEYBYTES_VALUE MLKEM1024_PUBLICKEYBYTES
+#define mlkem1024_SECRETKEYBYTES_VALUE MLKEM1024_SECRETKEYBYTES
+
+PQ_KEM_KEYPAIR_NOGVL_VARIANTS(PQ_DEFINE_RUBY_KEM_CHECK)
+
+#undef PQ_DEFINE_RUBY_KEM_CHECK
+
+#define PQ_DEFINE_RUBY_MLDSA_CHECK_SK(rb_name, c_name, sk_bytes)                          \
+    static VALUE pqcrypto_##rb_name##_check_secret_key(VALUE self, VALUE key) {           \
+        (void)self;                                                                       \
+        return pq_run_key_check(pq_##c_name##_check_secret_key, key, (size_t)(sk_bytes)); \
+    }
+
+PQ_DEFINE_RUBY_MLDSA_CHECK_SK(ml_dsa, mldsa, MLDSA65_SECRETKEYBYTES)
+PQ_DEFINE_RUBY_MLDSA_CHECK_SK(ml_dsa_44, mldsa44, MLDSA44_SECRETKEYBYTES)
+PQ_DEFINE_RUBY_MLDSA_CHECK_SK(ml_dsa_87, mldsa87, MLDSA87_SECRETKEYBYTES)
+
+#undef PQ_DEFINE_RUBY_MLDSA_CHECK_SK
+
 PQ_RUBY_KEM_VARIANTS(PQ_DEFINE_RUBY_KEM)
 
 #undef PQ_DEFINE_RUBY_KEM
@@ -1999,6 +2062,24 @@ void Init_pqcrypto_secure(void) {
                               pqcrypto_ml_kem_1024_encapsulate, 1);
     rb_define_module_function(mPQCrypto, "ml_kem_1024_decapsulate",
                               pqcrypto_ml_kem_1024_decapsulate, 2);
+    rb_define_module_function(mPQCrypto, "ml_kem_check_public_key",
+                              pqcrypto_ml_kem_check_public_key, 1);
+    rb_define_module_function(mPQCrypto, "ml_kem_check_secret_key",
+                              pqcrypto_ml_kem_check_secret_key, 1);
+    rb_define_module_function(mPQCrypto, "ml_kem_512_check_public_key",
+                              pqcrypto_ml_kem_512_check_public_key, 1);
+    rb_define_module_function(mPQCrypto, "ml_kem_512_check_secret_key",
+                              pqcrypto_ml_kem_512_check_secret_key, 1);
+    rb_define_module_function(mPQCrypto, "ml_kem_1024_check_public_key",
+                              pqcrypto_ml_kem_1024_check_public_key, 1);
+    rb_define_module_function(mPQCrypto, "ml_kem_1024_check_secret_key",
+                              pqcrypto_ml_kem_1024_check_secret_key, 1);
+    rb_define_module_function(mPQCrypto, "ml_dsa_check_secret_key",
+                              pqcrypto_ml_dsa_check_secret_key, 1);
+    rb_define_module_function(mPQCrypto, "ml_dsa_44_check_secret_key",
+                              pqcrypto_ml_dsa_44_check_secret_key, 1);
+    rb_define_module_function(mPQCrypto, "ml_dsa_87_check_secret_key",
+                              pqcrypto_ml_dsa_87_check_secret_key, 1);
     rb_define_module_function(mPQCrypto, "hybrid_kem_keypair", pqcrypto_hybrid_kem_keypair, 0);
     rb_define_module_function(mPQCrypto, "hybrid_kem_encapsulate", pqcrypto_hybrid_kem_encapsulate,
                               1);

data/ext/pqcrypto/pqcrypto_secure.c

@@ -265,12 +265,64 @@ cleanup:
             return PQ_ERROR_BUFFER;                                                          \
         }                                                                                    \
         return native##_dec(ss, ct, sk) == 0 ? PQ_SUCCESS : PQ_ERROR_DECAPSULATE;            \
+    }                                                                                        \
+    int pq_##prefix##_check_public_key(const uint8_t *pk) {                                  \
+        int rc;                                                                              \
+        if (!pk) {                                                                           \
+            return PQ_ERROR_BUFFER;                                                          \
+        }                                                                                    \
+        rc = native##_check_pk(pk);                                                          \
+        if (rc == 0) {                                                                       \
+            return PQ_SUCCESS;                                                               \
+        }                                                                                    \
+        if (rc == -2) {                                                                      \
+            return PQ_ERROR_NOMEM;                                                           \
+        }                                                                                    \
+        return PQ_ERROR_INVALID_PUBLIC_KEY;                                                  \
+    }                                                                                        \
+    int pq_##prefix##_check_secret_key(const uint8_t *sk) {                                  \
+        int rc;                                                                              \
+        if (!sk) {                                                                           \
+            return PQ_ERROR_BUFFER;                                                          \
+        }                                                                                    \
+        rc = native##_check_sk(sk);                                                          \
+        if (rc == 0) {                                                                       \
+            return PQ_SUCCESS;                                                               \
+        }                                                                                    \
+        if (rc == -2) {                                                                      \
+            return PQ_ERROR_NOMEM;                                                           \
+        }                                                                                    \
+        return PQ_ERROR_INVALID_SECRET_KEY;                                                  \
     }
 
 PQ_MLKEM_VARIANTS(PQ_DEFINE_MLKEM_SHIMS)
 
 #undef PQ_DEFINE_MLKEM_SHIMS
 
+#define PQ_DEFINE_MLDSA_CHECK_SK(prefix, native, pk_bytes)  \
+    int pq_##prefix##_check_secret_key(const uint8_t *sk) { \
+        uint8_t pk[(pk_bytes)];                             \
+        int rc;                                             \
+        if (!sk) {                                          \
+            return PQ_ERROR_BUFFER;                         \
+        }                                                   \
+        rc = native##_pk_from_sk(pk, sk);                   \
+        pq_secure_wipe(pk, sizeof(pk));                     \
+        if (rc == 0) {                                      \
+            return PQ_SUCCESS;                              \
+        }                                                   \
+        if (rc == -2) {                                     \
+            return PQ_ERROR_NOMEM;                          \
+        }                                                   \
+        return PQ_ERROR_INVALID_SECRET_KEY;                 \
+    }
+
+PQ_DEFINE_MLDSA_CHECK_SK(mldsa, pqcr_mldsa65, MLDSA65_PUBLICKEYBYTES)
+PQ_DEFINE_MLDSA_CHECK_SK(mldsa44, pqcr_mldsa44, MLDSA44_PUBLICKEYBYTES)
+PQ_DEFINE_MLDSA_CHECK_SK(mldsa87, pqcr_mldsa87, MLDSA87_PUBLICKEYBYTES)
+
+#undef PQ_DEFINE_MLDSA_CHECK_SK
+
 static int pq_testing_mlkem_keypair_from_seed_with(uint8_t *public_key, uint8_t *secret_key,
                                                    const uint8_t *seed, size_t seed_len,
                                                    int (*keypair_derand)(uint8_t *, uint8_t *,

data/ext/pqcrypto/pqcrypto_secure.h

@@ -29,7 +29,9 @@ typedef enum {
     PQ_ERROR_RANDOM = -7,
     PQ_ERROR_BUFFER = -8,
     PQ_ERROR_NOMEM = -9,
-    PQ_ERROR_OPENSSL = -10
+    PQ_ERROR_OPENSSL = -10,
+    PQ_ERROR_INVALID_PUBLIC_KEY = -11,
+    PQ_ERROR_INVALID_SECRET_KEY = -12
 } pq_error_t;
 
 typedef struct {
@@ -83,6 +85,17 @@ int pq_mlkem512_decapsulate(uint8_t *shared_secret, const uint8_t *ciphertext,
 int pq_mlkem1024_decapsulate(uint8_t *shared_secret, const uint8_t *ciphertext,
                              const uint8_t *secret_key);
 
+int pq_mlkem_check_public_key(const uint8_t *public_key);
+int pq_mlkem_check_secret_key(const uint8_t *secret_key);
+int pq_mlkem512_check_public_key(const uint8_t *public_key);
+int pq_mlkem512_check_secret_key(const uint8_t *secret_key);
+int pq_mlkem1024_check_public_key(const uint8_t *public_key);
+int pq_mlkem1024_check_secret_key(const uint8_t *secret_key);
+
+int pq_mldsa_check_secret_key(const uint8_t *secret_key);
+int pq_mldsa44_check_secret_key(const uint8_t *secret_key);
+int pq_mldsa87_check_secret_key(const uint8_t *secret_key);
+
 int pq_sign_keypair(uint8_t *public_key, uint8_t *secret_key);
 int pq_mldsa44_sign_keypair(uint8_t *public_key, uint8_t *secret_key);
 int pq_mldsa87_sign_keypair(uint8_t *public_key, uint8_t *secret_key);

data/ext/pqcrypto/pqcrypto_version.h

@@ -2,6 +2,6 @@
 #ifndef PQCRYPTO_VERSION_H
 #define PQCRYPTO_VERSION_H
 
-#define PQCRYPTO_VERSION "0.6.6"
+#define PQCRYPTO_VERSION "0.6.7"
 
 #endif

data/lib/pq_crypto/internal.rb

@@ -8,6 +8,16 @@ module PQCrypto
       String(value).b
     end
 
+    def frozen_binary_string(value)
+      binary_string(value).freeze
+    end
+
+    def strict_boolean!(value, name:)
+      return value if value.equal?(true) || value.equal?(false)
+
+      raise ArgumentError, "#{name} must be true or false (got #{value.inspect})"
+    end
+
     def safe_wipe(value)
       return unless value.is_a?(String) && !value.frozen?
 

data/lib/pq_crypto/kem.rb

@@ -14,18 +14,24 @@ module PQCrypto
         keypair_from_seed: :native_ml_kem_512_keypair_from_seed,
         encapsulate: :native_ml_kem_512_encapsulate,
         decapsulate: :native_ml_kem_512_decapsulate,
+        check_public_key: :native_ml_kem_512_check_public_key,
+        check_secret_key: :native_ml_kem_512_check_secret_key,
       }.freeze,
       ml_kem_768: {
         keypair: :native_ml_kem_keypair,
         keypair_from_seed: :native_ml_kem_keypair_from_seed,
         encapsulate: :native_ml_kem_encapsulate,
         decapsulate: :native_ml_kem_decapsulate,
+        check_public_key: :native_ml_kem_check_public_key,
+        check_secret_key: :native_ml_kem_check_secret_key,
       }.freeze,
       ml_kem_1024: {
         keypair: :native_ml_kem_1024_keypair,
         keypair_from_seed: :native_ml_kem_1024_keypair_from_seed,
         encapsulate: :native_ml_kem_1024_encapsulate,
         decapsulate: :native_ml_kem_1024_decapsulate,
+        check_public_key: :native_ml_kem_1024_check_public_key,
+        check_secret_key: :native_ml_kem_1024_check_secret_key,
       }.freeze,
     }.freeze
 
@@ -68,12 +74,18 @@ module PQCrypto
         SecretKey.new(resolve_algorithm!(resolved_algorithm), bytes)
       end
 
-      def secret_key_from_pkcs8_der(der, passphrase: nil)
-        secret_key_from_decoded_pkcs8(*PKCS8.decode_der(der, passphrase: passphrase))
+      def secret_key_from_pkcs8_der(der, passphrase: nil, require_encrypted: false)
+        require_encrypted = Internal.strict_boolean!(require_encrypted, name: "require_encrypted")
+        secret_key_from_decoded_pkcs8(
+          *PKCS8.decode_der(der, passphrase: passphrase, require_encrypted: require_encrypted)
+        )
       end
 
-      def secret_key_from_pkcs8_pem(pem, passphrase: nil)
-        secret_key_from_decoded_pkcs8(*PKCS8.decode_pem(pem, passphrase: passphrase))
+      def secret_key_from_pkcs8_pem(pem, passphrase: nil, require_encrypted: false)
+        require_encrypted = Internal.strict_boolean!(require_encrypted, name: "require_encrypted")
+        secret_key_from_decoded_pkcs8(
+          *PKCS8.decode_pem(pem, passphrase: passphrase, require_encrypted: require_encrypted)
+        )
       end
 
       def public_key_from_spki_der(der, algorithm: nil)
@@ -121,6 +133,10 @@ module PQCrypto
         end
       end
 
+      def checkable?(algorithm)
+        NATIVE_DISPATCH.key?(algorithm) && NATIVE_DISPATCH.fetch(algorithm).key?(:check_public_key)
+      end
+
       def native_method_for(algorithm, operation)
         NATIVE_DISPATCH.fetch(resolve_algorithm!(algorithm)).fetch(operation)
       end
@@ -158,8 +174,19 @@ module PQCrypto
 
       def initialize(algorithm, bytes)
         @algorithm = algorithm
-        @bytes = Internal.binary_string(bytes)
+        @bytes = Internal.frozen_binary_string(bytes)
         validate_length!
+        validate_structure!
+      end
+
+      def valid?
+        if @algorithm == :ml_kem_768_x25519_xwing
+          mlkem_half = @bytes.byteslice(0, KEM.details(:ml_kem_768).fetch(:public_key_bytes))
+          return PQCrypto.__send__(:native_ml_kem_check_public_key, mlkem_half)
+        end
+        return true unless KEM.send(:checkable?, @algorithm)
+
+        PQCrypto.__send__(KEM.send(:native_method_for, @algorithm, :check_public_key), @bytes)
       end
 
       def to_bytes
@@ -219,6 +246,10 @@ module PQCrypto
         expected = KEM.details(@algorithm).fetch(:public_key_bytes)
         raise InvalidKeyError, "Invalid KEM public key length" unless @bytes.bytesize == expected
       end
+
+      def validate_structure!
+        raise InvalidKeyError, "Invalid #{@algorithm} public key: FIPS 203 modulus check failed" unless valid?
+      end
     end
 
     class SecretKey
@@ -230,6 +261,13 @@ module PQCrypto
         @seed = seed.nil? ? nil : Internal.binary_string(seed)
         validate_length!
         validate_seed_length! if @seed
+        validate_structure!
+      end
+
+      def valid?
+        return true unless KEM.send(:checkable?, @algorithm)
+
+        PQCrypto.__send__(KEM.send(:native_method_for, @algorithm, :check_secret_key), @bytes)
       end
 
       def self.from_seed(algorithm, seed)
@@ -298,6 +336,10 @@ module PQCrypto
         raise InvalidKeyError, "Invalid KEM secret key length" unless @bytes.bytesize == expected
       end
 
+      def validate_structure!
+        raise InvalidKeyError, "Invalid #{@algorithm} secret key: FIPS 203 hash check failed" unless valid?
+      end
+
       def pkcs8_material(format)
         case format
         when :expanded

data/lib/pq_crypto/key.rb

@@ -17,22 +17,24 @@ module PQCrypto
         end
       end
 
-      def from_pem(pem, passphrase: nil)
+      def from_pem(pem, passphrase: nil, require_encrypted: false)
+        require_encrypted = Internal.strict_boolean!(require_encrypted, name: "require_encrypted")
         text = String(pem)
         if text.include?(SPKI::PEM_BEGIN)
           public_key_from_spki_pem(text)
         elsif text.include?(PKCS8::PEM_BEGIN) || text.include?(PKCS8::ENCRYPTED_PEM_BEGIN)
-          secret_key_from_pkcs8_pem(text, passphrase: passphrase)
+          secret_key_from_pkcs8_pem(text, passphrase: passphrase, require_encrypted: require_encrypted)
         else
           raise SerializationError, "Unsupported PEM label for PQCrypto::Key.from_pem"
         end
       end
 
-      def from_der(der, passphrase: nil)
+      def from_der(der, passphrase: nil, require_encrypted: false)
+        require_encrypted = Internal.strict_boolean!(require_encrypted, name: "require_encrypted")
         public_key_from_spki_der(der)
       rescue SerializationError => spki_error
         begin
-          secret_key_from_pkcs8_der(der, passphrase: passphrase)
+          secret_key_from_pkcs8_der(der, passphrase: passphrase, require_encrypted: require_encrypted)
         rescue SerializationError => pkcs8_error
           raise SerializationError,
                 "Unable to decode DER as SPKI or PKCS#8 (SPKI: #{spki_error.message}; PKCS#8: #{pkcs8_error.message})"
@@ -56,12 +58,16 @@ module PQCrypto
         public_key_from_algorithm_and_bytes(algorithm, bytes)
       end
 
-      def secret_key_from_pkcs8_pem(pem, passphrase: nil)
-        secret_key_from_decoded_pkcs8(*PKCS8.decode_pem(pem, passphrase: passphrase))
+      def secret_key_from_pkcs8_pem(pem, passphrase: nil, require_encrypted: false)
+        secret_key_from_decoded_pkcs8(
+          *PKCS8.decode_pem(pem, passphrase: passphrase, require_encrypted: require_encrypted)
+        )
       end
 
-      def secret_key_from_pkcs8_der(der, passphrase: nil)
-        secret_key_from_decoded_pkcs8(*PKCS8.decode_der(der, passphrase: passphrase))
+      def secret_key_from_pkcs8_der(der, passphrase: nil, require_encrypted: false)
+        secret_key_from_decoded_pkcs8(
+          *PKCS8.decode_der(der, passphrase: passphrase, require_encrypted: require_encrypted)
+        )
       end
 
       def secret_key_from_decoded_pkcs8(algorithm, format, material)

data/lib/pq_crypto/pkcs8.rb

@@ -70,10 +70,16 @@ module PQCrypto
         der = encode_der(algorithm, secret_material, format: format, passphrase: passphrase, iterations: iterations)
         pkcs8_native { PQCrypto.__send__(:native_pkcs8_der_to_pem, der, !passphrase.nil?) }
       end
-
-      def decode_der(der, passphrase: nil)
+      def decode_der(der, passphrase: nil, require_encrypted: false)
+        require_encrypted = Internal.strict_boolean!(require_encrypted, name: "require_encrypted")
         input = Internal.binary_string(der)
-        return decode_encrypted_der(input, passphrase: passphrase) if encrypted_der?(input)
+        encrypted = encrypted_der?(input)
+
+        if require_encrypted && !encrypted
+          raise SerializationError, "PKCS#8 input is not encrypted, but require_encrypted: true was requested"
+        end
+
+        return decode_encrypted_der(input, passphrase: passphrase) if encrypted
 
         oid, choice_der = private_key_info_from_der(input)
         algorithm = AlgorithmRegistry.by_standard_oid(oid)
@@ -83,15 +89,17 @@ module PQCrypto
         PrivateKeyChoice.validate_secret_key_algorithm!(algorithm, entry)
         PrivateKeyChoice.decode(algorithm, Internal.binary_string(choice_der))
       rescue ArgumentError => e
+        raise if e.message.start_with?("require_encrypted")
         raise SerializationError, e.message
       ensure
         Internal.safe_wipe(choice_der) if defined?(choice_der)
       end
 
-      def decode_pem(pem, passphrase: nil)
+      def decode_pem(pem, passphrase: nil, require_encrypted: false)
+        require_encrypted = Internal.strict_boolean!(require_encrypted, name: "require_encrypted")
         _encrypted, der = pkcs8_native { PQCrypto.__send__(:native_pkcs8_pem_to_der, String(pem)) }
         begin
-          decode_der(der, passphrase: passphrase)
+          decode_der(der, passphrase: passphrase, require_encrypted: require_encrypted)
         ensure
           Internal.safe_wipe(der)
         end

data/lib/pq_crypto/signature.rb

@@ -14,18 +14,21 @@ module PQCrypto
         sign: :native_ml_dsa_44_sign,
         verify: :native_ml_dsa_44_verify,
         keypair_from_seed: :native_ml_dsa_44_keypair_from_seed,
+        check_secret_key: :native_ml_dsa_44_check_secret_key,
       }.freeze,
       ml_dsa_65: {
         keypair: :native_sign_keypair,
         sign: :native_sign,
         verify: :native_verify,
         keypair_from_seed: :native_ml_dsa_keypair_from_seed,
+        check_secret_key: :native_ml_dsa_check_secret_key,
       }.freeze,
       ml_dsa_87: {
         keypair: :native_ml_dsa_87_keypair,
         sign: :native_ml_dsa_87_sign,
         verify: :native_ml_dsa_87_verify,
         keypair_from_seed: :native_ml_dsa_87_keypair_from_seed,
+        check_secret_key: :native_ml_dsa_87_check_secret_key,
       }.freeze,
     }.freeze
 
@@ -33,7 +36,8 @@ module PQCrypto
       def generate(algorithm = CANONICAL_ALGORITHM)
         algorithm = resolve_algorithm!(algorithm)
         public_key, secret_key = PQCrypto.__send__(native_method_for(algorithm, :keypair))
-        Keypair.new(PublicKey.new(algorithm, public_key), SecretKey.new(algorithm, secret_key))
+        Keypair.new(PublicKey.new(algorithm, public_key),
+                    SecretKey.new(algorithm, secret_key, freshly_generated: true))
       end
 
       def public_key_from_bytes(algorithm, bytes)
@@ -86,12 +90,18 @@ module PQCrypto
         PublicKey.new(resolve_algorithm!(resolved_algorithm), bytes)
       end
 
-      def secret_key_from_pkcs8_der(der, passphrase: nil)
-        secret_key_from_decoded_pkcs8(*PKCS8.decode_der(der, passphrase: passphrase))
+      def secret_key_from_pkcs8_der(der, passphrase: nil, require_encrypted: false)
+        require_encrypted = Internal.strict_boolean!(require_encrypted, name: "require_encrypted")
+        secret_key_from_decoded_pkcs8(
+          *PKCS8.decode_der(der, passphrase: passphrase, require_encrypted: require_encrypted)
+        )
       end
 
-      def secret_key_from_pkcs8_pem(pem, passphrase: nil)
-        secret_key_from_decoded_pkcs8(*PKCS8.decode_pem(pem, passphrase: passphrase))
+      def secret_key_from_pkcs8_pem(pem, passphrase: nil, require_encrypted: false)
+        require_encrypted = Internal.strict_boolean!(require_encrypted, name: "require_encrypted")
+        secret_key_from_decoded_pkcs8(
+          *PKCS8.decode_pem(pem, passphrase: passphrase, require_encrypted: require_encrypted)
+        )
       end
 
       def details(algorithm)
@@ -118,7 +128,7 @@ module PQCrypto
           SecretKey.new(algorithm, material)
         when :seed
           _public_key, expanded = PQCrypto.__send__(native_method_for(algorithm, :keypair_from_seed), material)
-          SecretKey.new(algorithm, expanded, seed: material)
+          SecretKey.new(algorithm, expanded, seed: material, freshly_generated: true)
         when :both
           _seed, expanded = material
           SecretKey.new(algorithm, expanded, seed: _seed)
@@ -133,6 +143,10 @@ module PQCrypto
         NATIVE_DISPATCH.fetch(resolve_algorithm!(algorithm)).fetch(operation)
       end
 
+      def secret_key_checkable?(algorithm)
+        NATIVE_DISPATCH.key?(algorithm) && NATIVE_DISPATCH.fetch(algorithm).key?(:check_secret_key)
+      end
+
       def validate_algorithm_match!(expected_algorithm, actual_algorithm)
         expected = resolve_algorithm!(expected_algorithm)
         return if expected == actual_algorithm
@@ -264,7 +278,7 @@ module PQCrypto
 
       def initialize(algorithm, bytes)
         @algorithm = algorithm
-        @bytes = Internal.binary_string(bytes)
+        @bytes = Internal.frozen_binary_string(bytes)
         validate_length!
       end
 
@@ -343,18 +357,25 @@ module PQCrypto
     class SecretKey
       attr_reader :algorithm
 
-      def initialize(algorithm, bytes, seed: nil)
+      def initialize(algorithm, bytes, seed: nil, freshly_generated: false)
         @algorithm = algorithm
         @bytes = Internal.binary_string(bytes)
         @seed = seed.nil? ? nil : Internal.binary_string(seed)
         validate_length!
         validate_seed_length! if @seed
+        validate_structure! unless freshly_generated
+      end
+
+      def valid?
+        return true unless Signature.send(:secret_key_checkable?, @algorithm)
+
+        PQCrypto.__send__(Signature.send(:native_method_for, @algorithm, :check_secret_key), @bytes)
       end
 
       def self.from_seed(algorithm, seed)
         seed_bytes = Internal.binary_string(seed)
         _public_key, expanded = PQCrypto.__send__(Signature.send(:native_method_for, algorithm, :keypair_from_seed), seed_bytes)
-        new(algorithm, expanded, seed: seed_bytes)
+        new(algorithm, expanded, seed: seed_bytes, freshly_generated: true)
       rescue ArgumentError => e
         raise InvalidKeyError, e.message
       end
@@ -424,6 +445,10 @@ module PQCrypto
         raise InvalidKeyError, "Invalid signature secret key length" unless @bytes.bytesize == expected
       end
 
+      def validate_structure!
+        raise InvalidKeyError, "Invalid #{@algorithm} secret key: ML-DSA structure check failed" unless valid?
+      end
+
       def pkcs8_material(format)
         case format
         when :expanded

data/lib/pq_crypto/spki.rb

@@ -26,7 +26,7 @@ module PQCrypto
           ]),
           OpenSSL::ASN1::BitString.new(bytes),
         ]).to_der.b
-      rescue OpenSSL::ASN1::ASN1Error => e
+      rescue OpenSSL::OpenSSLError, TypeError => e
         raise SerializationError, e.message
       end
 
@@ -63,6 +63,8 @@ module PQCrypto
         end
 
         [algorithm, bytes]
+      rescue OpenSSL::OpenSSLError, TypeError => e
+        raise SerializationError, e.message
       end
 
       def decode_pem(pem)
@@ -74,7 +76,7 @@ module PQCrypto
 
       def decode_asn1(der)
         OpenSSL::ASN1.decode(der)
-      rescue OpenSSL::ASN1::ASN1Error => e
+      rescue OpenSSL::OpenSSLError, TypeError => e
         raise SerializationError, e.message
       end
 

data/lib/pq_crypto/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PQCrypto
-  VERSION = "0.6.6"
+  VERSION = "0.6.7"
 end

data/lib/pq_crypto.rb

@@ -65,6 +65,15 @@ module PQCrypto
       ml_kem_1024_keypair_from_seed
       ml_kem_1024_encapsulate
       ml_kem_1024_decapsulate
+      ml_kem_check_public_key
+      ml_kem_check_secret_key
+      ml_kem_512_check_public_key
+      ml_kem_512_check_secret_key
+      ml_kem_1024_check_public_key
+      ml_kem_1024_check_secret_key
+      ml_dsa_check_secret_key
+      ml_dsa_44_check_secret_key
+      ml_dsa_87_check_secret_key
       hybrid_kem_keypair
       hybrid_kem_encapsulate
       hybrid_kem_expand_secret_key

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pq_crypto
 version: !ruby/object:Gem::Version
-  version: 0.6.6
+  version: 0.6.7
 platform: ruby
 authors:
 - Roman Haydarov