http_signature 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a052e0252607d934ef7221c6aa3ea32fb21644af4f1af77985677db0cb2e2bb3
-  data.tar.gz: 843effaf6aac8b647b29d2d19f5414513be7efb76a0a1eb837b9cc2872fe3727
+  metadata.gz: 4d7340510585b31400802574581fc40aa006889f7f43e67e6ac4d5c926ddc3ce
+  data.tar.gz: 3364453874b93eb6b37a2ef13208dbb2792b4b50975c872459fea1a1d70a68d7
 SHA512:
-  metadata.gz: 5aedcedf0056a4f98414a599a51ec89484500c3447f124c4f070b11d7567ec2c8b5f682aa17e8f1e6c1dcf09f0c1e796530ada79bca633e228e3cfe98154f575
-  data.tar.gz: 61e44809bd68c3d072b94faee4f1ba7915aa49e2acfde2131b55c2442982a14cd199e288eff6cf34533440bebfb3b788997a395f618830da4a4c7d96407e7e01
+  metadata.gz: ba102a57a504be38d46ff962442d273dcee1866e5e49127927f638774dc30a66b92c063edb62670ba09b42b14bb2257772992183b606ef2abc7c1d1340677717
+  data.tar.gz: b2ee1d08d85958e663760b999c45a8865e2db4f43920fbf9a77bae78479a5192e939d0cfdab26a6d47dd936c1bb17311b809ac6b8278f92d1c8ced43de957d9d

data/AGENTS.md

@@ -1,3 +1,7 @@
+# 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`

data/Gemfile.lock

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

data/README.md

@@ -23,21 +23,40 @@ bundle add 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"
+)
 ```
 
 
@@ -52,6 +71,9 @@ HTTPSignature.valid?(
   headers: headers,
   key: "secret"
 )
+
+# Returns true when all is good.
+# Raises `SignatureError` for invalid signatures
 ```
 
 ## Outgoing request examples
@@ -59,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)
@@ -71,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
@@ -89,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=...
@@ -115,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
@@ -134,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
@@ -149,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.1"
+  VERSION = "1.1.0"
 end

data/lib/http_signature.rb

@@ -17,6 +17,7 @@ module HTTPSignature
   class SignatureError < StandardError; end
   class MissingComponent < SignatureError; end
   class UnsupportedAlgorithm < SignatureError; end
+  class ExpiredError < SignatureError; end
 
   Algorithm = Struct.new(:type, :digest_name, :curve)
   ALGORITHMS = {
@@ -56,18 +57,28 @@ 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)
 
-    components =
-      covered_components || default_components(normalized_headers, body:)
+    components ||=
+      default_components(normalized_headers, body:)
 
     normalized_headers =
       if components.include?("content-digest")
@@ -77,20 +88,21 @@ module HTTPSignature
       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)
@@ -104,7 +116,7 @@ module HTTPSignature
 
   # Verify RFC 9421 Signature headers
   #
-  # @return [Boolean]
+  # @return [Boolean] true when signature verification succeeds
   def self.valid?(
     url:,
     method:,
@@ -126,6 +138,12 @@ 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
 
@@ -135,23 +153,27 @@ module HTTPSignature
     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 --
@@ -194,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
@@ -236,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
 
@@ -349,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.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Joel Larsson
@@ -170,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:
   - - ">="