http_signature 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e704af788a9d55b85db708db52faef4107d793d289c36a7b8839837c59590841
-  data.tar.gz: 4941ab8b360a30f0e37d9e8de3377a1a83feaac39b995909947846e072e3b0a3
+  metadata.gz: ad920771f621bd3462777e0eb8f9bbdeea23073a2ef2f6a6b7f28bc539ff981c
+  data.tar.gz: 14ad2f375a92b2ee0a98d1d08b8eb4b8c53bf955d6a61074f84c8227de5606e8
 SHA512:
-  metadata.gz: 312862f8f0a06de466c992cf422138b3676b23547f273ee3c0cd1ccc99111ad394f0a60ef6578c4701310dd4a423d8c4a70b1a1c66d11811b7dcac003823e5bc
-  data.tar.gz: 14d1e2b66bfa36e23efd38803d83104648e7bcc18dddadb7ee442ac5abf62a2d5653ca53bf4934255cf6521af84849fa66c5dc2ebba76705e0a2743b85f14838
+  metadata.gz: 07d414681a84629b24484340d72913df7b0611fc8cb637f0e1e5f8d83a6d65e95fb6070ebfd60830ba7b504e4339f7b10c4ec16a1e37f1aa353bdeb00f88ee39
+  data.tar.gz: 5aad2434674f6a8b26e6d30084ea9f06cbc12c4b70c22be4071356431aa30a15924707ff213164800adfc5729cbad32fddbda324e00a6e15bc3259356c568745

data/.github/workflows/ci.yml

@@ -9,13 +9,17 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['3.4', '4.0']
     steps:
       - uses: actions/checkout@v4
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.4'
+          ruby-version: ${{ matrix.ruby-version }}
           bundler-cache: true
 
       - name: Run tests with coverage
@@ -26,7 +30,7 @@ jobs:
       - name: Upload coverage artifact
         uses: actions/upload-artifact@v4
         with:
-          name: coverage-html
+          name: coverage-html-${{ matrix.ruby-version }}
           path: coverage/
           if-no-files-found: warn
 

data/AGENTS.md

@@ -6,3 +6,15 @@ This is a Ruby gem implementing the [HTTP Message Signatures RFC 9421 standard](
 - Run all tests: `bundle exec rake test`
 - Run single test file: `bundle exec rake test TEST=test/http_signature_test.rb`
 - Run single test: `bundle exec rake test TEST=test/http_signature_test.rb TESTOPTS="--name=/test_rsa_pss_sha512/"`
+
+## Linting
+- Run standardrb: `bundle exec standardrb`
+- Fix issues automatically: `bundle exec standardrb --fix`
+
+Always run linters before commit
+
+## Bump gem version
+
+- Update version number in lib/http_signature/version.rb
+- Run `bundle install`
+- Commit with message "Version x.x.x" and push

data/Gemfile

@@ -1,5 +1,3 @@
 source "https://rubygems.org"
 
-ruby "3.4.8"
-
 gemspec

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    http_signature (1.2.0)
+    http_signature (1.3.0)
       base64
+      starry (~> 0.2)
 
 GEM
   remote: https://rubygems.org/
@@ -129,6 +130,8 @@ GEM
     standard-performance (1.9.0)
       lint_roller (~> 1.1)
       rubocop-performance (~> 1.26.0)
+    starry (0.2.0)
+      base64
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)
@@ -152,8 +155,5 @@ DEPENDENCIES
   simplecov
   standard
 
-RUBY VERSION
-  ruby 3.4.8
-
 BUNDLED WITH
   4.0.2

data/README.md

