linzer 0.8.1.beta1 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ced6e7bed237dbb28cefa79ed9289fa19db7510a7078c64315f92d50ae637b7d
-  data.tar.gz: 291d1e92359fba0801ad5dfa543e6eb132c43c1f94686be5749462fcf3e18f2e
+  metadata.gz: 188e4a68a86287824bb5ba37a0c1b476abb9bd20b7b96048f13f230c070bab08
+  data.tar.gz: dc3e0081f6baaaf85d30e532fe7c5cf0bf1cb1e7b566dd8493701b754fabdfa3
 SHA512:
-  metadata.gz: 968bac61643099b34b73696193f8b5af9ab4489393b7d3d67d4f3fe70c35509c61e48acd659d4e78f101a8fabd7be65b549e87e6376bbaa146ff6cb755b894a8
-  data.tar.gz: d901254dd56d886b96b8e4c6425958e63b97841f2682958cb1fd2b020b2799f2a81c15609f74aa8790f80692756d2647f9359f45729ac15f2ca1eaf1e20b0699
+  metadata.gz: 2af5b16fa7832bce168d2fa024dbbe28adfff00d126b520c87e241348eb34f9f1133fd98a85ca3fec6cfd945f773165e0cfe3230420e086a91f1f59fa4eb67b8
+  data.tar.gz: 386f5fb8bfe0ddea3d045c66ed52d52a9dab9704c79662ada309027185b67cf0cd6887e5c4becaa64a8410c1aa4419c2274c6739d29743d74d9854da79f3e4c8

data/CHANGELOG.md

@@ -1,5 +1,82 @@
 ## [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
