linzer 0.7.0.beta1 → 0.7.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a19b05f41aa933779f504056b56b00fc1a8a6cda19bb26065dce56177caf0c2
-  data.tar.gz: 25d7d8b4afbd60a3e6e872064d92f9be22670466292e23a6ba8010ca546cdf23
+  metadata.gz: 65ccb6f89aab47730e202a8ad376b2ceb310213b2a140d194b2b6fd285aa710f
+  data.tar.gz: 485efd259e353048041528c38f0072945592cfe6f8d4c4e6ea20af5546e6cb94
 SHA512:
-  metadata.gz: 527fd9a73a1605b706fc7ca597ce14f4f5c95be099907bf61832aa698b11fe51dbf25a5eaf70d48d7c6715c91c27bfa391482a88a67f0e932c5f60ff8f3f16df
-  data.tar.gz: 2b30454801734973711afe81559ad18f09f6d08f473796241d56e1b13d5619971a697945703b85012e18ae969059ca5a3718e677fc71716151bd46e795eac8a7
+  metadata.gz: a01a27867e6dd628365268f1106880b7f61ad80b4d314ea336e21e4f1a4edbb17394d0c7da4f23256566e34a6acb2e6eec54680461141d917189a37219d3c84e
+  data.tar.gz: 2efef6b1fcad53964e1f54c8f1453b2ad3aa481ca98960ada2e735439d0736624118a99ab58d1f73fdef517f9802e1453215e17bfc660e56dae81cd5b044769d

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.7.0.beta3] - 2025-05-06 (aka the ["MiniDebConf Hamburg 2025"](https://wiki.debian.org/DebianEvents/de/2025/MiniDebConfHamburg) release)
+
+- Refactor to improve Linzer APIs and streamline its usage along with different
+  HTTP libraries.
+
+## [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 your 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
@@ -48,46 +58,40 @@ look at
 
 To learn about more specific scenarios or use cases, keep reading on below.
 
-### To sign a HTTP message:
+### To sign a HTTP request:
 
 ```ruby
 key = Linzer.generate_ed25519_key
 # => #<Linzer::Ed25519::Key:0x00000fe13e9bd208
 
-headers = {
-  "date" => "Fri, 23 Feb 2024 17:57:23 GMT",
-  "x-custom-header" => "foo"
-}
-
-request = Linzer.new_request(:post, "/some_uri", {}, headers)
-# => #<Rack::Request:0x0000000104c1c8c0
-#       @env={"HTTP_DATE"=>"Fri, 23 Feb 2024 17:57:23 GMT", "HTTP_X_CUSTOM..."
-#       @params=nil>
-
-message = Linzer::Message.new(request)
-# => #<Linzer::Message:0x0000000104afa960
-#       @operation=#<Rack::Request:0x00000001049754a0
-#       @env={"HTTP_DATE"=>"Fri, 23 Feb 2024 17:57:23 GMT", "HTTP_X_CUSTOM..."
-#       @params=nil>>
-
-fields = %w[date x-custom-header @method @path]
-
-signature = Linzer.sign(key, message, fields)
-# => #<Linzer::Signature:0x0000000111f77ad0 ...
-
-pp signature.to_h
-# => {"signature"=>"sig1=:Cv1TUCxUpX+5SVa7pH0Xh...",
-#  "signature-input"=>"sig1=(\"date\" \"x-custom-header\" ..."}
+uri = URI("https://example.org/api/task")
+request = Net::HTTP::Get.new(uri)
+request["date"] = Time.now.to_s
+
+Linzer.sign!(
+  request,
+  key: key,
+  components: %w[@method @request-target date],
+  label: "sig1",
+  params: {
+    created: Time.now.to_i
+  }
+)
+
+request["signature"]
+# => "sig1=:Cv1TUCxUpX+5SVa7pH0Xh..."
+request["signature-input"]
+# => "sig1=(\"@method\" \"@request-target\" \"date\" ..."}
 ```
 
-### Use the message signature with any HTTP client:
+### Use the signed request with an HTTP client:
 
 ```ruby
 require "net/http"
 
-http = Net::HTTP.new("localhost", 9292)
+http = Net::HTTP.new(uri.host, uri.port)
 http.set_debug_output($stderr)
-response = http.post("/some_uri", "data", headers.merge(signature.to_h))
+response = http.request(request)
 # opening connection to localhost:9292...
 # opened
 # <- "POST /some_uri HTTP/1.1\r\n
@@ -121,7 +125,123 @@ response = http.post("/some_uri", "data", headers.merge(signature.to_h))
 # => #<Net::HTTPOK 200 OK readbody=true>
 ```
 
-### To verify a valid signature:
+### To verify an incoming request on the server side:
+
+The middleware `Rack::Auth::Signature` can be used for this scenario
+[as shown above](#tldr-i-just-want-to-protect-my-application).
+
+Or directly in the application controller (or routes), the incoming request can
+be verified with the following approach:
+
+```ruby
+post "/foo" do
+  request
+  # =>
+  # #<Sinatra::Request:0x000000011e5a5d60
+  #  @env=
+  #   {"GATEWAY_INTERFACE" => "CGI/1.1",
+  #   "PATH_INFO" => "/api",
+  # ...
+
+  result = Linzer.verify!(request, key: some_client_key)
+  # => true
+  ...
+end
+```
+
+If the signature is missing or invalid, the verification method will raise an
+exception with a message clarifying why the request signature failed verification.
+
+Also, for additional flexibility on the server side, the method above can take
+a block with the `keyid` parameter extracted from the signature (if any) as argument.
+This can be useful to retrieve key data from databases/caches on the server side, e.g.:
+
+```ruby
+get "/bar" do
+  ...
+  result = Linzer.verify!(request) do |keyid|
+    retrieve_pubkey_from_db(db_client, keyid)
+  end
+  # => true
+  ...
+end
+```
+
+### To verify a received response on the client side:
+
+It's similar to verifying requests, the same method is used, see example below:
+
+```ruby
+response
+# => #<Net::HTTPOK 200 OK readbody=true>
+response.body
+# => "protected"
+pubkey = Linzer.new_ed25519_key(IO.read("pubkey.pem"))
+result = Linzer.verify!(response, key: pubkey, no_older_than: 600)
+# => true
+```
+
+### To sign an outgoing response on the server side:
+
+Again, the same principle used to sign outgoing requests, the same method is used,
+see example below:
+
+```ruby
+put "/baz" do
+  ...
+  response
+  # => #<Sinatra::Response:0x0000000109ac40b8 ...
+  response.headers["x-custom-app-header"] = "..."
+  Linzer.sign!(response,
+    key: my_key,
+    components: %w[@status content-type content-digest x-custom-app-header],
+    label: "sig1",
+    params: {
+      created: Time.now.to_i
+    }
+  )
+  response["signature"]
+  # => "sig1=:2TPCzD4l48bg6LMcVXdV9u..."
+  response["signature-input"]
+  # => "sig1=(\"@status\" \"content-type\" \"content-digest\"..."
+  ...
+end
+```
+
+### What do you do if you want to sign/verify requests and responses with your preferred HTTP ruby library/framework (not using Rack or `Net::HTTP`, for example)?
+
+You can provide an adapter class and then register it with this library.
+For guidance on how to implement such adapters, you can consult an
+[example adapter for http gem response](https://github.com/nomadium/linzer/blob/master/lib/linzer/message/adapter/http_gem/response.rb)
+included with this gem or the ones
+[provided out of the box](https://github.com/nomadium/linzer/blob/master/lib/linzer/message/adapter).
+
+For how to register a custom adapter and how to verify signatures in a response,
+see this example:
+
+```ruby
+Linzer::Message.register_adapter(HTTP::Response, MyOwnResponseAdapter)
+response = HTTP.get("http://www.example.com/api/service/task")
+# => #<HTTP::Response/1.1 200 OK ...
+response["signature"]
+=> "sig1=:oqzDlQmfejfT..."
+response["signature-input"]
+=> "sig1=(\"@status\" \"foo\");created=1746480237"
+result = Linzer.verify!(response, key: my_key)
+# => true
+```
+---
+
+Furthermore, on some low-level scenarios where a user wants or needs additional
+control on how the signing and verification routines are performed, Linzer allows
+to manipulate instances of internal HTTP messages (requests & responses, see
+`Linzer::Message` class and available adapters), signature objects
+(`Linzer::Signature`) and how to register additional message adapters for any
+HTTP ruby library not supported out of the box by this gem.
+
+See below for a few examples of these scenarios.
+
+#### To verify a valid signature:
 
 ```ruby
 test_ed25519_key_pub = key.material.public_to_pem
@@ -130,12 +250,6 @@ test_ed25519_key_pub = key.material.public_to_pem
 pubkey = Linzer.new_ed25519_public_key(test_ed25519_key_pub, "some-key-ed25519")
 # => #<Linzer::Ed25519::Key:0x00000fe19b9384b0
 
-# if you have to, there is a helper method to build a request object on the server side
-# although any standard Ruby web server or framework (Sinatra, Rails, etc) should expose
-# a request object and this should not be required for most cases.
-#
-# request = Linzer.new_request(:post, "/some_uri", {}, headers)
-
 message = Linzer::Message.new(request)
 
 signature = Linzer::Signature.build(message.headers)
@@ -153,14 +267,14 @@ Linzer.verify(pubkey, message, signature, no_older_than: 500)
 `no_older_than` expects a number of seconds, but you can pass anything that to responds to `#to_i`, including an `ActiveSupport::Duration`.
 `::verify` will raise if the `created` parameter of the signature is older than the given number of seconds.
 
-### What if an invalid signature if verified?
+#### What if an invalid signature if verified?
 
 ```ruby
 result = Linzer.verify(pubkey, message, signature)
 lib/linzer/verifier.rb:38:in `verify_or_fail': Failed to verify message: Invalid signature. (Linzer::Error)
 ```
 
-### HTTP responses are also supported
+#### HTTP responses are also supported
 
 HTTP responses can also be signed and verified in the same way as requests.
 

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/message/adapter/abstract.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      class Abstract
+        def initialize(operation, **options)
+          raise Linzer::Error, "Cannot instantiate an abstract class!"
+        end
+
+        def request?
+          self.class.to_s.include?("Request")
+        end
+
+        def response?
+          self.class.to_s.include?("Response")
+        end
+
+        # XXX: attached request as specified in RFC has to be tested for Net::HTTP classes
+        # and custom HTTP message classes
+        def attached_request?
+          response? && !!@attached_request
+        end
+
+        def field?(f)
+          !!self[f]
+        end
+
+        def [](field_name)
+          name = parse_field_name(field_name)
+          return nil if name.nil?
+
+          if field_name.start_with?("@")
+            retrieve(name, :derived)
+          else
+            retrieve(name, :field)
+          end
+        end
+
+        def headers
+          raise Linzer::Error, "Sub-classes are required to implement this method!"
+        end
+
+        def attach!(signature)
+          raise Linzer::Error, "Sub-classes are required to implement this method!"
+        end
+
+        private
+
+        def parse_field_name(field_name)
+          if field_name&.start_with?("@")
+            Starry.parse_item(field_name[1..])
+          else
+            Starry.parse_item(field_name)
+          end
+        rescue => _
+          nil
+        end
+
+        def validate_attached_request(message)
+          msg = "The attached message is not a valid HTTP request!"
+          raise Linzer::Error, msg unless message.request?
+        end
+
+        def validate_parameters(name, method)
+          has_unknown = name.parameters.any? { |p, _| !KNOWN_PARAMETERS.include?(p) }
+          return nil if has_unknown
+
+          has_name = name.parameters["name"]
+          has_req  = name.parameters["req"]
+          has_sf   = name.parameters["sf"] || name.parameters.key?("key")
+          has_bs   = name.parameters["bs"]
+          value    = name.value
+
+          # Section 2.2.8 of RFC 9421
+          return nil if has_name && value != :"query-param"
+
+          # No derived values come from trailers section
+          return nil if method == :derived && name.parameters["tr"]
+
+          # From: 2.1. HTTP Fields:
+          # The bs parameter, which requires the raw bytes of the field values
+          # from the message, is not compatible with the use of the sf or key
+          # parameters, which require the parsed data structures of the field
+          # values after combination
+          return nil if has_sf && has_bs
+
+          # req param only makes sense on responses with an associated request
+          # return nil if has_req && (!response? || !attached_request?)
+          return nil if has_req && !response?
+
+          name
+        end
+
+        KNOWN_PARAMETERS = %w[sf key bs req tr name]
+        private_constant :KNOWN_PARAMETERS
+
+        def retrieve(name, method)
+          if !name.parameters.empty?
+            valid_params = validate_parameters(name, method)
+            return nil if !valid_params
+          end
+
+          has_req = name.parameters["req"]
+          has_sf  = name.parameters["sf"] || name.parameters.key?("key")
+          has_bs  = name.parameters["bs"]
+
+          if has_req
+            name.parameters.delete("req")
+            return req(name, method)
+          end
+
+          value = send(method, name)
+
+          case
+          when has_sf
+            key = name.parameters["key"]
+            sf(value, key)
+          when has_bs then bs(value)
+          else value
+          end
+        end
+
+        def sf(value, key = nil)
+          dict = Starry.parse_dictionary(value)
+
+          if key
+            obj = dict[key]
+            Starry.serialize(obj.is_a?(Starry::InnerList) ? [obj] : obj)
+          else
+            Starry.serialize(dict)
+          end
+        end
+
+        def bs(value)
+          Starry.serialize(value.encode(Encoding::ASCII_8BIT))
+        end
+
+        def tr(trailer)
+          @operation.body.trailers[trailer.value.to_s]
+        end
+
+        def req(field, method)
+          case method
+          when :derived then @attached_request["@#{field}"]
+          when :field   then @attached_request[field.to_s]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter/http_gem/response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Example HTTP message adapter for HTTP::Response class from http ruby gem.
+# https://github.com/httprb/http
+# It's not required automatically to avoid making http gem a dependency.
+#
+module Linzer
+  class Message
+    module Adapter
+      module HTTPGem
+        class Response < Abstract
+          def initialize(operation, **options)
+            @operation = operation
+            freeze
+          end
+
+          def headers
+            @operation.headers
+          end
+
+          # XXX: this implementation is incomplete, e.g.: ;tr parameter is not supported yet
+          def [](field_name)
+            return @operation.code if field_name == "@status"
+            @operation[field_name]
+          end
+
+          def attach!(signature)
+            signature.to_h.each { |h, v| @operation[h] = v }
+            @operation
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter/net_http/request.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Linzer
+  class Message
+    module Adapter
+      module NetHTTP
+        class Request < Abstract
+          def initialize(operation, **options)
+            @operation = operation
+            freeze
+          end
+
+          def headers
+            @operation.each_header.to_h
+          end
+
+          def attach!(signature)
+            signature.to_h.each { |h, v| @operation[h] = v }
+            @operation
+          end
+
+          private
+
+          def derived(name)
+            case name.value
+            when :method           then @operation.method
+            when :"target-uri"     then @operation.uri.to_s
+            when :authority        then @operation.uri.authority.downcase
+            when :scheme           then @operation.uri.scheme.downcase
+            when :"request-target" then @operation.uri.request_uri
+            when :path             then @operation.uri.path
+            when :query            then "?%s" % String(@operation.uri.query)
+            when :"query-param"    then query_param(name)
+            end
+          end
+
+          def query_param(name)
+            param_name = name.parameters["name"]
+            return nil if !param_name
+            decoded_param_name = URI.decode_uri_component(param_name)
+            params = CGI.parse(@operation.uri.query)
+            URI.encode_uri_component(params[decoded_param_name]&.first)
+          end
+
+          def field(name)
+            has_tr = name.parameters["tr"]
+            return nil if has_tr # HTTP requests don't have trailer fields
+            value = @operation[name.value.to_s]
+            value.dup&.strip
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter/net_http/response.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      module NetHTTP
+        class Response < Abstract
+          def initialize(operation, **options)
+            @operation = operation
+            attached_request = options[:attached_request]
+            @attached_request = attached_request ? Message.new(attached_request) : nil
+            validate_attached_request @attached_request if @attached_request
+            freeze
+          end
+
+          def headers
+            @operation.each_header.to_h
+          end
+
+          # XXX: this implementation is incomplete, e.g.: ;tr parameter is not supported yet
+          def [](field_name)
+            return @operation.code.to_i if field_name == "@status"
+            @operation[field_name]
+          end
+
+          def attach!(signature)
+            signature.to_h.each { |h, v| @operation[h] = v }
+            @operation
+          end
+        end
+      end
+    end
+  end
+end