@@ -53,12 +53,28 @@ HTTPSignature.create(
   created: Time.now.to_i, # Default: Time.now.to_i
   expires: Time.now.to_i + 600, # Default: nil
   nonce: "1", # Default: nil
-  label: "sig1", # Default: "sig1",
-  query_string_params: {pet2: "cat"} # Default: {}, you can pass query string params both here and in the `url` param
-  algorithm: "hmac-sha512" # Default: "hmac-sha256"
+  label: "sig1", # Default: "sig1"
+  query_string_params: {pet2: "cat"}, # Default: {}, you can pass query string params both here and in the `url` param
+  algorithm: "hmac-sha512", # Default: "hmac-sha256"
+  include_alg: true, # Default: true, set to false to omit the alg parameter from Signature-Input
+  status: 200, # Default: nil, required when signing responses with @status component
+  attached_request: { headers: req_headers } # Default: nil, required when using ;req component parameter
 )
 ```
 
+#### Supported algorithms
+
+| Algorithm | Key type |
+|-----------|----------|
+| `hmac-sha256` (default) | Shared secret string |
+| `hmac-sha512` | Shared secret string |
+| `rsa-pss-sha256` | RSA key (`OpenSSL::PKey::RSA`) |
+| `rsa-pss-sha512` | RSA key |
+| `rsa-v1_5-sha256` | RSA key |
+| `ecdsa-p256-sha256` | EC key (P-256 curve) |
+| `ecdsa-p384-sha384` | EC key (P-384 curve) |
+| `ed25519` | Ed25519 key |
+
 #### Supported components
 
 Derived components (prefixed with `@`) per [RFC 9421 Section 2.2](https://www.rfc-editor.org/rfc/rfc9421#section-2.2):
@@ -71,12 +87,64 @@ Derived components (prefixed with `@`) per [RFC 9421 Section 2.2](https://www.rf
 | `@scheme` | URI scheme (`http` or `https`) |
 | `@path` | Request path (`/foo`) |
 | `@query` | Query string (including `?`; `?bar=1`) |
+| `@query-param` | Individual query parameter (requires `;name`, e.g., `@query-param;name="pet"`) |
+| `@request-target` | Request target (path + query) |
 | `@status` | Response status code (responses only) |
 
 Any lowercase header name (e.g., `content-type`, `date`) can also be used as a component.
 
 Default components are: `@method @target-uri content-digest content-type`
 
+#### Component parameters
+
+Components can have parameters per [RFC 9421 Section 2.1](https://www.rfc-editor.org/rfc/rfc9421#section-2.1):
+
+| Parameter | Description |
+|-----------|-------------|
+| `;sf` | Serialize the value as a structured field ([RFC 8941](https://www.rfc-editor.org/rfc/rfc8941)) |
+| `;key="member"` | Extract a single dictionary member from a structured field |
+| `;bs` | Use byte sequence serialization for the value |
+| `;req` | Resolve the component from the attached request (see below) |
+| `;name="param"` | Select a named query parameter (only with `@query-param`) |
+
+Example using `;key` to sign only the `sha-256` member of `content-digest`:
+
+```ruby
+components: ["@method", "@target-uri", 'content-digest;key="sha-256"']
+```
+
+#### Signing responses bound to a request
+
+When signing an HTTP response, you can bind it to the original request using the `;req` component parameter ([RFC 9421 Section 2.4](https://www.rfc-editor.org/rfc/rfc9421#section-2.4)). This cryptographically ties the response signature to values from the request, proving the response was generated for that specific request.
+
+Pass the original request headers via `attached_request`:
+
+```ruby
+sig_headers = HTTPSignature.create(
+  url: "https://example.com/api/data",
+  method: "POST",
+  headers: response_headers,
+  components: ["@status", "content-type", "content-type;req", "@method;req"],
+  status: 200,
+  key: "secret",
+  key_id: "key-1",
+  attached_request: { headers: { "content-type" => "application/json" } }
+)
+```
+
+Components with `;req` are resolved from the attached request's headers instead of the response headers. For verification, pass the same `attached_request`:
+
+```ruby
+HTTPSignature.valid?(
+  url: "https://example.com/api/data",
+  method: "POST",
+  headers: response_headers,
+  key: "secret",
+  status: 200,
+  attached_request: { headers: original_request_headers }
+)
+```
+
 ### Validate signature
 
 Call `valid?` with the incoming request headers (including `Signature-Input` and `Signature`)
@@ -93,6 +161,50 @@ HTTPSignature.valid?(
 # Raises `SignatureError` for invalid signatures
 ```
 
