http_signature 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d4b1e73dff1838a018f5e0d5bef1c6a6a14c2b8ef552dbbfd0481ac85cb03b7
-  data.tar.gz: 1a087ded86d8f84213984d9bd56fb55462f65feb9abc876514249f12fc5166ef
+  metadata.gz: 4d7340510585b31400802574581fc40aa006889f7f43e67e6ac4d5c926ddc3ce
+  data.tar.gz: 3364453874b93eb6b37a2ef13208dbb2792b4b50975c872459fea1a1d70a68d7
 SHA512:
-  metadata.gz: 7796499163d70782ea0fd809316c39a4d2a933cf01cc88f6daaa88d673607e9a138643d666fc5080063ea0bdb1068d32c48642fb487c59d6edcb7626fba7ad8e
-  data.tar.gz: 1603d71ad33fc087e456949de3e1534f3cf08c894a3fe10a3f456f6751409ddbbda247a53511d201866cf10f629e2c676fbe2eaa7cb0e0535dae81a2cad6e2a2
+  metadata.gz: ba102a57a504be38d46ff962442d273dcee1866e5e49127927f638774dc30a66b92c063edb62670ba09b42b14bb2257772992183b606ef2abc7c1d1340677717
+  data.tar.gz: b2ee1d08d85958e663760b999c45a8865e2db4f43920fbf9a77bae78479a5192e939d0cfdab26a6d47dd936c1bb17311b809ac6b8278f92d1c8ced43de957d9d

data/.github/workflows/push_gem.yml

@@ -0,0 +1,25 @@
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  push:
+    name: Push gem to RubyGems.org
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
+      contents: write # IMPORTANT: this permission is required for `rake release` to push the release tag
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: '3.4'
+
+      - uses: rubygems/release-gem@v1

data/AGENTS.md

