linzer 0.8.1.beta2 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bc1cb6232547c649f0c082b444d858632abcb7cd923a50c1bf55ea6da316034
-  data.tar.gz: 97da42478725e85ab12f9475f2808350dc76981c3f705a8e1479c57b7509f095
+  metadata.gz: 188e4a68a86287824bb5ba37a0c1b476abb9bd20b7b96048f13f230c070bab08
+  data.tar.gz: dc3e0081f6baaaf85d30e532fe7c5cf0bf1cb1e7b566dd8493701b754fabdfa3
 SHA512:
-  metadata.gz: 537e717e95afee1f2c32534ef294608020869b59aa4b07abdc58a629df11c74878390d0f0fa6202bbb7adf913ee70defde827f6f4c8e3c5d50d60c5fd159a1fe
-  data.tar.gz: 55337d62a400418a8b46bbd240a588e0fa6d66aef18df4c10938b0715919f8b236fb985a3ab0a082cb7fc10f13b27051f261daecf48a469b33ff11c5d7a19b7f
+  metadata.gz: 2af5b16fa7832bce168d2fa024dbbe28adfff00d126b520c87e241348eb34f9f1133fd98a85ca3fec6cfd945f773165e0cfe3230420e086a91f1f59fa4eb67b8
+  data.tar.gz: 386f5fb8bfe0ddea3d045c66ed52d52a9dab9704c79662ada309027185b67cf0cd6887e5c4becaa64a8410c1aa4419c2274c6739d29743d74d9854da79f3e4c8

data/CHANGELOG.md

@@ -1,5 +1,65 @@
 ## [Unreleased]
 
