pq_crypto 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2274795113da1599b664af11b1393a86d68f1886f3536e0a65385b04b8ce03fe
-  data.tar.gz: 386fe1093ba0b28a910195a40d7698e0cef91f9f57fc90b3a1aaac3eec4451a5
+  metadata.gz: 11bb63e90651697a30709e9621678c7a53224facc67264a331291a8c57520880
+  data.tar.gz: 111c87fa0809924f0c2997fc0d9c2ea41c43e88044c2802d35370c01ed5f88ca
 SHA512:
-  metadata.gz: f9f73a9d575d9931020e1674f96adafe08816a1f7183b0b948194fcd2fb4da106afb854525ef544409b47bde34c987ac0eae6ce54440b7562f70faf5807446c3
-  data.tar.gz: c5e54b45ab8461bd1edd2b3e4e14f0092267232bc3bf1436841488fa7a604fdf66056dfd160767ec2d47b0a4afe37cb660a46a54466677994a3c1d73269959d1
+  metadata.gz: c95c38ec77fce342cb92febfbdbecdee5c35495323e7f153a2e263e04b89dc6cb13e8bd2874b8abb0b5e19e5b26cde13fb7f6b9d99ef107c5d6e3e41b20d819c
+  data.tar.gz: 1aa62a91a03203fcd6253e3175d1166b5bf2a3590889509517b8b5eaa57ff6fac49023b253f0859b45c7c2e0f4b28b849a657a5d089890b328da8a234ef7b5c9

data/.github/workflows/ci.yml

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

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.6.0] - 2026-05-14
+
+### Added
+
+- Added seed-aware `SecretKey.from_seed` helpers for ML-KEM and ML-DSA, with PKCS#8 `:seed` / `:both` re-export when seed material is retained.
+- Added one-shot ML-DSA `context:` support, ML-DSA-44/65/87 streaming coverage, encrypted PKCS#8, and `PQCrypto::Key.from_pem/from_der` auto-dispatch.
+
+### Security
+
+- Tightened secret-key lifetime handling for PKCS#8 temporary buffers, key equality, and HybridKEM expanded-key wiping.
+
+## [0.5.3] - 2026-05-08
+
+### Compatibility
+
+- Lowered the minimum supported Ruby version from `>= 3.4.0` to `>= 3.1`.
+- Kept the Ruby 3.4+ optimized `rb_nogvl(..., RB_NOGVL_OFFLOAD_SAFE)` path intact.
+- Added explicit native build probes for `ruby/thread.h`, `rb_thread_call_without_gvl`, and `rb_nogvl`.
+- Ruby 3.1-3.3 now build the same selected `rb_nogvl` calls with a local `PQ_RB_NOGVL_OFFLOAD_SAFE` fallback of `0`, preserving ordinary no-GVL behavior without claiming scheduler offload guarantees.
+
+### CI
+
+- Added Ruby 3.1-3.3 compatibility coverage as compile + smoke checks while keeping full test coverage on Ruby 3.4 and 4.0.
+- Scoped the strict Async/Fiber Scheduler integration assertion to Ruby 3.4+ so compatibility runtimes do not claim `RB_NOGVL_OFFLOAD_SAFE` behavior.
+- Pinned the test-only `async` dependency to the Ruby 3.1-compatible `2.21.x` line, which still contains the worker-pool support needed for the Ruby 3.4+ offload test.
+
+### Documentation
+
+- Documented the Ruby 3.1+ support policy and the difference between compatibility no-GVL behavior and Ruby 3.4+ scheduler-aware offload.
+
 ## [0.5.2] - 2026-05-06
 
 ### Build

data/GET_STARTED.md

@@ -115,6 +115,19 @@ public_key.verify!(message, signature)
 # returns true, or raises on mismatch
 ```
 
+Use `context:` when the same key is shared across domains or protocols:
+
+```ruby
+context = "orders-v1".b
+signature = secret_key.sign(message, context: context)
+
+public_key.verify(message, signature, context: context)
+# => true
+
+public_key.verify(message, signature, context: "other".b)
+# => false
+```
+
 The same API shape applies to other supported ML-DSA parameter sets:
 
 ```ruby
