linzer 0.4.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e05d05474d794c882d28a6fb83949147497218f141ae1e40e6c07e750407b421
-  data.tar.gz: 58b26e247acd0ca13e9029ace69ebb7459f1639b7908733e07ac88566ac255d1
+  metadata.gz: 1955734eb1a8115753448b579b0cbe84f7d1ad247677ae20dd49495841b4aef3
+  data.tar.gz: abf9b2fbc465f10210c77f3d29e10c7e15af26a5badba90516f0b96050e3a548
 SHA512:
-  metadata.gz: 3af97f2888d5c4bd40900c490945590077604b93c954819c9308d2ab8fe767c491a08d2cbe5054aaced580a4da568a1d1cf11f82048048532feb5150dd59dfea
-  data.tar.gz: b4a47fd541623baef9582cc0b361975b504cc7824fd926f47f56f7f692f6a6d8dec0d8e4afdb5e64967d6e1d7a2107656165b95f383af5e902bddd26f0efe387
+  metadata.gz: 5263ec042dd91dc5bc434f4bbccc8f17d0ec52c751b7b9adec613c87efa180175cc7e5b4f47da007e6e61298a2b153f9ca05250ba3d55786c2d5609725233903
+  data.tar.gz: 45ad9720b910f441bf36f9766ec10eaaab64fb7a36f420b947a5170d9cae0d18d540f380996eba2265b6faa0df0b9537fb1c8b2b2e58c94bab45abcaccb19112

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.5.1] - 2024-04-01
+
+- Add support for additional derived components:
+  @target-uri, @scheme, @request-target, @query and @query-param.
+
+## [0.5.0] - 2024-03-30
+
+- Build Linzer::Message instances from Rack request and response objects
+  instead of unspecified/ad-hoc hashes with HTTP request and
+  response parameters.
+
+- Update README examples.
+
 ## [0.4.1] - 2024-03-25
 
 - Fix one-off error on ECDSA P-256 and P-384 curve signature generation.

data/README.md