+#### All verification options
+
+```ruby
+HTTPSignature.valid?(
+  url: "https://example.com/foo",
+  method: :get,
+  headers: headers,
+  body: request_body, # Default: ""
+  key: "secret", # Default: nil, uses key_resolver or configured keys if nil
+  key_resolver: ->(key_id) { find_key(key_id) }, # Default: nil, called with the key_id from Signature-Input
+  label: "sig1", # Default: "sig1"
+  query_string_params: {}, # Default: {}
+  max_age: 300, # Default: nil, reject signatures older than N seconds
+  algorithm: "hmac-sha256", # Default: nil, uses alg from Signature-Input or hmac-sha256
+  status: 200, # Default: nil, required when verifying responses with @status
+  require_content_digest: true, # Default: false, raise if body present but content-digest not signed
+  attached_request: { headers: req_headers } # Default: nil, required when ;req components were signed
+)
+```
+
+#### Dynamic key resolution
+
+Use `key_resolver` when you need to look up keys dynamically based on the `key_id` from the incoming signature:
+
+```ruby
+HTTPSignature.valid?(
+  url: "https://example.com/foo",
+  method: :get,
+  headers: headers,
+  key_resolver: ->(key_id) { KeyStore.find(key_id) }
+)
+```
+
+Alternatively, configure keys globally:
+
+```ruby
+HTTPSignature.configure do |config|
+  config.keys = [
+    {id: "key-1", value: "secret1"},
+    {id: "key-2", value: "secret2"}
+  ]
+end
+```
+
 #### Limiting signature age
 
 Use `max_age` to reject signatures older than a specified number of seconds, regardless of the signature's `expires` parameter. This helps protect against replay attacks.