@@ -0,0 +1,8 @@
+# HTTP signature gem
+
+This is a Ruby gem implementing the [HTTP Message Signatures RFC 9421 standard](https://www.rfc-editor.org/rfc/rfc9421.txt). Always adhere to the standard
+
+## Tests
+- 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/"`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    http_signature (1.0.0)
+    http_signature (1.1.0)
       base64
 
 GEM

data/README.md

@@ -2,18 +2,19 @@
 
 Create and validate HTTP Message Signatures per [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421) using the `Signature-Input` and `Signature` headers.
 
-Aims to only implement the creation and validation of signatures without any external dependencies. Adapters are provided for common HTTP libraries.
+TL;DR: You specify what should be signed in `Signature-Input` with [components](https://www.rfc-editor.org/rfc/rfc9421#name-derived-components) and lowercase headers. And then the signature is in the `Signature` header
+
+Example:
 
-__NOTE__: RFC 9421 signs components via two headers:
 ```
-Signature-Input: sig1=("@method" "@authority" "@target-uri" "date");created=...
-Signature: sig1=:BASE64_SIGNATURE_BYTES:
+Signature-Input: sig1=("@method" "@target-uri" "date");created=1767816111;keyid="Test";alg="hmac-sha256"
+Signature: sig1=:7a1ajkE2rOu+gnW3WLZ4ZEcgCm3TfExmypM/giIgdM0=:
 ```
 
 ## Installation
 
 ```shell
-gem install http_signature
+bundle add http_signature
 ```
 
 ## Usage
@@ -22,21 +23,40 @@ gem install http_signature
 
 `HTTPSignature.create` returns both `Signature-Input` and `Signature` headers that you can include in your request.
 
-
 ```ruby
-headers = { 'date' => 'Tue, 20 Apr 2021 02:07:55 GMT' }
+headers = { "date" => "Tue, 20 Apr 2021 02:07:55 GMT" }
 
 sig_headers = HTTPSignature.create(
-  url: 'https://example.com/foo?pet=dog',
+  url: "https://example.com/foo?pet=dog",
   method: :get,
+  key_id: "Test",
+  key: "secret",
   headers: headers,
-  key_id: 'Test',
-  key: 'secret',
-  covered_components: %w[@method @target-uri date],
+  components: %w[@method @target-uri date]
 )
 
-request['Signature-Input'] = sig_headers['Signature-Input']
-request['Signature'] = sig_headers['Signature']
+request["Signature-Input"] = sig_headers["Signature-Input"]
+request["Signature"] = sig_headers["Signature"]
+```
+#### All options
+
+```ruby
+HTTPSignature.create(
+  url: "https://example.com/foo?pet=dog",
+  method: :get,
+  key_id: "Test",
+  key: "secret",
+  # Optional arguments
+  headers: headers, # Default: {}
+  body: "Hello world", # Default: ""
+  components: %w[@method @target-uri date], # Default: %w[@method @target-uri content-digest content-type]
+  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"
+)
 ```
 
 
@@ -51,6 +71,9 @@ HTTPSignature.valid?(
   headers: headers,
   key: "secret"
 )
+
+# Returns true when all is good.
+# Raises `SignatureError` for invalid signatures
 ```
 
 ## Outgoing request examples
@@ -58,10 +81,10 @@ HTTPSignature.valid?(
 ### NET::HTTP
 
 ```ruby
-require 'net/http'
-require 'http_signature'
+require "net/http"
+require "http_signature"
 
-uri = URI('http://example.com/hello')
+uri = URI("http://example.com/hello")
 
 Net::HTTP.start(uri.host, uri.port) do |http|
   request = Net::HTTP::Get.new(uri)
@@ -70,14 +93,14 @@ Net::HTTP.start(uri.host, uri.port) do |http|
     url: request.uri,
     method: request.method,
     headers: request.each_header.map { |k, v| [k, v] }.to_h,
-    key: 'MYSECRETKEY',
-    key_id: 'KEY_1',
-    algorithm: 'hmac-sha256',
-    body: request.body ? request.body : ''
+    key: "MYSECRETKEY",
+    key_id: "KEY_1",
+    algorithm: "hmac-sha256",
+    body: request.body || ""
   )
 
-  request['Signature-Input'] = sig_headers['Signature-Input']
-  request['Signature'] = sig_headers['Signature']
+  request["Signature-Input"] = sig_headers["Signature-Input"]
+  request["Signature"] = sig_headers["Signature"]
 
   response = http.request(request) # Net::HTTPResponse
 end
@@ -88,18 +111,18 @@ end
 As a faraday middleware
 
 ```ruby
-require 'http_signature/faraday'
+require "http_signature/faraday"
 
-HTTPSignature::Faraday.key = 'secret'
-HTTPSignature::Faraday.key_id = 'key-1'
+HTTPSignature::Faraday.key = "secret"
+HTTPSignature::Faraday.key_id = "key-1"
 
-Faraday.new('http://example.com') do |faraday|
+Faraday.new("http://example.com") do |faraday|
   faraday.use(HTTPSignature::Faraday)
   faraday.adapter(Faraday.default_adapter)
 end
 
 # Now this request will contain the `Signature-Input` and `Signature` headers
-response = conn.get('/')
+response = conn.get("/")
 
 # Request looking like:
 # Signature-Input: sig1=("@method" "@authority" "@target-uri" "date");created=...
@@ -114,14 +137,14 @@ Rack middlewares sits in between your app and the HTTP request and validate the
 Here is how it could be used with sinatra:
 
 ```ruby
-require 'http_signature/rack'
+require "http_signature/rack"
 
 HTTPSignature.configure do |config|
   config.keys = [
-    {id: 'key-1', value: 'MySecureKey'}
+    {id: "key-1", value: "MySecureKey"}
   ]
 end
-HTTPSignature::Rack.exclude_paths = ['/', '/hello/*']
+HTTPSignature::Rack.exclude_paths = ["/", "/hello/*"]
 
 use HTTPSignature::Rack
 run MyApp
@@ -133,7 +156,7 @@ Opt-in per controller/action using a before_action. It responds with `401 Unauth
 ```ruby
 # app/controllers/api/base_controller.rb
 
-require 'http_signature/rails'
+require "http_signature/rails"
 
 class Api::BaseController < ApplicationController
   include HTTPSignature::Rails::Controller
@@ -148,7 +171,7 @@ Set the keys in an initializer
 
 HTTPSignature.configure do |config|
   config.keys = [
-    {id: 'key-1', value: 'MySecureKey'}
+    {id: "key-1", value: "MySecureKey"}
   ]
 end
 ```

data/http_signature.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 3.0.0"
+  spec.required_ruby_version = ">= 3.1.0"
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"

data/lib/http_signature/rack.rb

@@ -33,7 +33,7 @@ class HTTPSignature::Rack
         else
           ""
         end
-      valid_signature = HTTPSignature.valid?(
+      HTTPSignature.valid?(
         url: request.url,
         method: request.request_method,
         headers: request_headers,
@@ -44,8 +44,6 @@ class HTTPSignature::Rack
       return [401, {}, ["Invalid signature"]]
     end
 
-    return [401, {}, ["Invalid signature"]] unless valid_signature
-
     @app.call(env)
   end
 

data/lib/http_signature/rails.rb

@@ -20,7 +20,7 @@ module HTTPSignature
 
         request_body = read_request_body
 
-        valid_signature = HTTPSignature.valid?(
+        HTTPSignature.valid?(
           url: request.url,
           method: request.request_method,
           headers: request_headers,
@@ -28,10 +28,8 @@ module HTTPSignature
           key_resolver: ->(key_id) { HTTPSignature.key(key_id) }
         )
 
-        return if valid_signature
-
-        render status: :unauthorized, plain: "Invalid signature"
-      rescue HTTPSignature::SignatureError, ArgumentError
+        nil
+      rescue HTTPSignature::SignatureError
         render status: :unauthorized, plain: "Invalid signature"
       end
 

data/lib/http_signature/version.rb

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

data/lib/http_signature.rb

@@ -11,11 +11,13 @@ module HTTPSignature
   Config = Struct.new(:keys)
   DEFAULT_LABEL = "sig1"
   DEFAULT_ALGORITHM = "hmac-sha256"
-  DEFAULT_COMPONENTS = %w[@method @authority @target-uri].freeze
+  DEFAULT_COMPONENTS = %w[@method @target-uri].freeze
+  DEFAULT_HEADERS = %w[content-digest content-type].freeze
 
   class SignatureError < StandardError; end
   class MissingComponent < SignatureError; end
   class UnsupportedAlgorithm < SignatureError; end
+  class ExpiredError < SignatureError; end
 
   Algorithm = Struct.new(:type, :digest_name, :curve)
   ALGORITHMS = {
@@ -55,36 +57,52 @@ module HTTPSignature
     headers: {},
     body: "",
     algorithm: DEFAULT_ALGORITHM,
-    covered_components: nil,
+    components: nil,
     created: Time.now.to_i,
+    expires: nil,
     nonce: nil,
     label: DEFAULT_LABEL,
     query_string_params: {}
   )
+    unless created.is_a?(Integer)
+      raise ArgumentError, "created must be a Unix timestamp integer"
+    end
+    if expires && !expires.is_a?(Integer)
+      raise ArgumentError, "expires must be a Unix timestamp integer"
+    end
+    if expires && created > expires
+      raise ArgumentError, "expires (#{expires}) must be greater than created (#{created})"
+    end
     algorithm_entry = algorithm_entry_for(algorithm)
     normalized_headers = normalize_headers(headers)
     uri = apply_query_params(URI(url), query_string_params)
 
-    normalized_headers = ensure_content_digest(normalized_headers, body)
+    components ||=
+      default_components(normalized_headers, body:)
 
-    components =
-      covered_components || default_components(normalized_headers)
+    normalized_headers =
+      if components.include?("content-digest")
+        ensure_content_digest(normalized_headers, body)
+      else
+        normalized_headers
+      end
 
     canonical_components = build_components(
-      uri: uri,
-      method: method,
+      uri:,
+      method:,
       headers: normalized_headers,
-      covered_components: components
+      components:
     )
 
     signature_input_header, base_string = build_signature_input(
-      label: label,
-      components: components,
-      created: created,
-      key_id: key_id,
+      label:,
+      components:,
+      created:,
+      expires:,
+      key_id:,
       alg: algorithm,
-      nonce: nonce,
-      canonical_components: canonical_components
+      nonce:,
+      canonical_components:
     )
 
     signature_bytes = sign(base_string, key: key, algorithm: algorithm_entry)
@@ -98,7 +116,7 @@ module HTTPSignature
 
   # Verify RFC 9421 Signature headers
   #
-  # @return [Boolean]
+  # @return [Boolean] true when signature verification succeeds
   def self.valid?(
     url:,
     method:,
@@ -120,30 +138,42 @@ module HTTPSignature
 
     algorithm_entry = algorithm_entry_for(parsed_input[:params][:alg] || DEFAULT_ALGORITHM)
     key_id = parsed_input[:params][:keyid]
+    created = parsed_input[:params][:created].to_i
+    expires = parsed_input[:params][:expires]&.to_i
+    now = Time.now.to_i
+    if expires && (created > expires || now > expires)
+      raise ExpiredError, "Signature expired at #{expires}"
+    end
     resolved_key = key || key_resolver&.call(key_id) || key_from_store(key_id)
     raise SignatureError, "Key is required for verification" unless resolved_key
 
     uri = apply_query_params(URI(url), query_string_params)
-    normalized_headers = ensure_content_digest(normalized_headers, body)
+    if parsed_input[:components].include?("content-digest")
+      normalized_headers = ensure_content_digest(normalized_headers, body)
+    end
 
     canonical_components = build_components(
-      uri: uri,
-      method: method,
+      uri:,
+      method:,
       headers: normalized_headers,
-      covered_components: parsed_input[:components]
+      components: parsed_input[:components]
     )
 
     _, base_string = build_signature_input(
-      label: label,
+      label:,
       components: parsed_input[:components],
-      created: parsed_input[:params][:created].to_i,
-      key_id: key_id,
+      created:,
+      expires:,
+      key_id:,
       alg: parsed_input[:params][:alg],
       nonce: parsed_input[:params][:nonce],
-      canonical_components: canonical_components
+      canonical_components:
     )
 
-    verify_signature(base_string, parsed_signature, resolved_key, algorithm_entry)
+    verified = verify_signature(base_string, parsed_signature, resolved_key, algorithm_entry)
+    raise SignatureError, "Invalid signature" unless verified
+
+    true
   end
 
   # -- Private-ish helpers --
@@ -162,10 +192,19 @@ module HTTPSignature
     new_uri
   end
 
-  def self.default_components(headers)
+  def self.default_components(headers, body: nil)
     components = DEFAULT_COMPONENTS.dup
-    components << "date" if headers["date"]
-    components << "content-digest" if headers["content-digest"]
+    DEFAULT_HEADERS.each do |header|
+      include_header =
+        if header == "content-digest"
+          !body.to_s.empty? || headers[header]
+        else
+          headers[header]
+        end
+
+      components << header if include_header
+    end
+
     components
   end
 
@@ -177,8 +216,8 @@ module HTTPSignature
     headers.merge("content-digest" => "sha-256=:#{Base64.strict_encode64(digest)}:")
   end
 
-  def self.build_components(uri:, method:, headers:, covered_components:)
-    covered_components.map do |component|
+  def self.build_components(uri:, method:, headers:, components:)
+    components.map do |component|
       if component.start_with?("@")
         [component, derived_component(component, uri, method)]
       else
@@ -219,13 +258,16 @@ module HTTPSignature
     label:,
     components:,
     created:,
+    expires:,
     key_id:,
     alg:,
     nonce:,
     canonical_components:
   )
     component_tokens = components.map { |c| %("#{escape_structured_string(c)}") }.join(" ")
-    params = ["created=#{created}", %(keyid="#{escape_structured_string(key_id)}")]
+    params = ["created=#{created}"]
+    params << "expires=#{expires}" unless expires.nil?
+    params << %(keyid="#{escape_structured_string(key_id)}")
     params << %(alg="#{escape_structured_string(alg)}") if alg
     params << %(nonce="#{escape_structured_string(nonce)}") if nonce
 
@@ -332,6 +374,8 @@ module HTTPSignature
 
     encoded = match[1]
     Base64.strict_decode64(encoded)
+  rescue ArgumentError
+    raise SignatureError, "Invalid signature format"
   end
 
   def self.split_header(header)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: http_signature
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Joel Larsson
@@ -143,9 +143,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yml"
+- ".github/workflows/push_gem.yml"
 - ".github/workflows/standardrb.yml"
 - ".gitignore"
 - ".ruby-version"
+- AGENTS.md
 - Gemfile
 - Gemfile.lock
 - README.md
@@ -168,7 +170,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="