linzer 0.8.1.beta1 → 0.8.1.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ced6e7bed237dbb28cefa79ed9289fa19db7510a7078c64315f92d50ae637b7d
-  data.tar.gz: 291d1e92359fba0801ad5dfa543e6eb132c43c1f94686be5749462fcf3e18f2e
+  metadata.gz: 1bc1cb6232547c649f0c082b444d858632abcb7cd923a50c1bf55ea6da316034
+  data.tar.gz: 97da42478725e85ab12f9475f2808350dc76981c3f705a8e1479c57b7509f095
 SHA512:
-  metadata.gz: 968bac61643099b34b73696193f8b5af9ab4489393b7d3d67d4f3fe70c35509c61e48acd659d4e78f101a8fabd7be65b549e87e6376bbaa146ff6cb755b894a8
-  data.tar.gz: d901254dd56d886b96b8e4c6425958e63b97841f2682958cb1fd2b020b2799f2a81c15609f74aa8790f80692756d2647f9359f45729ac15f2ca1eaf1e20b0699
+  metadata.gz: 537e717e95afee1f2c32534ef294608020869b59aa4b07abdc58a629df11c74878390d0f0fa6202bbb7adf913ee70defde827f6f4c8e3c5d50d60c5fd159a1fe
+  data.tar.gz: 55337d62a400418a8b46bbd240a588e0fa6d66aef18df4c10938b0715919f8b236fb985a3ab0a082cb7fc10f13b27051f261daecf48a469b33ff11c5d7a19b7f

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [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,45 @@ 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/gem_key"
+
+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.
+
+### 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

@@ -3,6 +3,8 @@
 require "jwt"
 require "jwt/eddsa"
 require "ed25519"
+require "digest"
+require "base64"
 
 module Linzer
   # JSON Web Signature (JWS) compatible key support.
@@ -101,6 +103,40 @@ 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.
+      #
+      # 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
+
+        digest = Digest::SHA256.digest(JWT::JSON.generate(members))
+        Base64.urlsafe_encode64(digest, padding: false)
+      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,88 @@ 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
+      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)
+          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
+      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, see lib/linzer/ml_dsa/gem_key.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'
+      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/gem_key"` 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,279 @@
+# frozen_string_literal: true
+
+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
+    # 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
+
+    # 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).
+    #
+    # 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
+      # @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
+      def sign(data)
+        validate_signing_key
+        material.sign(nil, data)
+      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
+      # @raise [VerifyError] If this key does not contain public key material
+      def verify(signature, data)
+        validate_verify_key
+        material.verify(nil, signature, data)
+      end
+
+      # @return [Symbol] :openssl -- which backend produced this key
+      def backend
+        :openssl
+      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
+      # 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.
+      #
+      # @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
+
+      # 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,102 +1,25 @@
 # frozen_string_literal: true
 
+require_relative "ml_dsa/openssl_key"
+
 module Linzer
   # 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).
+  #
+  # `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.beta2"
 end

data/lib/linzer.rb

@@ -2,7 +2,6 @@
 
 require "starry"
 require "openssl"
-require "ml_dsa"
 require "uri"
 require "net/http"
 

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.beta2
 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