@@ -109,6 +221,37 @@ HTTPSignature.valid?(
 # Raises `ExpiredError` if the signature was created more than 300 seconds ago
 ```
 
+### Content-Digest
+
+When `content-digest` is included in the signed components and a body is present, the gem handles [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530) Content-Digest automatically:
+
+- **Signing** (`create`): If the request has a body and no `Content-Digest` header, the gem generates one using SHA-256 and adds it to the headers. If the header already exists, it verifies it matches the body.
+- **Verification** (`valid?`): Verifies that the `Content-Digest` header matches the body. Raises `MissingComponent` if the header is absent, and `SignatureError` on mismatch.
+
+To enforce that every request with a body must have `content-digest` in its signed components, use `require_content_digest: true` during verification.
+
+### Error handling
+
+All errors inherit from `HTTPSignature::SignatureError`:
+
+| Error | Raised when |
+|-------|-------------|
+| `SignatureError` | Signature is invalid, headers are missing, or Content-Digest mismatches |
+| `MissingComponent` | A signed component is not present in the request |
+| `UnsupportedComponent` | An unknown derived component is used (e.g., `@foo`) |
+| `UnsupportedAlgorithm` | The signing algorithm is not supported |
+| `ExpiredError` | The signature has expired (via `expires` or `max_age`) |
+
+```ruby
+begin
+  HTTPSignature.valid?(url:, method:, headers:, key:)
+rescue HTTPSignature::ExpiredError
+  # Signature too old
+rescue HTTPSignature::SignatureError => e
+  # Any other signature problem
+end
+```
+
 ## Outgoing request examples
 
 ### NET::HTTP

data/http_signature.gemspec

@@ -30,4 +30,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "actionpack", ">= 6.1"
 
   spec.add_dependency "base64"
+  spec.add_dependency "starry", "~> 0.2"
 end

data/lib/http_signature/rack.rb

@@ -52,12 +52,17 @@ class HTTPSignature::Rack
   def parse_request_headers(request)
     request_headers = {}
 
-    request.each_header do |header|
-      if header[0].include?("HTTP_") && header[0] != "HTTP_VERSION"
-        request_headers[header[0].gsub("HTTP_", "").tr("_", "-").downcase] = header[1]
+    request.each_header do |key, value|
+      if key.start_with?("HTTP_") && key != "HTTP_VERSION"
+        request_headers[key.sub("HTTP_", "").tr("_", "-").downcase] = value
       end
     end
 
+    %w[CONTENT_TYPE CONTENT_LENGTH].each do |env_key|
+      value = request.get_header(env_key)
+      request_headers[env_key.downcase.tr("_", "-")] = value if value
+    end
+
     request_headers
   end
 

data/lib/http_signature/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HTTPSignature
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/http_signature.rb

@@ -4,7 +4,7 @@ require "openssl"
 require "base64"
 require "uri"
 require "digest"
-require "rack/utils"
+require "starry"
 
 # Implements HTTP Message Signatures per RFC 9421.
 module HTTPSignature
@@ -20,7 +20,7 @@ module HTTPSignature
   class UnsupportedAlgorithm < SignatureError; end
   class ExpiredError < SignatureError; end
 
-  SUPPORTED_DERIVED_COMPONENTS = %w[@method @authority @target-uri @scheme @path @query @status].freeze
+  SUPPORTED_DERIVED_COMPONENTS = %w[@method @authority @target-uri @request-target @scheme @path @query @query-param @status].freeze
 
   Algorithm = Struct.new(:type, :digest_name, :curve)
   ALGORITHMS = {
@@ -87,7 +87,8 @@ module HTTPSignature
     label: DEFAULT_LABEL,
     query_string_params: {},
     include_alg: true,
-    status: nil
+    status: nil,
+    attached_request: nil
   )
     unless created.is_a?(Integer)
       raise ArgumentError, "created must be a Unix timestamp integer"
@@ -114,12 +115,15 @@ module HTTPSignature
         normalized_headers
       end
 
+    normalized_attached = attached_request ? {headers: normalize_headers(attached_request[:headers])} : nil
+
     canonical_components = build_components(
       uri:,
       method:,
       headers: normalized_headers,
       components:,
-      status:
+      status:,
+      attached_request: normalized_attached
     )
 
     signature_input_header, base_string = build_signature_input(
@@ -157,6 +161,8 @@ module HTTPSignature
   # @param algorithm [String, nil] Override algorithm for verification. If nil, uses alg from
   #   signature params or defaults to hmac-sha256 (default: nil)
   # @param status [Integer, nil] HTTP status code, required when verifying responses with @status component
+  # @param require_content_digest [Boolean] When true, raises if a body is present but content-digest
+  #   is not in the signed components. Useful for enforcing body integrity (default: false)
   # @return [Boolean] true when signature verification succeeds
   # @raise [ArgumentError] If max_age is not a non-negative integer
   # @raise [SignatureError] If signature headers are missing, key is missing, or signature is invalid
@@ -172,7 +178,9 @@ module HTTPSignature
     query_string_params: {},
     max_age: nil,
     algorithm: nil,
-    status: nil
+    status: nil,
+    require_content_digest: false,
+    attached_request: nil
   )
     if max_age && (!max_age.is_a?(Integer) || max_age < 0)
       raise ArgumentError, "max_age must be a non-negative integer"
@@ -184,12 +192,13 @@ module HTTPSignature
     raise SignatureError, "Signature headers are required for verification" unless signature_input_header && signature_header
 
     parsed_input = parse_signature_input(signature_input_header, label)
+    validate_components!(parsed_input[:components])
     parsed_signature = parse_signature(signature_header, label)
 
     algorithm_entry = algorithm_entry_for(algorithm || parsed_input[:params][:alg] || DEFAULT_ALGORITHM)
     key_id = parsed_input[:params][:keyid]
-    created = parsed_input[:params][:created].to_i
-    signature_expires = parsed_input[:params][:expires]&.to_i
+    created = parse_signature_timestamp(parsed_input[:params][:created], :created)
+    signature_expires = parse_signature_timestamp(parsed_input[:params][:expires], :expires, required: false)
     effective_expires = max_age ? created + max_age : signature_expires
     now = Time.now.to_i
     if effective_expires && (created > effective_expires || now > effective_expires)
@@ -199,16 +208,26 @@ module HTTPSignature
     raise SignatureError, "Key is required for verification" unless resolved_key
 
     uri = apply_query_params(URI(url), query_string_params)
+    if require_content_digest && !body.to_s.empty? && !parsed_input[:components].include?("content-digest")
+      raise SignatureError, "content-digest component is required when body is present"
+    end
+
     if parsed_input[:components].include?("content-digest")
-      normalized_headers = ensure_content_digest(normalized_headers, body)
+      unless normalized_headers["content-digest"]
+        raise MissingComponent, "Missing required component: content-digest"
+      end
+      verify_content_digest!(normalized_headers["content-digest"], body) unless body.to_s.empty?
     end
 
+    normalized_attached = attached_request ? {headers: normalize_headers(attached_request[:headers])} : nil
+
     canonical_components = build_components(
       uri:,
       method:,
       headers: normalized_headers,
       components: parsed_input[:components],
-      status:
+      status:,
+      attached_request: normalized_attached
     )
 
     _, base_string = build_signature_input(
@@ -244,15 +263,50 @@ module HTTPSignature
     new_uri
   end
 
+  KNOWN_PARAMETERS = %w[sf key bs req tr name].freeze
+
   def self.validate_components!(components)
+    if components.include?("@signature-params")
+      raise UnsupportedComponent, "@signature-params cannot be included as a component"
+    end
+
+    seen = {}
     components.each do |component|
+      if seen[component]
+        raise UnsupportedComponent, "Duplicate component: #{component}"
+      end
+      seen[component] = true
+
+      params = parse_component_params(component)
+      has_sf = params["sf"] || params.key?("key")
+      has_bs = params["bs"]
+
+      if has_sf && has_bs
+        raise UnsupportedComponent, "Cannot combine ;sf/;key with ;bs: #{component}"
+      end
+
+      if params.key?("name") && !component.start_with?("@query-param")
+        raise UnsupportedComponent, ";name parameter only valid with @query-param: #{component}"
+      end
+
       next unless component.start_with?("@")
-      next if SUPPORTED_DERIVED_COMPONENTS.include?(component)
+      base = component.split(";").first
+      next if SUPPORTED_DERIVED_COMPONENTS.include?(base)
 
       raise UnsupportedComponent, "Unsupported component: #{component}"
     end
   end
 
+  def self.parse_component_params(component)
+    _, raw_params = component.split(";", 2)
+    return {} unless raw_params
+
+    raw_params.split(";").each_with_object({}) do |param, hash|
+      key, value = param.split("=", 2)
+      hash[key] = value ? value.delete_prefix('"').delete_suffix('"') : true
+    end
+  end
+
   def self.default_components(headers, body: nil)
     components = DEFAULT_COMPONENTS.dup
     DEFAULT_HEADERS.each do |header|
@@ -271,27 +325,111 @@ module HTTPSignature
 
   def self.ensure_content_digest(headers, body)
     return headers if body.to_s.empty?
-    return headers if headers["content-digest"]
+
+    if headers["content-digest"]
+      verify_content_digest!(headers["content-digest"], body)
+      return headers
+    end
 
     digest = Digest::SHA256.digest(body)
     headers.merge("content-digest" => "sha-256=:#{Base64.strict_encode64(digest)}:")
   end
 
-  def self.build_components(uri:, method:, headers:, components:, status: nil)
+  def self.verify_content_digest!(header_value, body)
+    verified = false
+
+    header_value.scan(/([a-z0-9-]+)=:([A-Za-z0-9+\/=]+):/).each do |alg, encoded_digest|
+      digest = case alg
+      when "sha-256" then Digest::SHA256.digest(body)
+      when "sha-512" then Digest::SHA512.digest(body)
+      end
+      next unless digest
+
+      begin
+        decoded = Base64.strict_decode64(encoded_digest)
+      rescue ArgumentError
+        raise SignatureError, "Invalid Content-Digest encoding for #{alg}"
+      end
+      unless digest == decoded
+        raise SignatureError, "Content-Digest mismatch: body does not match #{alg} digest"
+      end
+      verified = true
+    end
+
+    raise SignatureError, "Content-Digest header contains no supported algorithm" unless verified
+  end
+
+  def self.build_components(uri:, method:, headers:, components:, status: nil, attached_request: nil)
     components.map do |component|
-      if component.start_with?("@")
-        [component, derived_component(component, uri, method, status:)]
+      params = parse_component_params(component)
+      base = component.split(";").first
+
+      if params["req"]
+        raise MissingComponent, ";req requires an attached request" unless attached_request
+        req_component = component.sub(/;req(?:=\S+)?/, "")
+        value = resolve_component_value(req_component, uri, method, attached_request[:headers], status:)
+      elsif base.start_with?("@")
+        value = derived_component(component, uri, method, status:)
       else
-        value = headers[component]
-        raise MissingComponent, "Missing required component: #{component}" unless value
+        raw = headers[base]
+        raise MissingComponent, "Missing required component: #{base}" unless raw
+        value = canonical_header_value(raw)
+      end
+
+      value = apply_structured_params(value, params)
 
-        [component, canonical_header_value(value)]
+      [component, value]
+    end
+  end
+
+  def self.resolve_component_value(component, uri, method, headers, status: nil)
+    base = component.split(";").first
+    if base.start_with?("@")
+      derived_component(component, uri, method, status:)
+    else
+      raw = headers[base]
+      raise MissingComponent, "Missing required component: #{base}" unless raw
+      canonical_header_value(raw)
+    end
+  end
+
+  def self.apply_structured_params(value, params)
+    has_sf = params["sf"] || params.key?("key")
+    has_bs = params["bs"]
+
+    if has_sf
+      key = params["key"]
+      if key
+        dict = Starry.parse_dictionary(value)
+        obj = dict[key]
+        raise MissingComponent, "Dictionary member not found: #{key}" unless obj
+        Starry.serialize(obj.is_a?(Starry::InnerList) ? [obj] : obj)
+      else
+        Starry.serialize(parse_structured_field(value))
       end
+    elsif has_bs
+      Starry.serialize(value.encode(Encoding::ASCII_8BIT))
+    else
+      value
+    end
+  rescue Starry::ParseError
+    raise SignatureError, "Failed to parse structured field value"
+  end
+
+  def self.parse_structured_field(value)
+    Starry.parse_dictionary(value)
+  rescue Starry::ParseError
+    begin
+      Starry.parse_list(value)
+    rescue Starry::ParseError
+      Starry.parse_item(value)
     end
   end
 
   def self.derived_component(component, uri, method, status: nil)
-    case component
+    base = component.split(";").first
+
+    case base
     when "@method" then method.to_s.upcase
     when "@authority"
       port = uri.port
@@ -299,9 +437,21 @@ module HTTPSignature
       (uri.port && port != default_port) ? "#{uri.host}:#{uri.port}" : uri.host
     when "@target-uri"
       uri.dup.tap { |u| u.fragment = nil }.to_s
+    when "@request-target"
+      path = uri.path.empty? ? "/" : uri.path
+      uri.query ? "#{path}?#{uri.query}" : path
     when "@scheme" then uri.scheme
-    when "@path" then uri.path
-    when "@query" then uri.query.to_s
+    when "@path"
+      path = uri.path
+      path.empty? ? "/" : path
+    when "@query" then "?#{uri.query}"
+    when "@query-param"
+      encoded_name = component.match(/;name="([^"]*)"/)&.[](1)
+      raise MissingComponent, "@query-param requires a name parameter" unless encoded_name
+      name = URI.decode_www_form_component(encoded_name)
+      pair = uri.query.to_s.split("&").map { |p| p.split("=", 2) }.find { |n, _| URI.decode_www_form_component(n) == name }
+      raise MissingComponent, "Query parameter not found: #{encoded_name}" unless pair
+      pair[1].to_s.tr("+", "%20")
     when "@status"
       raise MissingComponent, "@status requires a status code" unless status
       status.to_s
@@ -314,10 +464,24 @@ module HTTPSignature
     value.is_a?(Array) ? value.join(", ") : value.to_s
   end
 
+  def self.serialize_component_id(component)
+    base, params = component.split(";", 2)
+    serialized = %("#{escape_structured_string(base)}")
+    serialized << ";#{params}" if params
+    serialized
+  end
+
   def self.escape_structured_string(value)
     value.to_s.gsub("\\") { "\\\\" }.gsub('"') { '\"' }
   end
 
+  def self.unescape_structured_string(value)
+    return value unless value
+
+    value.delete_prefix('"').delete_suffix('"')
+      .gsub('\\"', '"').gsub("\\\\", "\\")
+  end
+
   def self.build_signature_input(
     label:,
     components:,
@@ -328,7 +492,7 @@ module HTTPSignature
     nonce:,
     canonical_components:
   )
-    component_tokens = components.map { |c| %("#{escape_structured_string(c)}") }.join(" ")
+    component_tokens = components.map { |c| serialize_component_id(c) }.join(" ")
     params = ["created=#{created}"]
     params << "expires=#{expires}" unless expires.nil?
     params << %(keyid="#{escape_structured_string(key_id)}")
@@ -339,7 +503,7 @@ module HTTPSignature
     signature_input_header = "#{label}=#{signature_params}"
 
     base_lines = canonical_components.map do |name, value|
-      %("#{name}": #{value})
+      "#{serialize_component_id(name)}: #{value}"
     end
     base_lines << %("@signature-params": #{signature_params})
 
@@ -361,6 +525,10 @@ module HTTPSignature
   end
 
   def self.sign(base_string, key:, algorithm:)
+    if algorithm.type == :hmac && asymmetric_key?(key)
+      raise SignatureError, "HMAC algorithm cannot be used with an asymmetric key"
+    end
+
     case algorithm.type
     when :hmac
       OpenSSL::HMAC.digest(algorithm.digest_name, key, base_string)
@@ -387,10 +555,15 @@ module HTTPSignature
   end
 
   def self.verify_signature(base_string, signature_bytes, key, algorithm)
+    if algorithm.type == :hmac && asymmetric_key?(key)
+      raise SignatureError, "HMAC algorithm cannot be used with an asymmetric key"
+    end
+
     case algorithm.type
     when :hmac
       expected = OpenSSL::HMAC.digest(algorithm.digest_name, key, base_string)
-      ::Rack::Utils.secure_compare(expected, signature_bytes)
+      expected.bytesize == signature_bytes.bytesize &&
+        OpenSSL.fixed_length_secure_compare(expected, signature_bytes)
     when :rsa_pss
       pkey = rsa_key(key)
       # Use generic verify with RSA-PSS options (works with all key types)
@@ -418,12 +591,17 @@ module HTTPSignature
     raise SignatureError, "Signature-Input missing" unless entry
 
     components_match = entry.match(/\((.*?)\)/)
-    components =
-      components_match ? components_match[1].scan(/"([^"]+)"/).flatten : []
+    components = if components_match
+      components_match[1].scan(/"([^"]+)"((?:;[a-z]+(?:=(?:"[^"]*"|\S+))?)*)/).map do |base, params|
+        params.empty? ? base : "#{base}#{params}"
+      end
+    else
+      []
+    end
 
     params = entry.split(");").last&.split(";")&.map do |p|
       key, value = p.split("=", 2)
-      [key.to_sym, value&.tr('"', "")]
+      [key.to_sym, unescape_structured_string(value)]
     end.to_h
 
     {components:, params:}
@@ -452,6 +630,19 @@ module HTTPSignature
     key(key_id)
   end
 
+  def self.parse_signature_timestamp(value, param_name, required: true)
+    if value.nil?
+      raise SignatureError, "Missing required #{param_name} parameter" if required
+      return nil
+    end
+
+    unless value.match?(/\A\d+\z/)
+      raise SignatureError, "Invalid #{param_name} parameter"
+    end
+
+    value.to_i
+  end
+
   def self.rsa_key(key)
     return key if key.is_a?(OpenSSL::PKey::RSA) || key.is_a?(OpenSSL::PKey::PKey)
 
@@ -468,6 +659,45 @@ module HTTPSignature
     OpenSSL::PKey.read(key)
   end
 
+  def self.asymmetric_key?(key)
+    return true if key.is_a?(OpenSSL::PKey::PKey)
+    return false unless key.is_a?(String)
+
+    pkey = nil
+
+    # Try parsing as an OpenSSL PKey
+    # Fast path for PEM encoded keys
+    if key.match?(/\A\s*-----BEGIN/)
+      begin
+        pkey = OpenSSL::PKey.read(key)
+      rescue ArgumentError, OpenSSL::PKey::PKeyError
+        return false
+      end
+    # For binary DER, only attempt parse if it looks like ASN.1 SEQUENCE (0x30)
+    # to avoid misclassifying raw HMAC secrets that start with 0x30 as asymmetric
+    elsif key.bytes[0] == 0x30
+      begin
+        pkey = OpenSSL::PKey.read(key)
+      rescue ArgumentError, OpenSSL::PKey::PKeyError
+        return false
+      end
+    end
+
+    return false unless pkey
+
+    # Only treat as asymmetric if parsed to a known key type with sane structure,
+    # so raw binary that parses as arbitrary DER is not misclassified as a key
+    case pkey
+    when OpenSSL::PKey::RSA
+      pkey.n&.num_bits.to_i >= 512
+    when OpenSSL::PKey::EC
+      true
+    else
+      # Ed25519 or other PKey subclass
+      true
+    end
+  end
+
   # Convert ECDSA DER signature to raw (r || s) format per RFC 9421
   def self.ecdsa_der_to_raw(der_signature, curve)
     byte_size = (curve == "prime256v1") ? 32 : 48
@@ -485,6 +715,10 @@ module HTTPSignature
   # Convert raw (r || s) signature to ECDSA DER format
   def self.ecdsa_raw_to_der(raw_signature, curve)
     byte_size = (curve == "prime256v1") ? 32 : 48
+    expected_size = byte_size * 2
+    unless raw_signature.is_a?(String) && raw_signature.bytesize == expected_size
+      raise SignatureError, "Invalid ECDSA signature length"
+    end
 
     r_bytes = raw_signature[0, byte_size]
     s_bytes = raw_signature[byte_size, byte_size]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: http_signature
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Joel Larsson
@@ -135,6 +135,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: starry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 description: 'Create and validate HTTP Message Signatures according to RFC 9421: https://www.rfc-editor.org/rfc/rfc9421.html'
 email:
 - bolmaster2@gmail.com