@@ -125,7 +138,8 @@ PQCrypto::Signature.generate(:ml_dsa_87)
 ## 5. ML-DSA for large files
 
 For large inputs, use the streaming helpers so the whole message does not need
-to be materialized as one Ruby string.
+to be materialized as one Ruby string. Streaming is available for
+`:ml_dsa_44`, `:ml_dsa_65`, and `:ml_dsa_87`.
 
 ```ruby
 keypair = PQCrypto::Signature.generate(:ml_dsa_65)
@@ -246,10 +260,19 @@ der = keypair.secret_key.to_pkcs8_der
 imported = PQCrypto::KEM.secret_key_from_pkcs8_der(der)
 ```
 
-ML-KEM PKCS#8 supports `:seed`, `:expanded`, and `:both` formats. A generated
-`SecretKey` does not retain the original seed, so exporting `:seed` or `:both`
-from `SecretKey#to_pkcs8_*` is intentionally unavailable. If you explicitly
-have the seed material, use the low-level PKCS#8 encoder.
+ML-KEM PKCS#8 supports `:seed`, `:expanded`, and `:both` formats. Generated
+keys export `:expanded` by default. If you have 64-byte seed material, build a
+seed-aware key to allow `:seed` and `:both` re-export:
+
+```ruby
+require "securerandom"
+
+seed = SecureRandom.random_bytes(PQCrypto::PKCS8::ML_KEM_SEED_BYTES)
+secret_key = PQCrypto::KEM.secret_key_from_seed(:ml_kem_768, seed)
+
+pem = secret_key.to_pkcs8_pem(format: :both)
+imported = PQCrypto::KEM.secret_key_from_pkcs8_pem(pem)
+```
 
 ### ML-DSA PKCS#8
 
@@ -269,10 +292,48 @@ PQCrypto::PKCS8.allow_ml_dsa_seed_format = true
 imported = PQCrypto::Signature.secret_key_from_pkcs8_pem(pem)
 ```
 
-Seed/both export from an existing ML-DSA `SecretKey` is intentionally not
-available because the object does not retain the original seed material. When
-you explicitly have seed material, call `PQCrypto::PKCS8.encode_der` /
-`encode_pem` directly.
+If you have 32-byte seed material, build a seed-aware key to allow `:seed` and
+`:both` re-export:
+
+```ruby
+require "securerandom"
+
+PQCrypto::PKCS8.allow_ml_dsa_seed_format = true
+
+seed = SecureRandom.random_bytes(PQCrypto::PKCS8::ML_DSA_SEED_BYTES)
+secret_key = PQCrypto::Signature.secret_key_from_seed(:ml_dsa_65, seed)
+
+pem = secret_key.to_pkcs8_pem(format: :both)
+imported = PQCrypto::Signature.secret_key_from_pkcs8_pem(pem)
+```
+
+### Encrypted PKCS#8
+
+Pass `passphrase:` to export encrypted private keys:
+
+```ruby
+keypair = PQCrypto::Signature.generate(:ml_dsa_65)
+
+pem = keypair.secret_key.to_pkcs8_pem(passphrase: "correct horse")
+imported = PQCrypto::Signature.secret_key_from_pkcs8_pem(
+  pem,
+  passphrase: "correct horse",
+)
+```
+
+The same option is available for DER and ML-KEM secret keys.
+
+### Auto-dispatch key loading
+
+Use `PQCrypto::Key` when you want the gem to detect SPKI vs PKCS#8 and the
+algorithm family from the encoded key:
+
+```ruby
+key = PQCrypto::Key.from_pem(pem, passphrase: "correct horse")
+key = PQCrypto::Key.from_der(der)
+
+keypair = PQCrypto::Key.generate(:ml_kem_768)
+```
 
 ## 9. pq_crypto-local container serialization
 
@@ -379,11 +440,15 @@ PQCRYPTO_NATIVE_ASM=1 bundle exec rake compile
 
 ## 14. Async / Fiber scheduler behavior
 
-On Ruby 3.4, signing and verification use Ruby's scheduler-aware
+On Ruby 3.4 and later, signing and verification keep Ruby's scheduler-aware
 `rb_nogvl(..., RB_NOGVL_OFFLOAD_SAFE)` path automatically. With a scheduler
 that implements `blocking_operation_wait`, blocking native work can be moved
 off the event loop.
 
+Ruby 3.1-3.3 are supported as a compatibility path: native operations still
+release the GVL, but `RB_NOGVL_OFFLOAD_SAFE` is not available there, so the gem
+does not claim Fiber Scheduler offload guarantees on those runtimes.
+
 ## 15. Test-only deterministic helpers
 
 `PQCrypto::Testing` exposes deterministic helpers for regression tests:

data/README.md

@@ -35,10 +35,10 @@ bundle exec rake test
 
 | 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. |
+| ML-KEM | Key generation, seed-aware secret keys, encapsulation, decapsulation, raw key import/export, SPKI public keys, PKCS#8 private keys. |
+| ML-DSA | Key generation, seed-aware secret keys, signing/verification with optional FIPS 204 context, 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. |
+| Serialization | Standard SPKI / PKCS#8 for NIST PQC keys, encrypted PKCS#8 private keys, auto-dispatch key loading, 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. |
 
@@ -63,7 +63,9 @@ original algorithms:
 
 ## Requirements
 
-- Ruby 3.4 or later
+- Ruby 3.1 or later
+  - Ruby 3.4+ keeps the optimized Fiber Scheduler offload path via `RB_NOGVL_OFFLOAD_SAFE`
+  - Ruby 3.1-3.3 use the compatibility no-GVL path without scheduler offload guarantees
 - 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`