+  `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).
+
+- The `ml_dsa` gem is no longer a hard runtime dependency, it's an
+  optional backend now, a real behavior change from beta1. To keep
+  using it (e.g. on older OpenSSL builds, or explicitly via
+  `backend: :ml_dsa`), add it to your own Gemfile and
+  `require "linzer/ml_dsa/gem_key"` before use.
+
 ## [0.8.1.beta1] - 2026-08-08
 
 - Add ML-DSA-44, ML-DSA-65, and ML-DSA-87 support following the C2SP

data/README.md

@@ -556,6 +556,53 @@ Linzer currently supports the following signature algorithms:
 - ECDSA (P-256 and P-384 curves).
 - ML-DSA-44, ML-DSA-65, and ML-DSA-87 ([C2SP profile](https://c2sp.org/httpsig-pq))
 
+### ML-DSA
+
+ML-DSA (FIPS 204, post-quantum) is backed by two interchangeable
+implementations. By default, Linzer uses OpenSSL 3.5+'s native ML-DSA
+support when available, with no extra dependency:
+
+```ruby
+key = Linzer.generate_ml_dsa_44_key # or _65_key / _87_key
+# => #<Linzer::MLDSA::OpenSSLKey:0x00000fe13e9bd208
+# or load an existing key with:
+# key = Linzer.new_ml_dsa_44_key(IO.read("key"), "mykeyid")
+
+key.backend # => :openssl, or :ml_dsa if this build fell back to it
+```
+
+Older OpenSSL builds aren't the only reason to reach for it: even on a fully
+capable build, you can opt into the [`ml_dsa`](https://rubygems.org/gems/ml_dsa)
+gem (a C extension bundling the PQClean implementation) explicitly via
+`backend: :ml_dsa`, for example, if you'd rather not depend on OpenSSL's ML-DSA
+support for a given deployment. Either way, you need to add the gem to your own
+Gemfile:
+
+```ruby
+# Gemfile
+gem "ml_dsa"
+```
+
+```ruby
+require "linzer/ml_dsa"
+
+key = Linzer.generate_ml_dsa_44_key
+```
+
+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,
 only Ed25519 is currently supported. Support for additional
 algorithms is planned and should be straightforward to add.

data/lib/linzer/helper.rb

@@ -60,7 +60,7 @@ module Linzer
       ctx = Signature::Context.new(
         message:    Message.new(request_or_response),
         key:        key,
-        label:      label,
+        label:      label || Signer::DEFAULT_LABEL,
         components: Array(components),
         params:     Hash(params)
       )

data/lib/linzer/jws.rb

@@ -4,6 +4,18 @@ require "jwt"
 require "jwt/eddsa"
 require "ed25519"
 
+# 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.
   #
@@ -101,6 +113,24 @@ module Linzer
         algo.verify(data: data, signature: signature, verification_key: verify_key)
       end
 
+      # Computes the RFC 7638 JWK SHA-256 Thumbprint for this key's public
+      # material.
+      #
+      # @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
+        exported = material.export
+
+        if exported[:kty] != "OKP"
+          raise Error, "Unsupported JWK kty for thumbprint: #{exported[:kty]}"
+        end
+
+        material.key_digest
+      end
+
       private
 
       # @return [Boolean] true if this key can verify signatures

data/lib/linzer/key/helper.rb

@@ -244,53 +244,69 @@ module Linzer
       # Generates an ML-DSA-44 key pair.
       #
       # @param key_id [String, nil] Optional key identifier
-      # @return [MLDSA::Key] A new ML-DSA-44 key pair
+      # @param backend [Symbol] :auto (default, prefers OpenSSL when this
+      #   build supports it, see {Linzer::MLDSA.openssl_supported?}
+      #   falling back to the ml_dsa gem otherwise), :openssl, or :ml_dsa
+      # @return [MLDSA::OpenSSLKey, MLDSA::GemKey] A new ML-DSA-44 key pair
+      # @raise [Error] If the requested backend can't actually be used
       # @see https://c2sp.org/httpsig-pq C2SP post-quantum HTTP signatures
-      def generate_ml_dsa_44_key(key_id = nil)
-        generate_ml_dsa_key("ml-dsa-44", key_id)
+      def generate_ml_dsa_44_key(key_id = nil, backend: :auto)
+        generate_ml_dsa_key("ml-dsa-44", key_id, backend)
       end
 
       # Generates an ML-DSA-65 key pair.
       #
       # @param key_id [String, nil] Optional key identifier
-      # @return [MLDSA::Key] A new ML-DSA-65 key pair
-      def generate_ml_dsa_65_key(key_id = nil)
-        generate_ml_dsa_key("ml-dsa-65", key_id)
+      # @param backend [Symbol] :auto, :openssl, or :ml_dsa, see
+      #   {#generate_ml_dsa_44_key}
+      # @return [MLDSA::OpenSSLKey, MLDSA::GemKey] A new ML-DSA-65 key pair
+      # @raise [Error] If the requested backend can't actually be used
+      def generate_ml_dsa_65_key(key_id = nil, backend: :auto)
+        generate_ml_dsa_key("ml-dsa-65", key_id, backend)
       end
 
       # Generates an ML-DSA-87 key pair.
       #
       # @param key_id [String, nil] Optional key identifier
-      # @return [MLDSA::Key] A new ML-DSA-87 key pair
-      def generate_ml_dsa_87_key(key_id = nil)
-        generate_ml_dsa_key("ml-dsa-87", key_id)
+      # @param backend [Symbol] :auto, :openssl, or :ml_dsa, see
+      #   {#generate_ml_dsa_44_key}
+      # @return [MLDSA::OpenSSLKey, MLDSA::GemKey] A new ML-DSA-87 key pair
+      # @raise [Error] If the requested backend can't actually be used
+      def generate_ml_dsa_87_key(key_id = nil, backend: :auto)
+        generate_ml_dsa_key("ml-dsa-87", key_id, backend)
       end
 
       # Loads a raw, DER, or PEM ML-DSA-44 private or public key.
       #
       # @param material [String, MlDsa::SecretKey, MlDsa::PublicKey] Key material
       # @param key_id [String, nil] Optional key identifier
-      # @return [MLDSA::Key] The loaded key
-      def new_ml_dsa_44_key(material, key_id = nil)
-        new_ml_dsa_key(material, "ml-dsa-44", key_id)
+      # @param backend [Symbol] :auto, :openssl, or :ml_dsa, see
+      #   {#generate_ml_dsa_44_key}
+      # @return [MLDSA::OpenSSLKey, MLDSA::GemKey] The loaded key
+      def new_ml_dsa_44_key(material, key_id = nil, backend: :auto)
+        new_ml_dsa_key(material, "ml-dsa-44", key_id, backend)
       end
 
       # Loads a raw, DER, or PEM ML-DSA-65 private or public key.
       #
       # @param material [String, MlDsa::SecretKey, MlDsa::PublicKey] Key material
       # @param key_id [String, nil] Optional key identifier
-      # @return [MLDSA::Key] The loaded key
-      def new_ml_dsa_65_key(material, key_id = nil)
-        new_ml_dsa_key(material, "ml-dsa-65", key_id)
+      # @param backend [Symbol] :auto, :openssl, or :ml_dsa, see
+      #   {#generate_ml_dsa_44_key}
+      # @return [MLDSA::OpenSSLKey, MLDSA::GemKey] The loaded key
+      def new_ml_dsa_65_key(material, key_id = nil, backend: :auto)
+        new_ml_dsa_key(material, "ml-dsa-65", key_id, backend)
       end
 
       # Loads a raw, DER, or PEM ML-DSA-87 private or public key.
       #
       # @param material [String, MlDsa::SecretKey, MlDsa::PublicKey] Key material
       # @param key_id [String, nil] Optional key identifier
-      # @return [MLDSA::Key] The loaded key
-      def new_ml_dsa_87_key(material, key_id = nil)
-        new_ml_dsa_key(material, "ml-dsa-87", key_id)
+      # @param backend [Symbol] :auto, :openssl, or :ml_dsa, see
+      #   {#generate_ml_dsa_44_key}
+      # @return [MLDSA::OpenSSLKey, MLDSA::GemKey] The loaded key
+      def new_ml_dsa_87_key(material, key_id = nil, backend: :auto)
+        new_ml_dsa_key(material, "ml-dsa-87", key_id, backend)
       end
 
       # Generates a new JWS key for the specified algorithm.
@@ -324,22 +340,94 @@ module Linzer
 
       private
 
-      def generate_ml_dsa_key(algorithm, key_id)
+      def generate_ml_dsa_key(algorithm, key_id, backend)
+        case resolve_ml_dsa_backend(algorithm, backend)
+        when :openssl
+          material = OpenSSL::PKey.generate_key(algorithm.upcase)
+          Linzer::MLDSA::OpenSSLKey.new(material, id: key_id, algorithm: algorithm)
+        when :ml_dsa
+          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::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
+      # here. This method's own `rescue MlDsa::Error` would need MlDsa
+      # to be defined just to evaluate, defeating the guard.
+      def generate_ml_dsa_key_via_gem(algorithm, key_id)
         parameter_set = Linzer::MLDSA::ALGORITHMS.fetch(algorithm)
         pair = MlDsa.keygen(parameter_set)
-        Linzer::MLDSA::Key.new(pair.secret_key, id: key_id, algorithm: algorithm)
+        Linzer::MLDSA::GemKey.new(pair.secret_key, id: key_id, algorithm: algorithm)
       rescue MlDsa::Error, ArgumentError, TypeError => e
         raise Linzer::Error, e.message, cause: e
       end
 
-      def new_ml_dsa_key(material, algorithm, key_id)
+      # NOTE: see generate_ml_dsa_key_via_gem, same reason.
+      def new_ml_dsa_key_via_gem(material, algorithm, key_id)
         parameter_set = Linzer::MLDSA::ALGORITHMS.fetch(algorithm)
         key = deserialize_ml_dsa_key(material, parameter_set)
-        Linzer::MLDSA::Key.new(key, id: key_id, algorithm: algorithm)
+        Linzer::MLDSA::GemKey.new(key, id: key_id, algorithm: algorithm)
       rescue MlDsa::Error, ArgumentError, TypeError => e
         raise Linzer::Error, e.message, cause: e
       end
 
+      # Resolves a `backend:` argument (:auto, :openssl, or :ml_dsa) to the
+      # concrete backend to actually use for a given algorithm.
+      #
+      # :auto trusts Linzer::MLDSA.openssl_supported?(algorithm) completely,
+      # the single source of truth for whether OpenSSL both can and has
+      # been wired up to handle this algorithm. An explicit :openssl request
+      # is held to the same standard: it's rejected up front, with a clear
+      # error, rather than silently attempted for an algorithm OpenSSLKey
+      # doesn't support (e.g. an unimplemented future parameter set, or a
+      # build without ML-DSA enabled).
+      #
+      # @return [Symbol] :openssl or :ml_dsa
+      # @raise [Error] If backend is :openssl but unavailable for algorithm,
+      #   or if backend is anything other than :auto/:openssl/:ml_dsa
+      def resolve_ml_dsa_backend(algorithm, backend)
+        case backend
+        when :auto
+          Linzer::MLDSA.openssl_supported?(algorithm) ? :openssl : :ml_dsa
+        when :openssl
+          unless Linzer::MLDSA.openssl_supported?(algorithm)
+            raise Linzer::Error, "OpenSSL-backed ML-DSA is not available for #{algorithm} on this build"
+          end
+          :openssl
+        when :ml_dsa
+          :ml_dsa
+        else
+          raise Linzer::Error, "Unknown ML-DSA backend: #{backend.inspect} (expected :auto, :openssl, or :ml_dsa)"
+        end
+      end
+
+      # @raise [Error] If Linzer::MLDSA::GemKey isn't loaded (the ml_dsa
+      #   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" 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)
         return material if material.is_a?(MlDsa::PublicKey) || material.is_a?(MlDsa::SecretKey)
         unless material.is_a?(String)

data/lib/linzer/ml_dsa/gem_key.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+begin
+  require "ml_dsa"
+rescue LoadError
+  raise Linzer::Error, "ml_dsa gem must be installed to use this feature."
+end
+
+module Linzer
+  module MLDSA
+    ALGORITHMS = {
+      "ml-dsa-44" => MlDsa::ML_DSA_44,
+      "ml-dsa-65" => MlDsa::ML_DSA_65,
+      "ml-dsa-87" => MlDsa::ML_DSA_87
+    }.freeze
+
+    # ML-DSA signing/verification backed by the `ml_dsa` gem (a C
+    # extension bundling the PQClean implementation).
+    #
+    # 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"` themselves, which
+    # requires `ml_dsa` in turn.
+    #
+    # @see Linzer::MLDSA::OpenSSLKey for the dependency-free alternative
+    #   backed directly by OpenSSL 3.5+, also supporting all three
+    #   parameter sets.
+    class GemKey < Linzer::Key
+      attr_reader :algorithm
+
+      def initialize(material, params = {})
+        @algorithm = String(params.fetch(:algorithm))
+        super
+      end
+
+      # Validates that the HTTP `alg` parameter matches this key's parameter set.
+      #
+      # @param parameters [Hash] HTTP signature parameters
+      # @return [true] If `alg` is absent or matches this key
+      # @raise [VerifyError] If `alg` selects another ML-DSA parameter set
+      def validate_signature_parameters(parameters)
+        supplied_algorithm = parameters["alg"] || parameters[:alg]
+        return true if supplied_algorithm.nil? || supplied_algorithm == algorithm
+
+        raise VerifyError,
+          "Signature algorithm #{supplied_algorithm} does not match key algorithm #{algorithm}"
+      end
+
+      # Signs an RFC 9421 signature base with an empty FIPS 204 context.
+      #
+      # @param data [String] Signature base bytes
+      # @return [String] Raw FIPS 204 signature bytes
+      # @raise [SigningError] If private key material is unavailable
+      def sign(data)
+        validate_signing_key
+        material.sign(data, context: "")
+      rescue MlDsa::Error => e
+        raise SigningError, e.message, cause: e
+      end
+
+      # Verifies an RFC 9421 signature base with an empty FIPS 204 context.
+      #
+      # @param signature [String] Raw FIPS 204 signature bytes
+      # @param data [String] Signature base bytes
+      # @return [Boolean] Whether the signature is valid
+      # @raise [VerifyError] If public key material is unavailable
+      def verify(signature, data)
+        validate_verify_key
+        return false unless signature.is_a?(String)
+        return false unless signature.bytesize == parameter_set.signature_bytes
+
+        verification_material.verify(data, signature, context: "")
+      rescue MlDsa::Error, ArgumentError, TypeError
+        false
+      end
+
+      # @return [Symbol] :ml_dsa -- which backend produced this key
+      def backend
+        :ml_dsa
+      end
+
+      private
+
+      def validate
+        super
+        expected = ALGORITHMS[algorithm]
+        raise Error, "Unsupported ML-DSA algorithm: #{algorithm}" unless expected
+
+        valid_type = material.is_a?(MlDsa::PublicKey) || material.is_a?(MlDsa::SecretKey)
+        raise Error, "Invalid ML-DSA key material" unless valid_type
+
+        return if material.param_set == expected
+
+        raise Error,
+          "ML-DSA key parameter set #{material.param_set} does not match #{algorithm}"
+      end
+
+      def parameter_set
+        ALGORITHMS.fetch(algorithm)
+      end
+
+      def verification_material
+        return material if material.is_a?(MlDsa::PublicKey)
+        return material.public_key if material.public_key
+
+        raise VerifyError, "Public key is needed!"
+      end
+
+      def compute_private?
+        material.is_a?(MlDsa::SecretKey)
+      end
+
+      def compute_public?
+        material.is_a?(MlDsa::PublicKey) ||
+          (material.is_a?(MlDsa::SecretKey) && !material.public_key.nil?)
+      end
+    end
+  end
+end

