linzer 0.6.4 → 0.7.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bff7f24f79244ceffa58e5b005b45b2384b34f2d23eda4c0a613060c4f708fa4
-  data.tar.gz: bfee805d74cf0e1fc3d3588ec6eac8a1de5b96a16021198d016f0be9fb48e371
+  metadata.gz: 9a19b05f41aa933779f504056b56b00fc1a8a6cda19bb26065dce56177caf0c2
+  data.tar.gz: 25d7d8b4afbd60a3e6e872064d92f9be22670466292e23a6ba8010ca546cdf23
 SHA512:
-  metadata.gz: d62f773a0d20b09bb97987180f251a70b4db5c29eb4ecf2112e486c9169e418085823c813fa68e4063347d421328f171604c3f82bdf1b6ffae0385bfc41fd8ce
-  data.tar.gz: 0e53c41f9485a8028f11f67e368ca0ec60a82f8e795973d258fb96a57cfdcfe085308f4cd2eb0ac55fe8b5ee39c1a4f8d56d3d9d09fa57ee720eda17831e66ae
+  metadata.gz: 527fd9a73a1605b706fc7ca597ce14f4f5c95be099907bf61832aa698b11fe51dbf25a5eaf70d48d7c6715c91c27bfa391482a88a67f0e932c5f60ff8f3f16df
+  data.tar.gz: 2b30454801734973711afe81559ad18f09f6d08f473796241d56e1b13d5619971a697945703b85012e18ae969059ca5a3718e677fc71716151bd46e795eac8a7

