pq_crypto 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0911b99fec80d68a6dff827829bbd77a28951d70c4a85f4fc68bc8c03bdffdda'
-  data.tar.gz: fb7f9e92387316b6641b191dc1d1f5c469f5297d866301a21d44d4eb789185e6
+  metadata.gz: 11bb63e90651697a30709e9621678c7a53224facc67264a331291a8c57520880
+  data.tar.gz: 111c87fa0809924f0c2997fc0d9c2ea41c43e88044c2802d35370c01ed5f88ca
 SHA512:
-  metadata.gz: 0a614e2b3a645332a3543062efd754421a4a002f08b7b2b71463ee2817f5008a14e65745c66d0c24b5b11a1ecb020f4fe9d479ff59676ddf770186d8d286e26a
-  data.tar.gz: ef7bd96e717b4a99b74346dfd2c98c4787bc3b09b3a1199acfe01b0a22ea2f26cfd594499f3948241abf207dab9d5602f21aaa0a21c66742710637ce53f1a07f
+  metadata.gz: c95c38ec77fce342cb92febfbdbecdee5c35495323e7f153a2e263e04b89dc6cb13e8bd2874b8abb0b5e19e5b26cde13fb7f6b9d99ef107c5d6e3e41b20d819c
+  data.tar.gz: 1aa62a91a03203fcd6253e3175d1166b5bf2a3590889509517b8b5eaa57ff6fac49023b253f0859b45c7c2e0f4b28b849a657a5d089890b328da8a234ef7b5c9

data/CHANGELOG.md

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

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
 

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. |
 
@@ -111,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
@@ -121,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/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