+## [0.8.1] - 2026-08-25
+
+(No major changes since the last beta release, this stable release
+bundles the ML-DSA/post-quantum work from both 0.8.1 betas
+(`ml_dsa`-gem-backed in beta1, OpenSSL-native and default-preferred in
+beta2), completing post-quantum HTTP Message Signatures support and
+closing [#28](https://github.com/nomadium/linzer/issues/28), plus a few
+unrelated Web Bot Auth fixes.)
+
+- Add ML-DSA-44, ML-DSA-65, and ML-DSA-87 support following the C2SP
+  post-quantum HTTP Message Signatures profile, including raw, DER, and PEM
+  key loading and strict parameter-set binding.
+  Pull request [#29](https://github.com/nomadium/linzer/pull/29)
+  by [soatok](https://github.com/soatok).
+  It can be used explicitly via `backend: :ml_dsa` by adding the `ml_dsa`
+  gem to your own Gemfile and `require "linzer/ml_dsa"` before use.
+
+- Add an OpenSSL-native ML-DSA backend, preferred by default over the
+  `ml_dsa` gem whenever this build's OpenSSL actually supports it (all
+  three FIPS 204 parameter sets: ML-DSA-44, ML-DSA-65, ML-DSA-87). Pass
+  `backend: :openssl` or `backend: :ml_dsa` to any
+  `generate_ml_dsa_*_key`/`new_ml_dsa_*_key` method to select
+  explicitly instead of relying on auto-selection; `key.backend`
+  reports which one produced a given key.
+  Pull request [#33](https://github.com/nomadium/linzer/pull/33)
+  by [nomadium](https://github.com/nomadium).
+  Since OpenSSL is now the default backend for ML-DSA, `ml_dsa` is no
+  longer a hard runtime dependency, so the minimum Ruby version moves
+  back down to 2.7.0.
+
+- ML-DSA keys generated or loaded with one backend can now be moved to
+  the other: raw public/private key bytes round-trip correctly between
+  the OpenSSL-native and `ml_dsa` gem backends. The raw-byte extraction
+  methods behind this (`Linzer::MLDSA::OpenSSLKey.unwrap_raw_public_key`/
+  `unwrap_raw_private_key`) are available for advanced use, though not
+  yet a stable public API.
+
+- Fix Web Bot Auth's `keyid` being computed incorrectly for
+  Ed25519/OKP keys: jwt-eddsa <= 0.9.0 computed the RFC 7638 JWK
+  thumbprint over the wrong members, so the derived `keyid` didn't
+  match what a spec-compliant verifier expects. Linzer now computes it
+  independently via the new `Linzer::JWS::Key#jwk_thumbprint`.
+
+- `Linzer::JWS::Key#jwk_thumbprint` now delegates to jwt-eddsa's own
+  `key_digest` instead of a local RFC 7638 workaround, now that
+  jwt-eddsa >= 1.0 computes it correctly for OKP keys. Linzer now
+  requires jwt-eddsa >= 1.0 for JWS/EdDSA support and raises a clear
+  error at `require "linzer/jws"` time on older versions.
+
+- Fix `Signer.sign!`'s signature `label` defaulting to
+  `"sig1"` too late — after `profile.apply(ctx)` already ran, breaking
+  any profile (like Web Bot Auth's `Signature-Agent` header) that needs
+  a real label at apply time. The default now applies before any
+  profile runs.
+
+- Fix `Signature-Agent` being sent as a bare, unquoted URL,
+  which isn't valid per draft-meunier-web-bot-auth-architecture
+  Appendix A.1.3. Now quoted as a proper RFC 8941 Structured Field
+  string.
+
 ## [0.8.1.beta2] - 2026-08-14
 
 - Add an OpenSSL-native ML-DSA backend, preferred by default over the

data/README.md

@@ -584,7 +584,7 @@ gem "ml_dsa"
 ```
 
 ```ruby
-require "linzer/ml_dsa/gem_key"
+require "linzer/ml_dsa"
 
 key = Linzer.generate_ml_dsa_44_key
 ```
@@ -593,6 +593,14 @@ Pass `backend: :openssl` or `backend: :ml_dsa` to any `generate_ml_dsa_*`/
 `new_ml_dsa_*` method to force a specific implementation instead of
 relying on auto-selection.
 
+Keys are portable between the two backends: raw public/private key
+bytes produced by one load correctly via the other, so switching
+`backend:` -- or moving a key between hosts with different OpenSSL
+capabilities -- doesn't require regenerating anything. (The raw-byte
+extraction methods behind this, `Linzer::MLDSA::OpenSSLKey.unwrap_raw_public_key`/
+`unwrap_raw_private_key`, are available for advanced use but not yet a
+stable public API.)
+
 ### JSON Web Signature (JWS) algorithms
 
 Of the JSON Web Signature (JWS) algorithms mentioned in RFC 9421,

data/lib/linzer/jws.rb

@@ -3,8 +3,18 @@
 require "jwt"
 require "jwt/eddsa"
 require "ed25519"
-require "digest"
-require "base64"
+
+# jwt-eddsa isn't a runtime dependency of this gemspec, callers who want
+# JWS/EdDSA support add it to their own Gemfile. jwt-eddsa <= 0.9.0 has a
+# bug where its OKP JWK class computes thumbprints over the wrong members
+# (see Linzer::JWS::Key#jwk_thumbprint, which delegates to it), so guard
+# against a too-old version actually being resolved instead of silently
+# producing wrong keyids.
+if Gem::Version.new(JWT::EdDSA::VERSION) < Gem::Version.new("1.0")
+  raise Linzer::Error,
+    "linzer requires jwt-eddsa >= 1.0 (found #{JWT::EdDSA::VERSION}); " \
+    "versions <= 0.9.0 compute OKP JWK thumbprints incorrectly"
+end
 
 module Linzer
   # JSON Web Signature (JWS) compatible key support.
@@ -106,35 +116,19 @@ module Linzer
       # Computes the RFC 7638 JWK SHA-256 Thumbprint for this key's public
       # material.
       #
-      # This is computed directly from the exported JWK rather than
-      # delegating to the underlying jwt-eddsa gem's own thumbprint/kid
-      # generation: jwt-eddsa (<= 0.9.0) has a bug where its OKP JWK class
-      # computes that value over the wrong members (an RSA-shaped {kty, n,
-      # x} instead of the RFC 8037-correct {crv, kty, x}), which silently
-      # produces a keyid that a spec-compliant verifier will reject.
-      #
       # @return [String] base64url-encoded (no padding) SHA-256 thumbprint
       # @raise [Error] if this key's JWK "kty" is not supported
       #
       # @see https://www.rfc-editor.org/rfc/rfc7638 RFC 7638 - JSON Web Key (JWK) Thumbprint
       # @see https://www.rfc-editor.org/rfc/rfc8037 RFC 8037 - EdDSA for JWS/JWK
       def jwk_thumbprint
-        # XXX: drop this method custom implementation and just
-        # return material.key_digest
-        # once https://github.com/jwt/ruby-jwt-eddsa/pull/26 is resolved
-        #
         exported = material.export
 
-        members =
-          case exported[:kty]
-          when "OKP"
-            {crv: exported[:crv], kty: exported[:kty], x: exported[:x]}
-          else
-            raise Error, "Unsupported JWK kty for thumbprint: #{exported[:kty]}"
-          end
+        if exported[:kty] != "OKP"
+          raise Error, "Unsupported JWK kty for thumbprint: #{exported[:kty]}"
+        end
 
-        digest = Digest::SHA256.digest(JWT::JSON.generate(members))
-        Base64.urlsafe_encode64(digest, padding: false)
+        material.key_digest
       end
 
       private

data/lib/linzer/key/helper.rb

@@ -349,17 +349,21 @@ module Linzer
           ensure_ml_dsa_gem_key_available!
           generate_ml_dsa_key_via_gem(algorithm, key_id)
         end
+      rescue OpenSSL::PKey::PKeyError, OpenSSL::ASN1::ASN1Error => e
+        raise Linzer::Error, e.message, cause: e
       end
 
       def new_ml_dsa_key(material, algorithm, key_id, backend)
         case resolve_ml_dsa_backend(algorithm, backend)
         when :openssl
-          key = Linzer::MLDSA.deserialize_raw_or_encoded_key(material, algorithm)
+          key = Linzer::MLDSA::OpenSSLKey.deserialize_raw_or_encoded_key(material, algorithm)
           Linzer::MLDSA::OpenSSLKey.new(key, id: key_id, algorithm: algorithm)
         when :ml_dsa
           ensure_ml_dsa_gem_key_available!
           new_ml_dsa_key_via_gem(material, algorithm, key_id)
         end
+      rescue OpenSSL::PKey::PKeyError, OpenSSL::ASN1::ASN1Error, TypeError => e
+        raise Linzer::Error, e.message, cause: e
       end
 
       # NOTE: ensure_ml_dsa_gem_key_available! must run in the caller, not
@@ -413,13 +417,15 @@ module Linzer
       end
 
       # @raise [Error] If Linzer::MLDSA::GemKey isn't loaded (the ml_dsa
-      #   gem backend is opt-in, see lib/linzer/ml_dsa/gem_key.rb)
+      #   gem backend is opt-in via `require "linzer/ml_dsa"`, see
+      #   lib/linzer/ml_dsa.rb)
       def ensure_ml_dsa_gem_key_available!
         return if defined?(Linzer::MLDSA::GemKey)
 
         raise Linzer::Error,
           "ML-DSA gem backend not available: " \
-          'require "linzer/ml_dsa/gem_key" first'
+          'require "linzer/ml_dsa" first (needs the ml_dsa gem installed; ' \
+          'plain require "linzer" only gets you the OpenSSL backend)'
       end
 
       def deserialize_ml_dsa_key(material, parameter_set)

data/lib/linzer/ml_dsa/gem_key.rb

@@ -20,7 +20,7 @@ module Linzer
     # Supports all three FIPS 204 parameter sets. Optional: not required
     # by `linzer.rb` itself, and not a runtime dependency of the gemspec,
     # callers who want this backend must add `ml_dsa` to their own
-    # Gemfile and `require "linzer/ml_dsa/gem_key"` themselves, which
+    # Gemfile and `require "linzer/ml_dsa"` themselves, which
     # requires `ml_dsa` in turn.
     #
     # @see Linzer::MLDSA::OpenSSLKey for the dependency-free alternative

data/lib/linzer/ml_dsa/openssl_key.rb

@@ -2,19 +2,6 @@
 
 module Linzer
   module MLDSA
-    # NIST OIDs for ML-DSA (id-ml-dsa-44/65/87), used both by OpenSSL's own
-    # PEM/DER encoding and by {wrap_raw_public_key}/{wrap_raw_private_key}
-    # below when reconstructing a key from raw FIPS 204 bytes. Verified
-    # against real OpenSSL 3.5+ output (decoded from a freshly generated
-    # key's own `public_to_der`), not taken from documentation alone.
-    # @return [Hash{String => String}]
-    OPENSSL_OIDS = {
-      "ml-dsa-44" => "2.16.840.1.101.3.4.3.17",
-      "ml-dsa-65" => "2.16.840.1.101.3.4.3.18",
-      "ml-dsa-87" => "2.16.840.1.101.3.4.3.19"
-    }.freeze
-    private_constant :OPENSSL_OIDS
-
     # Linzer algorithm identifiers (lowercase, e.g. "ml-dsa-44") that this
     # OpenSSL-backed implementation actually has construction/OID support
     # for today. {openssl_supported?} treats anything outside this set as
@@ -23,26 +10,6 @@ module Linzer
     IMPLEMENTED_ALGORITHMS = %w[ml-dsa-44 ml-dsa-65 ml-dsa-87].freeze
     private_constant :IMPLEMENTED_ALGORITHMS
 
-    # FIPS 204 raw public-key sizes per parameter set, used to sniff raw
-    # key material in {deserialize_raw_or_encoded_key} the same way
-    # {GemKey} does for the gem backend.
-    # @return [Hash{String => Integer}]
-    RAW_PUBLIC_KEY_BYTES = {
-      "ml-dsa-44" => 1312,
-      "ml-dsa-65" => 1952,
-      "ml-dsa-87" => 2592
-    }.freeze
-    private_constant :RAW_PUBLIC_KEY_BYTES
-
-    # FIPS 204 raw (expanded, seed-free) private-key sizes per parameter set.
-    # @return [Hash{String => Integer}]
-    RAW_PRIVATE_KEY_BYTES = {
-      "ml-dsa-44" => 2560,
-      "ml-dsa-65" => 4032,
-      "ml-dsa-87" => 4896
-    }.freeze
-    private_constant :RAW_PRIVATE_KEY_BYTES
-
     # ML-DSA (FIPS 204) signing/verification backed directly by OpenSSL
     # 3.5+, with no additional gem dependency. Supports all three
     # parameter sets (ML-DSA-44/65/87).
@@ -61,6 +28,39 @@ module Linzer
     #   C2SP httpsig-pq: Post-Quantum Algorithms for HTTP Message Signatures
     # @see https://csrc.nist.gov/pubs/fips/204/final FIPS 204
     class OpenSSLKey < Linzer::Key
+      # NIST OIDs for ML-DSA (id-ml-dsa-44/65/87), used both by OpenSSL's own
+      # PEM/DER encoding and by {wrap_raw_public_key}/{wrap_raw_private_key}
+      # below when reconstructing a key from raw FIPS 204 bytes. Verified
+      # against real OpenSSL 3.5+ output (decoded from a freshly generated
+      # key's own `public_to_der`), not taken from documentation alone.
+      # @return [Hash{String => String}]
+      OPENSSL_OIDS = {
+        "ml-dsa-44" => "2.16.840.1.101.3.4.3.17",
+        "ml-dsa-65" => "2.16.840.1.101.3.4.3.18",
+        "ml-dsa-87" => "2.16.840.1.101.3.4.3.19"
+      }.freeze
+      private_constant :OPENSSL_OIDS
+
+      # FIPS 204 raw public-key sizes per parameter set, used to sniff raw
+      # key material in {deserialize_raw_or_encoded_key} the same way
+      # {GemKey} does for the gem backend.
+      # @return [Hash{String => Integer}]
+      RAW_PUBLIC_KEY_BYTES = {
+        "ml-dsa-44" => 1312,
+        "ml-dsa-65" => 1952,
+        "ml-dsa-87" => 2592
+      }.freeze
+      private_constant :RAW_PUBLIC_KEY_BYTES
+
+      # FIPS 204 raw (expanded, seed-free) private-key sizes per parameter set.
+      # @return [Hash{String => Integer}]
+      RAW_PRIVATE_KEY_BYTES = {
+        "ml-dsa-44" => 2560,
+        "ml-dsa-65" => 4032,
+        "ml-dsa-87" => 4896
+      }.freeze
+      private_constant :RAW_PRIVATE_KEY_BYTES
+
       # @return [String] The FIPS 204 parameter set this key was
       #   constructed for, e.g. `"ml-dsa-44"`
       attr_reader :algorithm
@@ -92,10 +92,13 @@ module Linzer
       #
       # @param data [String] The data to sign (typically the signature base)
       # @return [String] The FIPS 204 signature
-      # @raise [SigningError] If this key does not contain private key material
+      # @raise [SigningError] If this key does not contain private key
+      #   material, or the underlying OpenSSL signing operation fails
       def sign(data)
         validate_signing_key
         material.sign(nil, data)
+      rescue OpenSSL::PKey::PKeyError => e
+        raise SigningError, e.message, cause: e
       end
 
       # Verifies a signature using the ML-DSA public key.
@@ -103,10 +106,16 @@ module Linzer
       # @param signature [String] The signature bytes to verify
       # @param data [String] The data that was signed
       # @return [Boolean] true if the signature is valid, false otherwise
+      #   (including malformed or non-String `signature`/`data` input,
+      #   matching {Linzer::MLDSA::GemKey#verify}'s contract)
       # @raise [VerifyError] If this key does not contain public key material
       def verify(signature, data)
         validate_verify_key
+        return false unless signature.is_a?(String)
+
         material.verify(nil, signature, data)
+      rescue OpenSSL::PKey::PKeyError, ArgumentError, TypeError
+        false
       end
 
       # @return [Symbol] :openssl -- which backend produced this key
@@ -114,14 +123,137 @@ module Linzer
         :openssl
       end
 
+      class << self
+        # Builds an OpenSSL key from ML-DSA material of unknown shape: raw
+        # FIPS 204 bytes for `algorithm` (sniffed by exact byte length, the
+        # same approach {Linzer::MLDSA::GemKey} uses for the gem backend) or
+        # an OpenSSL-encoded PEM/DER key, handled as a fallback. Sniffing is
+        # scoped to `algorithm`'s own raw sizes, not all three parameter
+        # sets' sizes at once, material sized for a *different* parameter
+        # set than requested falls through to the `OpenSSL::PKey.read`
+        # fallback and fails there (raw bytes aren't valid PEM/DER), rather
+        # than silently being accepted and mislabeled.
+        #
+        # @param material [String] Raw FIPS 204 bytes, or a PEM/DER-encoded key
+        # @param algorithm [String] Linzer's lowercase algorithm identifier,
+        #   e.g. `"ml-dsa-44"`
+        # @return [OpenSSL::PKey::PKey]
+        # @raise [TypeError] If `material` isn't a String
+        # @api private
+        def deserialize_raw_or_encoded_key(material, algorithm)
+          raise TypeError, "ML-DSA key material must be a String" unless material.is_a?(String)
+
+          case material.bytesize
+          when RAW_PUBLIC_KEY_BYTES.fetch(algorithm)
+            wrap_raw_public_key(material, algorithm)
+          when RAW_PRIVATE_KEY_BYTES.fetch(algorithm)
+            wrap_raw_private_key(material, algorithm)
+          else
+            OpenSSL::PKey.read(material)
+          end
+        end
+
+        # Extracts the raw FIPS 204 public key bytes from an OpenSSL key's
+        # own SubjectPublicKeyInfo encoding -- the inverse of
+        # {wrap_raw_public_key}. Used to hand a key generated (or loaded)
+        # via this backend to the `ml_dsa` gem backend instead.
+        #
+        # @param key [OpenSSL::PKey::PKey] A public or private ML-DSA key
+        # @return [String] Raw FIPS 204 public key bytes
+        # @api private
+        def unwrap_raw_public_key(key)
+          spki = OpenSSL::ASN1.decode(key.public_to_der)
+          spki.value[1].value
+        end
+
+        # Extracts the raw (expanded, seed-free) FIPS 204 private key bytes
+        # from an OpenSSL key's own PKCS8 encoding -- the inverse of
+        # {wrap_raw_private_key}. Used to hand a key generated via this
+        # backend to the `ml_dsa` gem backend instead.
+        #
+        # OpenSSL's own generated keys always use the "both" alternative of
+        # the ML-DSA private key CHOICE (a seed alongside the expanded key,
+        # confirmed empirically -- see the strategy notes), so this only
+        # handles that shape; anything else raises rather than silently
+        # returning the wrong bytes.
+        #
+        # @param key [OpenSSL::PKey::PKey] A private ML-DSA key
+        # @return [String] Raw FIPS 204 expanded private key bytes
+        # @raise [Error] If the key's private key CHOICE isn't the expected
+        #   seed+expandedKey SEQUENCE
+        # @api private
+        def unwrap_raw_private_key(key)
+          one_asymmetric_key = OpenSSL::ASN1.decode(key.private_to_der)
+          private_key_choice = OpenSSL::ASN1.decode(one_asymmetric_key.value[2].value)
+          unless private_key_choice.is_a?(OpenSSL::ASN1::Sequence)
+            raise Error, "Unsupported ML-DSA private key encoding (expected seed+expandedKey)"
+          end
+
+          private_key_choice.value[1].value
+        end
+
+        private
+
+        # Reconstructs an OpenSSL key from a raw FIPS 204 ML-DSA public key.
+        #
+        # The `openssl` gem does not yet accept ML-DSA algorithm names in
+        # {OpenSSL::PKey.new_raw_public_key} (there is no upstream issue
+        # tracking this as of this writing), so this wraps the raw bytes in a
+        # minimal DER SubjectPublicKeyInfo structure that {OpenSSL::PKey.read}
+        # does accept. Verified byte-identical to OpenSSL's own
+        # `public_to_der` output for ml-dsa-44; for ml-dsa-65/87, verified
+        # via a full raw-bytes-in/sign/verify round trip instead (a
+        # byte-level mismatch would fail that too). Tested against OpenSSL 3.5+
+        # in both cases.
+        #
+        # @param raw_public_key [String] Raw FIPS 204 public key bytes
+        # @param algorithm [String] Linzer's lowercase algorithm identifier
+        # @return [OpenSSL::PKey::PKey]
+        def wrap_raw_public_key(raw_public_key, algorithm)
+          spki = OpenSSL::ASN1::Sequence.new([
+            ml_dsa_algorithm_identifier(algorithm),
+            OpenSSL::ASN1::BitString.new(raw_public_key)
+          ])
+          OpenSSL::PKey.read(spki.to_der)
+        end
+
+        # Builds an OpenSSL key from a raw FIPS 204 ML-DSA private key.
+        #
+        # {OpenSSL::PKey.new_raw_private_key} doesn't accept ML-DSA algorithm
+        # names yet, and unlike the public key, a fixed DER prefix won't work
+        # here: OpenSSL's PKCS8 encoding embeds a per-key 32-byte seed
+        # alongside the expanded key. This builds the seed-free "expandedKey"
+        # alternative of the ML-DSA private key CHOICE instead (an untagged
+        # OCTET STRING), which carries no per-key data.
+        #
+        # @param raw_private_key [String] Raw FIPS 204 private key bytes
+        # @param algorithm [String] Linzer's lowercase algorithm identifier
+        # @return [OpenSSL::PKey::PKey]
+        def wrap_raw_private_key(raw_private_key, algorithm)
+          expanded_key_choice = OpenSSL::ASN1::OctetString.new(raw_private_key).to_der
+          one_asymmetric_key = OpenSSL::ASN1::Sequence.new([
+            OpenSSL::ASN1::Integer(0),
+            ml_dsa_algorithm_identifier(algorithm),
+            OpenSSL::ASN1::OctetString.new(expanded_key_choice)
+          ])
+          OpenSSL::PKey.read(one_asymmetric_key.to_der)
+        end
+
+        # @param algorithm [String] Linzer's lowercase algorithm identifier
+        # @return [OpenSSL::ASN1::Sequence] the ML-DSA AlgorithmIdentifier
+        def ml_dsa_algorithm_identifier(algorithm)
+          OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::ObjectId(OPENSSL_OIDS.fetch(algorithm))])
+        end
+      end
+
       private
 
       # Cross-checks the underlying OpenSSL key material against the
       # claimed {algorithm}. Only actually able to catch a mismatch when
       # `material` came in as PEM/DER (via {OpenSSL::PKey.read}) for a
       # *different* ML-DSA parameter set than requested, material built
-      # via {Linzer::MLDSA.deserialize_raw_or_encoded_key}'s raw-byte path
-      # or `OpenSSL::PKey.generate_key(algorithm.upcase)` is already
+      # via {deserialize_raw_or_encoded_key}'s raw-byte path or
+      # `OpenSSL::PKey.generate_key(algorithm.upcase)` is already
       # guaranteed consistent by construction, so this is a no-op for
       # those (cheap: `public_to_der` on an already-parsed key, no network
       # or extra crypto). Best-effort: if the material's own OID can't be
@@ -176,6 +308,11 @@ module Linzer
       # free. Unknown or not-yet-implemented algorithm identifiers return
       # `false` rather than raising.
       #
+      # Kept at the {Linzer::MLDSA} module level, not under {OpenSSLKey},
+      # since it's a backend-selection capability probe used to decide
+      # *whether* to construct an {OpenSSLKey} at all, not a detail of an
+      # already-chosen OpenSSL backend.
+      #
       # @param algorithm [String] Linzer's lowercase algorithm identifier,
       #   e.g. `"ml-dsa-44"`
       # @return [Boolean]
@@ -195,85 +332,6 @@ module Linzer
             false
           end
       end
-
-      # Builds an OpenSSL key from ML-DSA material of unknown shape: raw
-      # FIPS 204 bytes for `algorithm` (sniffed by exact byte length, the
-      # same approach {Linzer::MLDSA::GemKey} uses for the gem backend) or
-      # an OpenSSL-encoded PEM/DER key, handled as a fallback. Sniffing is
-      # scoped to `algorithm`'s own raw sizes, not all three parameter
-      # sets' sizes at once, material sized for a *different* parameter
-      # set than requested falls through to the `OpenSSL::PKey.read`
-      # fallback and fails there (raw bytes aren't valid PEM/DER), rather
-      # than silently being accepted and mislabeled.
-      #
-      # @param material [String] Raw FIPS 204 bytes, or a PEM/DER-encoded key
-      # @param algorithm [String] Linzer's lowercase algorithm identifier,
-      #   e.g. `"ml-dsa-44"`
-      # @return [OpenSSL::PKey::PKey]
-      # @api private
-      def deserialize_raw_or_encoded_key(material, algorithm)
-        case material.bytesize
-        when RAW_PUBLIC_KEY_BYTES.fetch(algorithm)
-          wrap_raw_public_key(material, algorithm)
-        when RAW_PRIVATE_KEY_BYTES.fetch(algorithm)
-          wrap_raw_private_key(material, algorithm)
-        else
-          OpenSSL::PKey.read(material)
-        end
-      end
-
-      private
-
-      # Reconstructs an OpenSSL key from a raw FIPS 204 ML-DSA public key.
-      #
-      # The `openssl` gem does not yet accept ML-DSA algorithm names in
-      # {OpenSSL::PKey.new_raw_public_key} (there is no upstream issue
-      # tracking this as of this writing), so this wraps the raw bytes in a
-      # minimal DER SubjectPublicKeyInfo structure that {OpenSSL::PKey.read}
-      # does accept. Verified byte-identical to OpenSSL's own
-      # `public_to_der` output for ml-dsa-44; for ml-dsa-65/87, verified
-      # via a full raw-bytes-in/sign/verify round trip instead (a
-      # byte-level mismatch would fail that too). Tested against OpenSSL 3.5+
-      # in both cases.
-      #
-      # @param raw_public_key [String] Raw FIPS 204 public key bytes
-      # @param algorithm [String] Linzer's lowercase algorithm identifier
-      # @return [OpenSSL::PKey::PKey]
-      def wrap_raw_public_key(raw_public_key, algorithm)
-        spki = OpenSSL::ASN1::Sequence.new([
-          ml_dsa_algorithm_identifier(algorithm),
-          OpenSSL::ASN1::BitString.new(raw_public_key)
-        ])
-        OpenSSL::PKey.read(spki.to_der)
-      end
-
-      # Builds an OpenSSL key from a raw FIPS 204 ML-DSA private key.
-      #
-      # {OpenSSL::PKey.new_raw_private_key} doesn't accept ML-DSA algorithm
-      # names yet, and unlike the public key, a fixed DER prefix won't work
-      # here: OpenSSL's PKCS8 encoding embeds a per-key 32-byte seed
-      # alongside the expanded key. This builds the seed-free "expandedKey"
-      # alternative of the ML-DSA private key CHOICE instead (an untagged
-      # OCTET STRING), which carries no per-key data.
-      #
-      # @param raw_private_key [String] Raw FIPS 204 private key bytes
-      # @param algorithm [String] Linzer's lowercase algorithm identifier
-      # @return [OpenSSL::PKey::PKey]
-      def wrap_raw_private_key(raw_private_key, algorithm)
-        expanded_key_choice = OpenSSL::ASN1::OctetString.new(raw_private_key).to_der
-        one_asymmetric_key = OpenSSL::ASN1::Sequence.new([
-          OpenSSL::ASN1::Integer(0),
-          ml_dsa_algorithm_identifier(algorithm),
-          OpenSSL::ASN1::OctetString.new(expanded_key_choice)
-        ])
-        OpenSSL::PKey.read(one_asymmetric_key.to_der)
-      end
-
-      # @param algorithm [String] Linzer's lowercase algorithm identifier
-      # @return [OpenSSL::ASN1::Sequence] the ML-DSA AlgorithmIdentifier
-      def ml_dsa_algorithm_identifier(algorithm)
-        OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::ObjectId(OPENSSL_OIDS.fetch(algorithm))])
-      end
     end
   end
 end

data/lib/linzer/ml_dsa.rb

@@ -1,18 +1,27 @@
 # frozen_string_literal: true
 
 require_relative "ml_dsa/openssl_key"
+require_relative "ml_dsa/gem_key"
 
 module Linzer
-  # ML-DSA support for HTTP Message Signatures as specified by https://c2sp.org/httpsig-pq
+  # ML-DSA support for HTTP Message Signatures as specified by
+  # https://c2sp.org/httpsig-pq
   #
   # Two independent backends live under this namespace, both supporting
   # all three FIPS 204 parameter sets (ML-DSA-44/65/87):
   #
   # - {Linzer::MLDSA::OpenSSLKey} -- backed directly by OpenSSL 3.5+, no
-  #   extra gem dependency. Always loaded by this file.
-  # - {Linzer::MLDSA::GemKey} -- backed by the `ml_dsa` gem. Optional:
-  #   `require "linzer/ml_dsa/gem_key"` yourself to use it (which
-  #   requires `ml_dsa` in turn).
+  #   extra gem dependency.
+  # - {Linzer::MLDSA::GemKey} -- backed by the `ml_dsa` gem.
+  #
+  # `require "linzer"` alone already gets you OpenSSLKey for free when the
+  # running OpenSSL build supports it, that's the safe default, and this
+  # file plays no part in it (lib/linzer.rb requires ml_dsa/openssl_key
+  # directly). `require "linzer/ml_dsa"` is the explicit opt-in for
+  # everything else: it also loads GemKey, which in turn requires the
+  # `ml_dsa` gem to be installed. Reach for it when your OpenSSL build is
+  # too old for ML-DSA, or you specifically want the gem-backed
+  # implementation.
   #
   # `Linzer.generate_ml_dsa_*_key`/`Linzer.new_ml_dsa_*_key` dispatch
   # between them via a `backend:` keyword (:auto, :openssl, or :ml_dsa),

data/lib/linzer/version.rb

@@ -3,5 +3,5 @@
 module Linzer
   # Current version of the Linzer gem.
   # @return [String]
-  VERSION = "0.8.1.beta2"
+  VERSION = "0.8.1"
 end

data/lib/linzer.rb

@@ -26,7 +26,7 @@ require_relative "linzer/rsa_pss"
 require_relative "linzer/hmac"
 require_relative "linzer/ed25519"
 require_relative "linzer/ecdsa"
-require_relative "linzer/ml_dsa"
+require_relative "linzer/ml_dsa/openssl_key"
 require_relative "linzer/key/helper"
 require_relative "linzer/signer"
 require_relative "linzer/verifier"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: linzer
 version: !ruby/object:Gem::Version
-  version: 0.8.1.beta2
+  version: 0.8.1
 platform: ruby
 authors:
 - Miguel Landaeta
@@ -194,7 +194,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.2
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="