linzer 0.6.5 → 0.7.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d5b1a0dfcd7d402e3a5bf2e22102271e3273e1f7092e4dad09ae7078e04dcf3
-  data.tar.gz: 197933c6728e55678e7f29e5161b57fecd0ca39bacb586260412674a538cd8b1
+  metadata.gz: fd7b5e233ec42d94c7040f774097c612850eef9c5795a2c8d3251bc618c8df5f
+  data.tar.gz: 53cc818e2fc68fe1f6b3c89414a5b0d2393e1b8cfa8e4c9f3ba9076ce537f81c
 SHA512:
-  metadata.gz: f6da1cd0829f06c15f1a5cf66af191836294ffeea666e15f969f28c7171bf2b8e887b1fb5aa405fbfc7c840719ce82cc6cdae3b7238f987bb00f6c71e238c930
-  data.tar.gz: 047a03b94451dcffe5982165bc14acc7c6419fe4d8ff9f72e2d4510a77fae87c5960fabdaa0ff129d89724b0185a37454e3a6d9ec6ea903192eadc013e1abb64
+  metadata.gz: 93e5fb0d4fd0cd534691102a02efa8ae14589d12ee3636f86d10d19e57104b1bb122f950c9191c5fb40264fc453a31d33aa1369fac0fe34451e74108ce9c6a5c
+  data.tar.gz: e5b12b53e46f7958c560cb579111c14eab85da6a047effcdb599d39f955fe38b89175faef1937a963890c8d8254763c54314ea95c4eff70815fc0c0b8c396551

data/.standard.yml

@@ -8,3 +8,4 @@ ignore:
     - Layout/HashAlignment
     - Layout/ArgumentAlignment
     - Style/EmptyCaseCondition
+    - Style/RescueModifier

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [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.
+
 ## [0.6.5] - 2025-04-09
 
 - Add support for RSA (RSASSA-PKCS1-V1_5) and improve RSASSA-PSS handling.

data/README.md

@@ -21,6 +21,43 @@ Or just `gem install linzer`.
 
 ## Usage
 
+### TL;DR: I just want to protect my application!!
+
+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: {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:
+
+```ruby
+# config.ru
+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
+look at
+[examples/sinatra/http-signatures.yml](https://github.com/nomadium/linzer/tree/master/examples/sinatra/http-signatures.yml) to get started and/or
+[lib/rack/auth/signature.rb](https://github.com/nomadium/linzer/tree/master/lib/rack/auth/signature.rb) for full implementation details.
+
+To learn about more specific scenarios or use cases, keep reading on below.
+
 ### To sign a HTTP message:
 
 ```ruby

data/examples/sinatra/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "sinatra",      "~> 4.0"
+gem "rackup",       "~> 2.1"
+gem "webrick",      "~> 1.9"
+gem "rack-contrib", "~> 2.4"
+gem "linzer",       "~> 0.7.0.beta2"

data/examples/sinatra/config.ru

@@ -0,0 +1,11 @@
+require "rack"
+require "rack/contrib"
+require "linzer"
+require_relative "myapp"
+
+set :root, File.dirname(__FILE__)
+
+use Rack::Auth::Signature, except: "/",
+  config_path: "http-signatures.yml"
+
+run Sinatra::Application

data/examples/sinatra/http-signatures.yml

@@ -0,0 +1,33 @@
+---
+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
+    material: |
+      -----BEGIN PUBLIC KEY-----
+      MCowBQYDK2VwAyEAMEH9bSanwgAWE5qxUEaXjK6qei8z2hiHT0nlr7ljG0Y=
+      -----END PUBLIC KEY-----
+  bar:
+    alg: rsa-pss-sha512
+    path: pubkey_rsa.pem
+  baz:
+    alg: hmac-sha256
+    path: app.secret

data/examples/sinatra/myapp.rb

@@ -0,0 +1,21 @@
+# myapp.rb
+require "sinatra"
+
+get "/" do
+  "Hello world!"
+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.6.5"
+  VERSION = "0.7.0.beta2"
 end

data/lib/linzer.rb

@@ -21,6 +21,7 @@ require_relative "linzer/ecdsa"
 require_relative "linzer/key/helper"
 require_relative "linzer/signer"
 require_relative "linzer/verifier"
+require_relative "rack/auth/signature"
 
 module Linzer
   class Error < StandardError; 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

@@ -0,0 +1,115 @@
+require "linzer"
+require "logger"
+require_relative "signature/helpers"
+
+# Rack::Auth::Signature implements HTTP Message Signatures, as per RFC 9421.
+#
+# Initialize with the Rack application that you want protecting.
+# A hash with options and a block can be passed to customize, enhance
+# or disable security checks applied to incoming requests.
+#
+module Rack
+  module Auth
+    class Signature
+      include Helpers
+
+      def initialize(app, options = {}, &block)
+        @app = app
+        @options = load_options(Hash(options))
+        instance_eval(&block) if block
+      end
+
+      def call(env)
+        @request = Rack::Request.new(env)
+
+        if excluded? || allowed?
+          @app.call(env)
+        else
+          response = options[:signatures][:error_response].values
+          Rack::Response.new(*response).finish
+        end
+      end
+
+      private
+
+      def excluded?
+        return false if !request
+        Array(options[:except]).include?(request.path_info)
+      end
+
+      def allowed?
+        has_signature? && acceptable? && verifiable?
+      end
+
+      attr_reader :request, :options
+
+      def params
+        @signature.parameters || {}
+      end
+
+      def logger
+        @logger ||= request.logger || ::Logger.new($stderr)
+      end
+
+      def has_signature?
+        @signature = build_signature
+        (@signature.to_h.keys & %w[signature signature-input]).size == 2
+      rescue => ex
+        logger.error ex.message
+        false
+      end
+
+      def build_signature
+        signature_opts = {}
+        label = options[:signatures][:default_label]
+        signature_opts[:label] = label if label
+
+        @message = Linzer::Message.new(request)
+        signature = Linzer::Signature.build(@message.headers, **signature_opts)
+        request.env["rack.signature"] = signature
+        signature
+      end
+
+      def has_required_params?
+        created? && expires? && keyid? && nonce? && alg? && tag?
+      rescue => ex
+        logger.error ex.message
+        false
+      end
+
+      def has_required_components?
+        components         = @signature.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) }
+      end
+
+      def acceptable?
+        has_required_params? && has_required_components?
+      end
+
+      def verifiable?
+        verify_opts = build_and_check_verify_opts || {}
+        Linzer.verify(key, @message, @signature, **verify_opts)
+      rescue => ex
+        logger.error ex.message
+        false
+      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
+
+        if reject_older
+          age = Integer(reject_older)
+          verify_opts[:no_older_than] = age
+        end
+
+        verify_opts
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: linzer
 version: !ruby/object:Gem::Version
-  version: 0.6.5
+  version: 0.7.0.beta2
 platform: ruby
 authors:
 - Miguel Landaeta
 bindir: exe
 cert_chain: []
-date: 2025-04-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openssl
@@ -103,6 +103,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 3.1.2
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.0
 email:
 - miguel@miguel.cc
 executables: []
@@ -116,6 +136,10 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/sinatra/Gemfile
+- examples/sinatra/config.ru
+- examples/sinatra/http-signatures.yml
+- examples/sinatra/myapp.rb
 - lib/linzer.rb
 - lib/linzer/common.rb
 - lib/linzer/ecdsa.rb
@@ -132,6 +156,8 @@ files:
 - lib/linzer/signer.rb
 - 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
@@ -153,7 +179,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: An implementation of HTTP Messages Signatures (RFC9421)
 test_files: []