data/.standard.yml

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

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [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.
+  Pull request [#10](https://github.com/nomadium/linzer/pull/10)
+  by [oneiros](https://github.com/oneiros).
+
 ## [0.6.4] - 2025-04-04
 
 - Allow validating the `created` parameter to mitigate the

data/README.md

@@ -21,6 +21,33 @@ Or just `gem install linzer`.
 
 ## Usage
 
+### TL;DR: I just want to protect my application!!
+
+Add the following middleware to you run Rack application, e.g.:
+
+```ruby
+# config.ru
+use Rack::Auth::Signature, except: "/login",
+  default_key: {"key" => IO.read("app/config/pubkey.pem"), "alg" => "ed25519"}
+```
+
+or on more complex scenarios:
+
+```ruby
+# config.ru
+use Rack::Auth::Signature, except: "/login",
+  config_path: "app/configuration/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
@@ -160,7 +187,7 @@ pp signature.to_h
 
 For now, to consult additional details just take a look at source code and/or the unit tests.
 
-Please note that is still early days and extensive testing is still ongoing. For now only the following algorithms are supported: RSASSA-PSS using SHA-512, HMAC-SHA256, Ed25519 and ECDSA (P-256 and P-384 curves).
+Please note that is still early days and extensive testing is still ongoing. For now the following algorithms are supported: RSASSA-PSS using SHA-512, RSASSA-PKCS1-v1_5 using SHA-256, HMAC-SHA256, Ed25519 and ECDSA (P-256 and P-384 curves). JSON Web Signature (JWS) algorithms mentioned in the RFC are not supported yet.
 
 I'll be expanding the library to cover more functionality specified in the RFC
 in subsequent releases.

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.beta1"

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,26 @@
+---
+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:
+  foo:
+    alg: ed25519
+    key: |
+      -----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

data/examples/sinatra/myapp.rb

@@ -0,0 +1,10 @@
+# myapp.rb
+require "sinatra"
+
+get "/" do
+  "Hello world!"
+end
+
+get "/protected" do
+  "secure area"
+end

data/lib/linzer/key/helper.rb

@@ -4,24 +4,38 @@ module Linzer
   class Key
     module Helper
       def generate_rsa_pss_sha512_key(size, key_id = nil)
-        material = OpenSSL::PKey::RSA.generate(size)
-        Linzer::RSA::Key.new(material, id: key_id, digest: "SHA512")
+        material = OpenSSL::PKey.generate_key("RSASSA-PSS")
+        Linzer::RSAPSS::Key.new(material, id: key_id, digest: "SHA512")
       end
 
       def new_rsa_pss_sha512_key(material, key_id = nil)
         key = OpenSSL::PKey.read(material)
-        Linzer::RSA::Key.new(key, id: key_id, digest: "SHA512")
+        Linzer::RSAPSS::Key.new(key, id: key_id, digest: "SHA512")
       end
 
+      # XXX: investigate: was this method made redundant after:
+      # https://github.com/nomadium/linzer/pull/10
       def new_rsa_pss_sha512_public_key(material, key_id = nil)
         key = OpenSSL::PKey::RSA.new(material)
-        Linzer::RSA::Key.new(key, id: key_id, digest: "SHA512")
+        Linzer::RSAPSS::Key.new(key, id: key_id, digest: "SHA512")
       end
 
-      # XXX: to-do
-      # Linzer::RSA::Key
-      # def new_rsa_v1_5_sha256_key
-      # def generate_rsa_v1_5_sha256_key
+      def generate_rsa_v1_5_sha256_key(size, key_id = nil)
+        material = OpenSSL::PKey::RSA.generate(size)
+        Linzer::RSA::Key.new(material, id: key_id, digest: "SHA256")
+      end
+
+      def new_rsa_v1_5_sha256_key(material, key_id = nil)
+        key = OpenSSL::PKey.read(material)
+        Linzer::RSA::Key.new(key, id: key_id, digest: "SHA256")
+      end
+
+      # XXX: investigate: was this method made redundant after:
+      # https://github.com/nomadium/linzer/pull/10
+      def new_rsa_v1_5_sha256_public_key(material, key_id = nil)
+        key = OpenSSL::PKey.read(material)
+        Linzer::RSA::Key.new(key, id: key_id, digest: "SHA256")
+      end
 
       def generate_hmac_sha256_key(key_id = nil)
         material = OpenSSL::Random.random_bytes(64)

data/lib/linzer/rsa.rb

@@ -15,13 +15,7 @@ module Linzer
 
       def verify(signature, data)
         # XXX: should check if the key is usable for verifying
-        return true if @material.verify_pss(
-          @params[:digest],
-          signature,
-          data,
-          salt_length: @params[:salt_length] || :auto,
-          mgf1_hash:   @params[:digest]
-        )
+        return true if @material.verify(@params[:digest], signature, data)
         false
       end
     end

data/lib/linzer/rsa_pss.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Linzer
+  module RSAPSS
+    SALT_LENGTH = 64
+
+    class Key < Linzer::Key
+      def validate
+        super
+        validate_digest
+      end
+
+      def sign(data)
+        # XXX: should check if the key is usable for signing
+        @material.sign(@params[:digest], data, signature_options)
+      end
+
+      def verify(signature, data)
+        # XXX: should check if the key is usable for verifying
+        return true if @material.verify(
+          @params[:digest],
+          signature,
+          data,
+          signature_options
+        )
+        false
+      end
+
+      private
+
+      def signature_options
+        {
+          rsa_padding_mode: "pss",
+          rsa_pss_saltlen: @params[:salt_length] || SALT_LENGTH,
+          rsa_mgf1_md:   @params[:digest]
+        }
+      end
+    end
+  end
+end

data/lib/linzer/version.rb

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

data/lib/linzer.rb

@@ -14,12 +14,14 @@ require_relative "linzer/message"
 require_relative "linzer/signature"
 require_relative "linzer/key"
 require_relative "linzer/rsa"
+require_relative "linzer/rsa_pss"
 require_relative "linzer/hmac"
 require_relative "linzer/ed25519"
 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.rb

@@ -0,0 +1,206 @@
+require "linzer"
+require "logger"
+require "yaml"
+
+# 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
+      def initialize(app, options = {}, &block)
+        @app = app
+        @options = load_options(options)
+        instance_eval(&block) if block
+      end
+
+      def call(env)
+        @request = Rack::Request.new(env)
+
+        if excluded? || allowed?
+          @app.call(env)
+        else
+          response = options[: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
+
+      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
+        @signature.parameters || {}
+      end
+
+      def logger
+        @logger ||= request.logger || ::Logger.new($stderr)
+      end
+
+      def has_signature?
+        @message = Linzer::Message.new(request)
+        @signature = Linzer::Signature.build(@message.headers)
+        request.env["rack.signature"] = @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 alg?
+        required = options[:alg_required]
+        required ? params.key?("alg") : !required
+      end
+
+      def tag?
+        required = options[:tag_required]
+        required ? params.key?("tag") : !required
+      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[: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 = {}
+
+        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
+
+        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_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
+        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
+        {}
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: linzer
 version: !ruby/object:Gem::Version
-  version: 0.6.4
+  version: 0.7.0.beta1
 platform: ruby
 authors:
 - Miguel Landaeta
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openssl
@@ -104,7 +103,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 3.1.2
-description:
+- !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: []
@@ -118,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
@@ -129,10 +151,12 @@ files:
 - lib/linzer/request.rb
 - lib/linzer/response.rb
 - lib/linzer/rsa.rb
+- lib/linzer/rsa_pss.rb
 - lib/linzer/signature.rb
 - lib/linzer/signer.rb
 - lib/linzer/verifier.rb
 - lib/linzer/version.rb
+- lib/rack/auth/signature.rb
 homepage: https://github.com/nomadium/linzer
 licenses:
 - MIT
@@ -140,7 +164,6 @@ metadata:
   homepage_uri: https://github.com/nomadium/linzer
   source_code_uri: https://github.com/nomadium/linzer
   changelog_uri: https://github.com/nomadium/linzer/blob/master/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -155,8 +178,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.3
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: An implementation of HTTP Messages Signatures (RFC9421)
 test_files: []