@@ -1,4 +1,11 @@
-# Linzer
+# Linzer [![Latest Version][gem-badge]][gem-link] [![License: MIT][license-image]][license-link] [![CI Status][ci-image]][ci-link]
+
+[gem-badge]: https://badge.fury.io/rb/linzer.svg
+[gem-link]: https://rubygems.org/gems/linzer
+[license-image]: https://img.shields.io/badge/license-MIT-blue.svg
+[license-link]: https://github.com/nomadium/linzer/blob/master/LICENSE.txt
+[ci-image]: https://github.com/nomadium/linzer/actions/workflows/main.yml/badge.svg?branch=master
+[ci-link]: https://github.com/nomadium/linzer/actions/workflows/main.yml
 
 Linzer is a Ruby library for [HTTP Message Signatures (RFC 9421)](https://www.rfc-editor.org/rfc/rfc9421.html).
 
@@ -17,35 +24,97 @@ Or just `gem install linzer`.
 ### To sign a HTTP message:
 
 ```ruby
-irb(main):001:0> key = Linzer.generate_ed25519_key
+key = Linzer.generate_ed25519_key
 # => #<Linzer::Ed25519::Key:0x00000fe13e9bd208
 
-message = Linzer::Message.new(headers: {"date" => "Fri, 23 Feb 2024 17:57:23 GMT", "x-custom-header" => "foo"})
-# => #<Linzer::Message:0x0000000111b592a0 @headers={"date"=>"Fri, 23 Feb 2024 17:57:23 GMT", ...
+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]
 
-fields = %w[date x-custom-header]
 signature = Linzer.sign(key, message, fields)
 # => #<Linzer::Signature:0x0000000111f77ad0 ...
 
-puts signature.to_h
-{"signature"=>
-  "sig1=:8rLY3nFtezwwsK+sqZEMe7wzbNHojZJGEnvp3suKichgwH...",
- "signature-input"=>"sig1=(\"date\" \"x-custom-header\");created=1709075013;keyid=\"test-key-ed25519\""}
+pp signature.to_h
+# => {"signature"=>"sig1=:Cv1TUCxUpX+5SVa7pH0Xh...",
+#  "signature-input"=>"sig1=(\"date\" \"x-custom-header\" ..."}
+```
+
+### Use the message signature with any HTTP client:
+
+```ruby
+require "net/http"
+
+http = Net::HTTP.new("localhost", 9292)
+http.set_debug_output($stderr)
+response = http.post("/some_uri", "data", headers.merge(signature.to_h))
+# opening connection to localhost:9292...
+# opened
+# <- "POST /some_uri HTTP/1.1\r\n
+# <- Date: Fri, 23 Feb 2024 17:57:23 GMT\r\n
+# <- X-Custom-Header: foo\r\n
+# <- Signature: sig1=:Cv1TUCxUpX+5SVa7pH0X...
+# <- Signature-Input: sig1=(\"date\" \"x-custom-header\" \"@method\"...
+# <- Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3\r\n
+# <- Accept: */*\r\n
+# <- User-Agent: Ruby\r\n
+# <- Connection: close\r\n
+# <- Host: localhost:9292
+# <- Content-Length: 4\r\n
+# <- Content-Type: application/x-www-form-urlencoded\r\n\r\n"
+# <- "data"
+#
+# -> "HTTP/1.1 200 OK\r\n"
+# -> "Content-Type: text/html;charset=utf-8\r\n"
+# -> "Content-Length: 0\r\n"
+# -> "X-Xss-Protection: 1; mode=block\r\n"
+# -> "X-Content-Type-Options: nosniff\r\n"
+# -> "X-Frame-Options: SAMEORIGIN\r\n"
+# -> "Server: WEBrick/1.8.1 (Ruby/3.2.0/2022-12-25)\r\n"
+# -> "Date: Thu, 28 Mar 2024 17:19:21 GMT\r\n"
+# -> "Connection: close\r\n"
+# -> "\r\n"
+# reading 0 bytes...
+# -> ""
+# read 0 bytes
+# Conn close
+# => #<Net::HTTPOK 200 OK readbody=true>
 ```
 
 ### To verify a valid signature:
 
 ```ruby
-pubkey = Linzer.new_ed25519_public_key(test_ed25519_key_pub, "some-key-ed25519")
+test_ed25519_key_pub = Base64.strict_encode64(key.material.verify_key.to_bytes)
+# => "EUra7KsJ8B/lSZJVhDaopMycmZ6T7KtJqKVNJTHKIw0="
+
+raw_pubkey = Base64.strict_decode64(test_ed25519_key_pub)
+# => "\xB1rM\xFFR\x1F\xDDw\x00\x89\..."
+
+pubkey = Linzer.new_ed25519_public_key(raw_pubkey, "some-key-ed25519")
 # => #<Linzer::Ed25519::Key:0x00000fe19b9384b0
 
-headers = {"signature-input" => "...", signature => "...", "date" => "Fri, 23 Feb 2024 13:18:15 GMT", "x-custom-header" => "bar"})
+# 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(headers)
-# => #<Linzer::Message:0x0000000111b592a0 @headers={"date"=>"Fri, 23 Feb 2024 13:18:15 GMT", ...
+message = Linzer::Message.new(request)
 
-signature = Linzer::Signature.build(headers)
-# => #<Linzer::Signature:0x0000000112396008 ...
+signature = Linzer::Signature.build(message.headers)
 
 Linzer.verify(pubkey, message, signature)
 # => true
@@ -55,10 +124,35 @@ Linzer.verify(pubkey, message, signature)
 
 ```ruby
 result = Linzer.verify(pubkey, message, signature)
-lib/linzer/verifier.rb:34:in `verify_or_fail': Failed to verify message: Invalid signature. (Linzer::Error)
+lib/linzer/verifier.rb:38:in `verify_or_fail': Failed to verify message: Invalid signature. (Linzer::Error)
+```
+
+### HTTP responses are also supported
+
+HTTP responses can also be signed and verified in the same way as requests.
+
+```ruby
+headers = {
+  "date" => "Sat, 30 Mar 2024 21:40:13 GMT",
+  "x-response-custom" => "bar"
+}
+
+response = Linzer.new_response("request body", 200, headers)
+# or just use the response object exposed by your HTTP framework
+
+message = Linzer::Message.new(response)
+fields  = %w[@status date x-response-custom]
+
+signature = Linzer.sign(key, message, fields)
+
+pp signature.to_h
+# => {"signature"=>
+#   "sig1=:tCldwXqbISktyABrmbhszo...",
+#  "signature-input"=>"sig1=(\"@status\" \"date\" ..."}
+
 ```
 
-For now, to consult additional details, just take a look at source code and/or the unit tests.
+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).
 

data/lib/linzer/message.rb

@@ -2,37 +2,56 @@
 
 module Linzer
   class Message
-    def initialize(request_data)
-      @http    = Hash(request_data[:http].clone).freeze
-      @headers = Hash(request_data.fetch(:headers, {})
-                        .transform_keys(&:downcase)
-                        .clone).freeze
+    def initialize(operation)
+      @operation = operation
       freeze
     end
 
-    def empty?
-      @headers.empty?
+    def request?
+      @operation.is_a?(Rack::Request) || @operation.respond_to?(:request_method)
     end
 
-    def header?(header)
-      @headers.key?(header)
+    def response?
+      @operation.is_a?(Rack::Response) || @operation.respond_to?(:status)
+    end
+
+    def headers
+      return @operation.headers if response? || @operation.respond_to?(:headers)
+
+      Request.headers(@operation)
     end
 
     def field?(f)
       !!self[f]
     end
 
+    DERIVED_COMPONENT = {
+      "@method"         => :request_method,
+      "@authority"      => :authority,
+      "@path"           => :path_info,
+      "@status"         => :status,
+      "@target-uri"     => :url,
+      "@scheme"         => :scheme,
+      "@request-target" => :fullpath,
+      "@query"          => :query_string
+    }.freeze
+
     def [](field_name)
-      return @headers[field_name] if !field_name.start_with?("@")
+      if !field_name.start_with?("@")
+        return @operation.env[Request.rack_header_name(field_name)] if request?
+        return @operation.headers[field_name]                     # if response?
+      end
+
+      method = DERIVED_COMPONENT[field_name]
 
       case field_name
-      when "@method"    then @http["method"]
-      when "@authority" then @http["host"]
-      when "@path"      then @http["path"]
-      when "@status"    then @http["status"]
-      else # XXX: improve this and add support for all fields in the RFC
-        raise Error.new "Unknown/unsupported field: \"#{field_name}\""
+      when "@query"
+        return "?#{@operation.public_send(method)}"
+      when /\A(?<field>(?<prefix>@query-param)(?<rest>;name=.+)\Z)/
+        return parse_query_param Regexp.last_match
       end
+
+      method ? @operation.public_send(method) : nil
     end
 
     class << self
@@ -42,5 +61,17 @@ module Linzer
         raise Error.new "Cannot parse \"#{field_name}\" field. Bailing out!"
       end
     end
+
+    private
+
+    def parse_query_param(match_data)
+      raw_item    = '"%s"%s' % [match_data[:prefix], match_data[:rest]]
+      parsed_item = Starry.parse_item(raw_item)
+      fail unless parsed_item.value == "@query-param"
+      param_name  = URI.decode_uri_component(parsed_item.parameters["name"])
+      URI.encode_uri_component(@operation.params.fetch(param_name))
+    rescue => _
+      nil
+    end
   end
 end

data/lib/linzer/request.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Linzer
+  module Request
+    extend self
+
+    def build(verb, uri = "/", params = {}, headers = {})
+      validate verb, uri, params, headers
+
+      # XXX: to-do: handle rack request params?
+      request_method = Rack.const_get(verb.upcase)
+      args = {
+        "REQUEST_METHOD" => request_method,
+        "PATH_INFO"      => uri.to_str
+      }
+
+      Rack::Request.new(build_rack_env(headers).merge(args))
+    end
+
+    def rack_header_name(field_name)
+      validate_header_name field_name
+
+      rack_name = field_name.upcase.tr("-", "_")
+      case field_name.downcase
+      when "content-type", "content-length"
+        rack_name
+      else
+        "HTTP_#{rack_name}"
+      end
+    end
+
+    def headers(rack_request)
+      rack_request
+        .each_header
+        .to_h
+        .select do |k, _|
+          k.start_with?("HTTP_") || %w[CONTENT_TYPE CONTENT_LENGTH].include?(k)
+        end
+        .transform_keys { |k| k.downcase.tr("_", "-") }
+        .transform_keys do |k|
+          %w[content-type content-length].include?(k) ? k : k.gsub(/^http-/, "")
+        end
+    end
+
+    private
+
+    def validate(verb, uri, params, headers)
+      validate_verb      verb
+      validate_uri       uri
+      validate_arg_hash  headers: headers
+      validate_arg_hash  params:  params
+    end
+
+    def validate_verb(verb)
+      Rack.const_get(verb.upcase)
+    rescue => ex
+      unknown_method = "Unknown/invalid HTTP request method"
+      raise Error.new, unknown_method, cause: ex
+    end
+
+    def validate_uri(uri)
+      uri.to_str
+    rescue => ex
+      invalid_uri = "Invalid URI"
+      raise Error.new, invalid_uri, cause: ex
+    end
+
+    def validate_arg_hash(hsh)
+      arg_name = hsh.keys.first
+      hsh[arg_name].to_hash
+    rescue => ex
+      err_msg = "invalid \"#{arg_name}\" parameter, cannot be converted to hash."
+      raise Error.new, "Cannot build request: #{err_msg}", cause: ex
+    end
+
+    def validate_header_name(name)
+      raise ArgumentError.new, "Blank header name." if name.empty?
+      name.to_str
+    rescue => ex
+      err_msg = "Invalid header name: '#{name}'"
+      raise Error.new, err_msg, cause: ex
+    end
+
+    def build_rack_env(headers)
+      headers
+        .to_hash
+        .transform_keys { |k| k.upcase.tr("-", "_") }
+        .transform_keys do |k|
+          %w[CONTENT_TYPE CONTENT_LENGTH].include?(k) ? k : "HTTP_#{k}"
+        end
+    end
+  end
+end

data/lib/linzer/response.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Linzer
+  module Response
+    def new_response(body = nil, status = 200, headers = {})
+      Rack::Response.new(body, status, headers)
+    end
+  end
+end

data/lib/linzer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Linzer
-  VERSION = "0.4.1"
+  VERSION = "0.5.1"
 end

data/lib/linzer.rb

@@ -2,9 +2,12 @@
 
 require "starry"
 require "openssl"
+require "rack"
 
 require_relative "linzer/version"
 require_relative "linzer/common"
+require_relative "linzer/request"
+require_relative "linzer/response"
 require_relative "linzer/message"
 require_relative "linzer/signature"
 require_relative "linzer/key"
@@ -21,6 +24,11 @@ module Linzer
 
   class << self
     include Key::Helper
+    include Response
+
+    def new_request(verb, uri = "/", params = {}, headers = {})
+      Linzer::Request.build(verb, uri, params, headers)
+    end
 
     def verify(pubkey, message, signature)
       Linzer::Verifier.verify(pubkey, message, signature)

data/linzer.gemspec

@@ -31,4 +31,5 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency "ed25519", "~> 1.3", ">= 1.3.0"
   spec.add_runtime_dependency "starry", "~> 0.1"
+  spec.add_runtime_dependency "rack", "~> 3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: linzer
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.1
 platform: ruby
 authors:
 - Miguel Landaeta
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-25 00:00:00.000000000 Z
+date: 2024-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ed25519
@@ -44,6 +44,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description:
 email:
 - miguel@miguel.cc
@@ -66,6 +80,8 @@ files:
 - lib/linzer/key.rb
 - lib/linzer/key/helper.rb
 - lib/linzer/message.rb
+- lib/linzer/request.rb
+- lib/linzer/response.rb
 - lib/linzer/rsa.rb
 - lib/linzer/signature.rb
 - lib/linzer/signer.rb