data/lib/linzer/ml_dsa/openssl_key.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+module Linzer
+  module MLDSA
+    # 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
+    # unsupported without ever asking OpenSSL about it.
+    # @return [Array<String>]
+    IMPLEMENTED_ALGORITHMS = %w[ml-dsa-44 ml-dsa-65 ml-dsa-87].freeze
+    private_constant :IMPLEMENTED_ALGORITHMS
+
+    # 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).
+    #
+    # Like Ed25519, ML-DSA is a "pure"/digest-less signature scheme: the
+    # RFC 9421 signature base is signed directly, with no prehashing.
+    #
+    # @note Requires OpenSSL 3.5+ with ML-DSA signature algorithms enabled.
+    #   Some distributions ship OpenSSL 3.5+ with these disabled by crypto
+    #   policy (see https://github.com/ruby/openssl/issues/1075), so callers
+    #   should be prepared for {OpenSSL::PKey::PKeyError} on unsupported
+    #   builds even when the OpenSSL version alone looks sufficient.
+    #
+    # @see Linzer::MLDSA::GemKey for the `ml_dsa`-gem-backed alternative
+    # @see https://github.com/C2SP/C2SP/blob/httpsig-pq/v0.2.0/httpsig-pq.md
+    #   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
+
+      # @param material [OpenSSL::PKey::PKey] The underlying OpenSSL key
+      # @param params [Hash] Additional key parameters
+      # @option params [String] :algorithm Required. One of
+      #   `"ml-dsa-44"`/`"ml-dsa-65"`/`"ml-dsa-87"`
+      # @option params [String] :id The key identifier (keyid)
+      def initialize(material, params = {})
+        @algorithm = String(params.fetch(:algorithm))
+        super
+      end
+
+      # Validates that the HTTP `alg` parameter matches this key's algorithm.
+      #
+      # @param parameters [Hash] HTTP signature parameters
+      # @return [true] If `alg` is absent or matches this key
+      # @raise [VerifyError] If `alg` selects a different algorithm
+      def validate_signature_parameters(parameters)
+        supplied_algorithm = parameters["alg"] || parameters[:alg]
+        return true if supplied_algorithm.nil? || supplied_algorithm == algorithm
+
+        raise VerifyError,
+          "Signature algorithm #{supplied_algorithm} does not match key algorithm #{algorithm}"
+      end
+
+      # Signs data using the ML-DSA private key.
+      #
+      # @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, 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.
+      #
+      # @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
+      def backend
+        :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 {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
+      # determined at all, doesn't fail the whole key over it, something
+      # downstream (sign/verify) will surface a real problem regardless.
+      # @raise [Error] If key material is nil, or its actual algorithm
+      #   doesn't match {algorithm}
+      def validate
+        super
+        expected_oid = OPENSSL_OIDS.fetch(algorithm) { raise Error, "Unsupported ML-DSA algorithm: #{algorithm}" }
+        actual_oid = material_openssl_oid
+        return if actual_oid.nil? || actual_oid == expected_oid
+
+        raise Error, "ML-DSA key material (#{actual_oid}) does not match algorithm #{algorithm}"
+      end
+
+      # @return [String, nil] The dotted OID of `material`'s own
+      #   AlgorithmIdentifier, or nil if it can't be determined
+      def material_openssl_oid
+        spki = OpenSSL::ASN1.decode(material.public_to_der)
+        spki.value[0].value[0].oid
+      rescue OpenSSL::ASN1::ASN1Error, OpenSSL::PKey::PKeyError
+        nil
+      end
+
+      # @return [Boolean] true if this key contains public key material
+      def compute_public?
+        has_pem_public?
+      end
+
+      # @return [Boolean] true if this key contains private key material
+      def compute_private?
+        has_pem_private?
+      end
+    end
+
+    class << self
+      # Checks whether this OpenSSL build can actually perform ML-DSA
+      # signing/verification for the given algorithm.
+      #
+      # Returns true only when the algorithm is *both* something this
+      # OpenSSL-backed implementation has actually implemented (see
+      # {IMPLEMENTED_ALGORITHMS}) *and* something the underlying OpenSSL
+      # library itself supports. This is needed mostly because a
+      # version-number check alone isn't reliable and some distributions ship
+      # OpenSSL 3.5+ with ML-DSA disabled by crypto policy (see
+      # https://github.com/ruby/openssl/issues/1075), so this actually
+      # attempts a throwaway key generation rather than inspecting
+      # `OpenSSL::OPENSSL_VERSION`.
+      #
+      # Memoized per algorithm after the first check, so repeated calls are
+      # 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]
+      def openssl_supported?(algorithm)
+        cache = (@openssl_supported ||= {})
+        return cache[algorithm] if cache.key?(algorithm)
+
+        cache[algorithm] =
+          if IMPLEMENTED_ALGORITHMS.include?(algorithm)
+            begin
+              OpenSSL::PKey.generate_key(algorithm.upcase)
+              true
+            rescue OpenSSL::PKey::PKeyError
+              false
+            end
+          else
+            false
+          end
+      end
+    end
+  end
+end

data/lib/linzer/ml_dsa.rb

@@ -1,102 +1,34 @@
 # 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.
+  # - {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),
+  # preferring OpenSSL when this build actually supports it.
   #
   # @see https://c2sp.org/httpsig-pq C2SP post-quantum HTTP signatures
   # @see https://csrc.nist.gov/pubs/fips/204/final FIPS 204
   module MLDSA
-    ALGORITHMS = {
-      "ml-dsa-44" => MlDsa::ML_DSA_44,
-      "ml-dsa-65" => MlDsa::ML_DSA_65,
-      "ml-dsa-87" => MlDsa::ML_DSA_87
-    }.freeze
-
-    # An ML-DSA signing or verification key.
-    class Key < Linzer::Key
-      attr_reader :algorithm
-
-      def initialize(material, params = {})
-        @algorithm = String(params.fetch(:algorithm))
-        super
-      end
-
-      # Validates that the HTTP `alg` parameter matches this key's parameter set.
-      #
-      # @param parameters [Hash] HTTP signature parameters
-      # @return [true] If `alg` is absent or matches this key
-      # @raise [VerifyError] If `alg` selects another ML-DSA parameter set
-      def validate_signature_parameters(parameters)
-        supplied_algorithm = parameters["alg"] || parameters[:alg]
-        return true if supplied_algorithm.nil? || supplied_algorithm == algorithm
-
-        raise VerifyError,
-          "Signature algorithm #{supplied_algorithm} does not match key algorithm #{algorithm}"
-      end
-
-      # Signs an RFC 9421 signature base with an empty FIPS 204 context.
-      #
-      # @param data [String] Signature base bytes
-      # @return [String] Raw FIPS 204 signature bytes
-      # @raise [SigningError] If private key material is unavailable
-      def sign(data)
-        validate_signing_key
-        material.sign(data, context: "")
-      rescue MlDsa::Error => e
-        raise SigningError, e.message, cause: e
-      end
-
-      # Verifies an RFC 9421 signature base with an empty FIPS 204 context.
-      #
-      # @param signature [String] Raw FIPS 204 signature bytes
-      # @param data [String] Signature base bytes
-      # @return [Boolean] Whether the signature is valid
-      # @raise [VerifyError] If public key material is unavailable
-      def verify(signature, data)
-        validate_verify_key
-        return false unless signature.is_a?(String)
-        return false unless signature.bytesize == parameter_set.signature_bytes
-
-        verification_material.verify(data, signature, context: "")
-      rescue MlDsa::Error, ArgumentError, TypeError
-        false
-      end
-
-      private
-
-      def validate
-        super
-        expected = ALGORITHMS[algorithm]
-        raise Error, "Unsupported ML-DSA algorithm: #{algorithm}" unless expected
-
-        valid_type = material.is_a?(MlDsa::PublicKey) || material.is_a?(MlDsa::SecretKey)
-        raise Error, "Invalid ML-DSA key material" unless valid_type
-
-        return if material.param_set == expected
-
-        raise Error,
-          "ML-DSA key parameter set #{material.param_set} does not match #{algorithm}"
-      end
-
-      def parameter_set
-        ALGORITHMS.fetch(algorithm)
-      end
-
-      def verification_material
-        return material if material.is_a?(MlDsa::PublicKey)
-        return material.public_key if material.public_key
-
-        raise VerifyError, "Public key is needed!"
-      end
-
-      def compute_private?
-        material.is_a?(MlDsa::SecretKey)
-      end
-
-      def compute_public?
-        material.is_a?(MlDsa::PublicKey) ||
-          (material.is_a?(MlDsa::SecretKey) && !material.public_key.nil?)
-      end
-    end
   end
 end

data/lib/linzer/signature/profile/web_bot_auth.rb

@@ -139,7 +139,7 @@ module Linzer
           #
           params[:expires] ||= Time.now.to_i + 3600
           params[:tag]     ||= "web-bot-auth"
-          params[:keyid]   ||= key.material.key_digest
+          params[:keyid]   ||= key.jwk_thumbprint
         end
 
         # Injects and signs the Signature-Agent header.

data/lib/linzer/version.rb

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

data/lib/linzer.rb

@@ -2,7 +2,6 @@
 
 require "starry"
 require "openssl"
-require "ml_dsa"
 require "uri"
 require "net/http"
 
@@ -27,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.beta1
+  version: 0.8.1
 platform: ruby
 authors:
 - Miguel Landaeta
@@ -23,20 +23,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
-- !ruby/object:Gem::Dependency
-  name: ml_dsa
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: uri
   requirement: !ruby/object:Gem::Requirement
@@ -177,6 +163,8 @@ files:
 - lib/linzer/message/overlay.rb
 - lib/linzer/message/wrapper.rb
 - lib/linzer/ml_dsa.rb
+- lib/linzer/ml_dsa/gem_key.rb
+- lib/linzer/ml_dsa/openssl_key.rb
 - lib/linzer/options.rb
 - lib/linzer/rack.rb
 - lib/linzer/rsa.rb
@@ -206,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:
   - - ">="