@@ -109,8 +111,13 @@ PQCrypto.supported_signatures
 PQCrypto.supported_hybrid_kems
 
 PQCrypto::KEM.generate(:ml_kem_768)
+PQCrypto::KEM.secret_key_from_seed(:ml_kem_768, seed_64_bytes)
+
 PQCrypto::Signature.generate(:ml_dsa_65)
+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)
 ```
 
 ## More examples
@@ -119,9 +126,9 @@ Detailed usage examples live in [`GET_STARTED.md`](GET_STARTED.md):
 
 - generating keys
 - ML-KEM encapsulation / decapsulation
-- ML-DSA signing / verification
+- ML-DSA signing / verification with optional FIPS 204 context
 - streaming ML-DSA for large files
-- SPKI and PKCS#8 serialization
+- SPKI, PKCS#8, encrypted PKCS#8, and auto-dispatch key loading
 - `pqc_container_*` compatibility serialization
 - native backend / vendoring notes
-- secure wiping and practical safety notes
+- seed-aware keys, secure wiping, and practical safety notes

data/ext/pqcrypto/extconf.rb

@@ -187,6 +187,12 @@ def find_vendor_dir
   candidates.find { |path| native_vendor_ready?(path) }
 end
 
+def configure_ruby_c_api!
+  abort "ruby/thread.h is required" unless have_header("ruby/thread.h")
+  abort "rb_thread_call_without_gvl is required" unless have_func("rb_thread_call_without_gvl", "ruby/thread.h")
+  abort "rb_nogvl is required" unless have_func("rb_nogvl", "ruby/thread.h")
+end
+
 def configure_openssl!
   configure_compiler_environment
 
@@ -349,6 +355,7 @@ vendor_dir = find_vendor_dir
 
 puts
 puts "=== PQCrypto build configuration ==="
+configure_ruby_c_api!
 configure_openssl!
 native_config = native_vendor_config(vendor_dir)
 puts "OpenSSL: system"

data/ext/pqcrypto/pq_externalmu.c

@@ -34,57 +34,62 @@ cleanup:
     return ret;
 }
 
-int pq_mldsa_extract_tr_from_secret_key(uint8_t *tr_out, const uint8_t *secret_key) {
-    uint8_t public_key[MLDSA_PUBLICKEYBYTES];
+int pq_mldsa_extract_tr_from_secret_key(uint8_t *tr_out, const uint8_t *secret_key,
+                                        size_t public_key_len,
+                                        int (*pk_from_sk)(uint8_t *, const uint8_t *)) {
+    uint8_t public_key[MLDSA87_PUBLICKEYBYTES];
     int rc;
 
-    if (tr_out == NULL || secret_key == NULL) {
+    if (tr_out == NULL || secret_key == NULL || pk_from_sk == NULL || public_key_len == 0 ||
+        public_key_len > sizeof(public_key)) {
         return PQ_ERROR_BUFFER;
     }
 
     memset(public_key, 0, sizeof(public_key));
-    rc = pqcr_mldsa65_pk_from_sk(public_key, secret_key);
+    rc = pk_from_sk(public_key, secret_key);
     if (rc != 0) {
         pq_secure_wipe(public_key, sizeof(public_key));
         return PQ_ERROR_KEYPAIR;
     }
 
-    rc = pq_shake256(tr_out, PQ_MLDSA_TRBYTES, public_key, sizeof(public_key));
+    rc = pq_shake256(tr_out, PQ_MLDSA_TRBYTES, public_key, public_key_len);
     pq_secure_wipe(public_key, sizeof(public_key));
     return rc;
 }
 
-int pq_mldsa_compute_tr_from_public_key(uint8_t *tr_out, const uint8_t *public_key) {
+int pq_mldsa_compute_tr_from_public_key(uint8_t *tr_out, const uint8_t *public_key,
+                                        size_t public_key_len) {
     if (tr_out == NULL || public_key == NULL) {
         return PQ_ERROR_BUFFER;
     }
 
-    return pq_shake256(tr_out, PQ_MLDSA_TRBYTES, public_key, MLDSA_PUBLICKEYBYTES);
+    return pq_shake256(tr_out, PQ_MLDSA_TRBYTES, public_key, public_key_len);
 }
 
 int pq_sign_mu(uint8_t *signature, size_t *signature_len, const uint8_t *mu,
-               const uint8_t *secret_key) {
-    if (signature == NULL || signature_len == NULL || mu == NULL || secret_key == NULL) {
+               const uint8_t *secret_key,
+               int (*signature_extmu)(uint8_t *, size_t *, const uint8_t *, const uint8_t *)) {
+    if (signature == NULL || signature_len == NULL || mu == NULL || secret_key == NULL ||
+        signature_extmu == NULL) {
         return PQ_ERROR_BUFFER;
     }
 
-    return pqcr_mldsa65_signature_extmu(signature, signature_len, mu, secret_key) == 0
-               ? PQ_SUCCESS
-               : PQ_ERROR_SIGN;
+    return signature_extmu(signature, signature_len, mu, secret_key) == 0 ? PQ_SUCCESS
+                                                                          : PQ_ERROR_SIGN;
 }
 
 int pq_verify_mu(const uint8_t *signature, size_t signature_len, const uint8_t *mu,
-                 const uint8_t *public_key) {
-    if (signature == NULL || mu == NULL || public_key == NULL) {
+                 const uint8_t *public_key, size_t expected_signature_len,
+                 int (*verify_extmu)(const uint8_t *, size_t, const uint8_t *, const uint8_t *)) {
+    if (signature == NULL || mu == NULL || public_key == NULL || verify_extmu == NULL) {
         return PQ_ERROR_BUFFER;
     }
-    if (signature_len != MLDSA_BYTES) {
+    if (signature_len != expected_signature_len) {
         return PQ_ERROR_VERIFY;
     }
 
-    return pqcr_mldsa65_verify_extmu(signature, signature_len, mu, public_key) == 0
-               ? PQ_SUCCESS
-               : PQ_ERROR_VERIFY;
+    return verify_extmu(signature, signature_len, mu, public_key) == 0 ? PQ_SUCCESS
+                                                                       : PQ_ERROR_VERIFY;
 }
 
 void *pq_mu_builder_new(void) {

data/ext/pqcrypto/pqcrypto_native_api.h

@@ -95,6 +95,11 @@ int pqcr_mldsa44_verify(const uint8_t *sig, size_t siglen, const uint8_t *m, siz
 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],
+                              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]);
@@ -128,5 +133,10 @@ int pqcr_mldsa87_verify(const uint8_t *sig, size_t siglen, const uint8_t *m, siz
 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],
+                              const uint8_t *pk);
+int pqcr_mldsa87_pk_from_sk(uint8_t *pk, const uint8_t *sk);
 
 #endif