linzer 0.7.0.beta1 → 0.7.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a19b05f41aa933779f504056b56b00fc1a8a6cda19bb26065dce56177caf0c2
-  data.tar.gz: 25d7d8b4afbd60a3e6e872064d92f9be22670466292e23a6ba8010ca546cdf23
+  metadata.gz: fd7b5e233ec42d94c7040f774097c612850eef9c5795a2c8d3251bc618c8df5f
+  data.tar.gz: 53cc818e2fc68fe1f6b3c89414a5b0d2393e1b8cfa8e4c9f3ba9076ce537f81c
 SHA512:
-  metadata.gz: 527fd9a73a1605b706fc7ca597ce14f4f5c95be099907bf61832aa698b11fe51dbf25a5eaf70d48d7c6715c91c27bfa391482a88a67f0e932c5f60ff8f3f16df
-  data.tar.gz: 2b30454801734973711afe81559ad18f09f6d08f473796241d56e1b13d5619971a697945703b85012e18ae969059ca5a3718e677fc71716151bd46e795eac8a7
+  metadata.gz: 93e5fb0d4fd0cd534691102a02efa8ae14589d12ee3636f86d10d19e57104b1bb122f950c9191c5fb40264fc453a31d33aa1369fac0fe34451e74108ce9c6a5c
+  data.tar.gz: e5b12b53e46f7958c560cb579111c14eab85da6a047effcdb599d39f955fe38b89175faef1937a963890c8d8254763c54314ea95c4eff70815fc0c0b8c396551

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [0.7.0.beta2] - 2025-04-13
+
+- Refactor and improve Rack::Auth::Signature code organization.
+- Do not expose secret material on HMAC SHA-256 key when #inspect method is used.
+- Update Rack::Auth::Signature configuration file options.
+- Validate and test Rack::Auth::Signature with example Rails and Sinatra apps.
+
 ## [0.7.0.beta1] - 2025-04-12
 
 - Introduce Rack::Auth::Signature middleware.

data/README.md

@@ -23,12 +23,14 @@ Or just `gem install linzer`.
 
 ### TL;DR: I just want to protect my application!!
 
-Add the following middleware to you run Rack application, e.g.:
+Add the following middleware to you run Rack application and configure it
+as needed, e.g.:
 
 ```ruby
 # config.ru
 use Rack::Auth::Signature, except: "/login",
-  default_key: {"key" => IO.read("app/config/pubkey.pem"), "alg" => "ed25519"}
+  default_key: {material: Base64.strict_decode64(ENV["MYAPP_KEY"]), alg: "hmac-sha256"}
+  # or: default_key: {material: IO.read("app/config/pubkey.pem"), "ed25519"}
 ```
 
 or on more complex scenarios:
@@ -39,6 +41,14 @@ use Rack::Auth::Signature, except: "/login",
   config_path: "app/configuration/http-signatures.yml"
 ```
 
+or with a typical Rails application:
+
+```ruby
+# config/application.rb
+config.middleware.use Rack::Auth::Signature, except: "/login",
+  config_path: "http-signatures.yml"
+```
+
 And that's it, all routes in the example app (except `/login`) above will
 require a valid signature created with the respective private key held by a
 client. For more details on what configuration options are available, take a

data/examples/sinatra/Gemfile

@@ -6,4 +6,4 @@ gem "sinatra",      "~> 4.0"
 gem "rackup",       "~> 2.1"
 gem "webrick",      "~> 1.9"
 gem "rack-contrib", "~> 2.4"
-gem "linzer",       "~> 0.7.0.beta1"
+gem "linzer",       "~> 0.7.0.beta2"

data/examples/sinatra/http-signatures.yml

@@ -1,26 +1,33 @@
 ---
-no_older_than: 6000
-created_required: true
-keyid_required: true
-# nonce_required: false
-# alg_required: false
-# tag_required: false
-# expires_required: false
-covered_components:
-- "@method"
-- "@request-target"
-- date
-known_keys:
+signatures:
+  reject_older_than:  6000 # seconds
+  created_required:   true
+  keyid_required:     true
+  # nonce_required:   false
+  # alg_required:     false
+  # tag_required:     false
+  # expires_required: false
+  covered_components:
+  - "@method"
+  - "@request-target"
+  - date
+  # In most cases is not needed to configure a label but it
+  # could useful in the event of receiving a signature
+  # header with more than 1 signature. Currently, linzer signatures
+  # middleware will only validate 1 signature per request and multiple
+  # signatures validation at the same time are not supported.
+  # If you need this, feel free to open an issue and explain your use case.
+  # default_label:      "mylabel"
+keys:
   foo:
     alg: ed25519
-    key: |
+    material: |
       -----BEGIN PUBLIC KEY-----
       MCowBQYDK2VwAyEAMEH9bSanwgAWE5qxUEaXjK6qei8z2hiHT0nlr7ljG0Y=
       -----END PUBLIC KEY-----
   bar:
-    alg: hmac-sha256
-    key: !binary |-
-      KuOR/Q8U1Crgp0WsFqW+5ZuC+KbN41dIlXWp71UhPEeJcRfuxZEy6XAUE9nf0yl4jt55yRASBnD0kQKucO6SfA==
-  baz:
     alg: rsa-pss-sha512
-    path: rsa.pem
+    path: pubkey_rsa.pem
+  baz:
+    alg: hmac-sha256
+    path: app.secret

data/examples/sinatra/myapp.rb

@@ -6,5 +6,16 @@ get "/" do
 end
 
 get "/protected" do
+  # if signature is valid, rack will expose it in the request object,
+  # so application specific checks can be performed, e.g.:
+  #
+  # halt if !request.env["rack.signature"].parameters["nonce"]
+  # halt if redis.exists?(request.env["rack.signature"].parameters["nonce"])
+  # halt unless request.env["rack.signature"].parameters["tag"] == "myapp"
+  #
+  # Note that these examples are deliberately simple for illustration
+  # purposes since such validations would make more sense to be
+  # encapsulated in helper methods called in a before { ... } block.
+  #
   "secure area"
 end

data/lib/linzer/hmac.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Linzer
   module HMAC
     class Key < Linzer::Key
@@ -15,6 +17,17 @@ module Linzer
       def verify(signature, data)
         signature == sign(data)
       end
+
+      def inspect
+        vars =
+          instance_variables
+            .reject { |v| v == :@material } # don't leak secret unneccesarily
+            .map do |n|
+              "#{n}=#{instance_variable_get(n).inspect}"
+            end
+        oid = Digest::SHA2.hexdigest(object_id.to_s)[48..63]
+        "#<%s:0x%s %s>" % [self.class, oid, vars.join(", ")]
+      end
     end
   end
 end

data/lib/linzer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Linzer
-  VERSION = "0.7.0.beta1"
+  VERSION = "0.7.0.beta2"
 end

data/lib/rack/auth/signature/helpers.rb

@@ -0,0 +1,132 @@
+require "yaml"
+
+module Rack
+  module Auth
+    class Signature
+      module Helpers
+        module Parameters
+          private
+
+          def created?
+            !options[:signatures][:created_required] || !!Integer(params.fetch("created"))
+          end
+
+          def expires?
+            return true if !options[:signatures][:expires_required]
+            Integer(params.fetch("expires")) > Time.now.to_i
+          end
+
+          def keyid?
+            !options[:signatures][:keyid_required] || String(params.fetch("keyid"))
+          end
+
+          def nonce?
+            !options[:signatures][:nonce_required] || String(params.fetch("nonce"))
+          end
+
+          def alg?
+            !options[:signatures][:alg_required] || String(params.fetch("alg"))
+          end
+
+          def tag?
+            !options[:signatures][:tag_required] || String(params.fetch("tag"))
+          end
+        end
+
+        module Configuration
+          DEFAULT_OPTIONS = {
+            signatures: {
+              reject_older_than:  900,
+              created_required:   true,
+              nonce_required:     false,
+              alg_required:       false,
+              tag_required:       false,
+              expires_required:   false,
+              keyid_required:     false,
+              covered_components: %w[@method @request-target @authority date],
+              error_response:     {body: [], status: 401, headers: {}}
+            },
+            keys: {}
+          }
+
+          private_constant :DEFAULT_OPTIONS
+
+          private
+
+          def load_options(options)
+            options_from_file = load_options_from_config_file(options)
+            {
+              except:      options[:except]      || options_from_file[:except],
+              default_key: options[:default_key] || options_from_file[:default_key],
+              signatures:
+                DEFAULT_OPTIONS[:signatures]
+                  .merge(options_from_file[:signatures].to_h)
+                  .merge(options[:signatures].to_h),
+              keys:
+                DEFAULT_OPTIONS[:keys]
+                  .merge(options_from_file[:keys].to_h)
+                  .merge(options[:keys].to_h)
+            }
+          end
+
+          def load_options_from_config_file(options)
+            config_path = options[:config_path]
+            YAML.safe_load_file(config_path, symbolize_names: true)
+          rescue
+            {}
+          end
+        end
+
+        module Key
+          private
+
+          def key
+            build_key(params["keyid"])
+          end
+
+          def build_key(keyid)
+            key_data = if keyid.nil? ||
+                (!options[:keys].key?(keyid.to_sym) && options[:default_key])
+              options[:default_key].to_h
+            else
+              options[:keys][keyid.to_sym] || {}
+            end
+
+            if key_data.key?(:path) && !key_data.key?(:material)
+              key_data[:material] = IO.read(key_data[:path]) rescue nil
+            end
+
+            if !key_data || key_data.empty? || !key_data[:material]
+              key_not_found = "Key not found. Signature cannot be verified."
+              raise Linzer::Error.new key_not_found
+            end
+
+            alg = @signature.parameters["alg"] || key_data[:alg] || :unknown
+            instantiate_key(keyid || :default, alg, key_data)
+          end
+
+          def instantiate_key(keyid, alg, key_data)
+            key_methods = {
+              "rsa-pss-sha512"    => :new_rsa_pss_sha512_key,
+              "rsa-v1_5-sha256"   => :new_rsa_v1_5_sha256_key,
+              "hmac-sha256"       => :new_hmac_sha256_key,
+              "ecdsa-p256-sha256" => :new_ecdsa_p256_sha256_key,
+              "ecdsa-p384-sha384" => :new_ecdsa_p384_sha384_key,
+              "ed25519"           => :new_ed25519_public_key
+            }
+            method = key_methods[alg]
+
+            alg_error = "Unsupported or unknown signature algorithm"
+            raise Linzer::Error.new alg_error unless method
+
+            Linzer.public_send(method, key_data[:material], keyid.to_s)
+          end
+        end
+
+        include Parameters
+        include Configuration
+        include Key
+      end
+    end
+  end
+end

data/lib/rack/auth/signature.rb

@@ -1,6 +1,6 @@
 require "linzer"
 require "logger"
-require "yaml"
+require_relative "signature/helpers"
 
 # Rack::Auth::Signature implements HTTP Message Signatures, as per RFC 9421.
 #
@@ -11,9 +11,11 @@ require "yaml"
 module Rack
   module Auth
     class Signature
+      include Helpers
+
       def initialize(app, options = {}, &block)
         @app = app
-        @options = load_options(options)
+        @options = load_options(Hash(options))
         instance_eval(&block) if block
       end
 
@@ -23,7 +25,7 @@ module Rack
         if excluded? || allowed?
           @app.call(env)
         else
-          response = options[:error_response].values
+          response = options[:signatures][:error_response].values
           Rack::Response.new(*response).finish
         end
       end
@@ -39,21 +41,6 @@ module Rack
         has_signature? && acceptable? && verifiable?
       end
 
-      DEFAULT_OPTIONS = {
-        no_older_than: 900,
-        created_required: true,
-        nonce_required:   false,
-        alg_required:     false,
-        tag_required:     false,
-        expires_required: false,
-        keyid_required:   false,
-        known_keys:       {},
-        covered_components: %w[@method @request-target @authority date],
-        error_response: {body: [], status: 401, headers: {}}
-      }
-
-      private_constant :DEFAULT_OPTIONS
-
       attr_reader :request, :options
 
       def params
@@ -65,51 +52,22 @@ module Rack
       end
 
       def has_signature?
-        @message = Linzer::Message.new(request)
-        @signature = Linzer::Signature.build(@message.headers)
-        request.env["rack.signature"] = @signature
+        @signature = build_signature
         (@signature.to_h.keys & %w[signature signature-input]).size == 2
       rescue => ex
         logger.error ex.message
         false
       end
 
-      def created?
-        required = options[:created_required]
-        if required
-          params.key?("created") && Integer(params["created"])
-        else
-          !required
-        end
-      end
-
-      def expires?
-        required = options[:expires_required]
-        if required
-          params.key?("expires") && Integer(params["expires"]) > Time.now.to_i
-        else
-          !required
-        end
-      end
-
-      def keyid?
-        required = options[:keyid_required]
-        required ? params.key?("keyid") : !required
-      end
-
-      def nonce?
-        required = options[:nonce_required]
-        required ? params.key?("nonce") : !required
-      end
+      def build_signature
+        signature_opts = {}
+        label = options[:signatures][:default_label]
+        signature_opts[:label] = label if label
 
-      def alg?
-        required = options[:alg_required]
-        required ? params.key?("alg") : !required
-      end
-
-      def tag?
-        required = options[:tag_required]
-        required ? params.key?("tag") : !required
+        @message = Linzer::Message.new(request)
+        signature = Linzer::Signature.build(@message.headers, **signature_opts)
+        request.env["rack.signature"] = signature
+        signature
       end
 
       def has_required_params?
@@ -121,7 +79,7 @@ module Rack
 
       def has_required_components?
         components         = @signature.components || []
-        covered_components = options[:covered_components]
+        covered_components = options[:signatures][:covered_components]
         warning = "Insufficient coverage by signature. Consult S 7.2.1. in RFC"
         logger.warn warning if covered_components.empty?
         (covered_components || []).all? { |c| components.include?(c) }
@@ -132,74 +90,25 @@ module Rack
       end
 
       def verifiable?
-        verify_opts = {}
-
-        warning = "Risk of signature replay! (Consult S 7.2.2. in RFC)"
-        logger.warn warning unless options[:no_older_than]
-
-        if options[:no_older_than]
-          age = Integer(options[:no_older_than])
-          verify_opts[:no_older_than] = age
-        end
-
+        verify_opts = build_and_check_verify_opts || {}
         Linzer.verify(key, @message, @signature, **verify_opts)
       rescue => ex
         logger.error ex.message
         false
       end
 
-      def key
-        build_key(params["keyid"] || :default)
-      end
+      def build_and_check_verify_opts
+        verify_opts = {}
+        reject_older = options[:signatures][:reject_older_than]
+        warning = "Risk of signature replay! (Consult S 7.2.2. in RFC)"
+        logger.warn warning unless reject_older
 
-      def build_key(keyid)
-        material = if keyid == :default
-          options[:default_key]
-        else
-          key_data = options[:known_keys][keyid] || {}
-          if !key_data.key?("key") && key_data.key?("path")
-            key_data["key"] = IO.read(key_data["path"]) rescue nil
-          end
-          key_data
+        if reject_older
+          age = Integer(reject_older)
+          verify_opts[:no_older_than] = age
         end
 
-        key_not_found = "Key not found. Signature cannot be verified."
-        raise Linzer::Error.new key_not_found if !material || !material["key"]
-
-        alg = @signature.parameters["alg"] || material["alg"] || :unknown
-        instantiate_key(keyid, alg, material)
-      end
-
-      def instantiate_key(keyid, alg, material)
-        key_methods = {
-          "rsa-pss-sha512"    => :new_rsa_pss_sha512_key,
-          "rsa-v1_5-sha256"   => :new_rsa_v1_5_sha256_key,
-          "hmac-sha256"       => :new_hmac_sha256_key,
-          "ecdsa-p256-sha256" => :new_ecdsa_p256_sha256_key,
-          "ecdsa-p384-sha384" => :new_ecdsa_p384_sha384_key,
-          "ed25519"           => :new_ed25519_public_key
-        }
-        method = key_methods[alg]
-
-        alg_error = "Unsupported or unknown signature algorithm"
-        raise Linzer::Error.new alg_error unless method
-
-        Linzer.public_send(method, material["key"], keyid.to_s)
-      end
-
-      def load_options(options)
-        DEFAULT_OPTIONS
-          .merge(load_options_from_config_file(options))
-          .merge(Hash(options)) || {}
-      end
-
-      def load_options_from_config_file(options)
-        config_path = options[:config_path]
-        YAML
-          .safe_load_file(config_path)
-          .transform_keys(&:to_sym)
-      rescue
-        {}
+        verify_opts
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: linzer
 version: !ruby/object:Gem::Version
-  version: 0.7.0.beta1
+  version: 0.7.0.beta2
 platform: ruby
 authors:
 - Miguel Landaeta
@@ -157,6 +157,7 @@ files:
 - lib/linzer/verifier.rb
 - lib/linzer/version.rb
 - lib/rack/auth/signature.rb
+- lib/rack/auth/signature/helpers.rb
 homepage: https://github.com/nomadium/linzer
 licenses:
 - MIT