linzer 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b025e976012c79dc5153ebd4ca98f23df08a55bf0706c6d8427e0374b3cd7f5
-  data.tar.gz: b864415aad8cc6c9cbee217a64531378b92edbb62fb58b67a036e5997fec4a30
+  metadata.gz: a9b2828e9333279ffabf8102d126f832ebece8e6b5ce26bec6897337bae773b4
+  data.tar.gz: 868c9763f3067b55eb8fc76dfb1b6c5e6529562a57ee08d41bbfb3f443311536
 SHA512:
-  metadata.gz: 9d2eea3036d11c6b7f8969d0f30b71fa3715d62820acde93c7d512689aa7c91d281436f8b2ea91e47b906f62167a4611298d2fad64bcf241b39b18f4405ed7a9
-  data.tar.gz: 6f85ffe146b8a52647969575dc80011f5fefdf299bdf082cd4f3b4de0fc605f60f8beaaa1cc4cf04843cf2b3a5f7d6441c7f6b3989d50ed559cca398bbc3d7b6
+  metadata.gz: ef676846ea6c038465971a4c5fa47b77763f74e37adc357b5c967c483a5d3c767f0e3d1b0e073c16621ac311cc07bd524fe422e0272e9ef6e0b88091e15120e7
+  data.tar.gz: 8047b4e3ea2778e53764bc625d04c4ba4435f2399992885406f46128a69502158598a0130184b49887ad576252220bc71bfdbe451910971ce7357a84374f2818

data/.standard.yml

@@ -1,3 +1,11 @@
 # For available configuration options, see:
 #   https://github.com/testdouble/standard
 ruby_version: 2.6
+
+ignore:
+  - 'lib/**/*':
+    - Layout/ExtraSpacing
+    - Layout/HashAlignment
+  - 'spec/**/*':
+    - Layout/ExtraSpacing
+    - Layout/HashAlignment

data/CHANGELOG.md

@@ -1,6 +1,11 @@
 ## [Unreleased]
 
+## [0.2.0] - 2024-02-23
+
+- Add signature signing functionality. RSASSA-PSS using SHA-512 is still the only
+  supported algorithm.
+
 ## [0.1.0] - 2024-02-18
 
 - Initial release
-- It barely passes unit tests to verify signatures with RSASSA-PSS Using SHA-512.
+- It barely passes unit tests to verify signatures with RSASSA-PSS using SHA-512.

data/README.md

@@ -14,11 +14,57 @@ Or just `gem install linzer`.
 
 ## Usage
 
-TODO: Write usage instructions here
+### To sign a HTTP message:
 
-For now just take a look at the unit tests.
+```ruby
+key = Linzer::Key.new(material: OpenSSL::PKey::RSA.generate(2048), key_id: "my-test-key-rsa-pss")
+# => #<struct Struct::Key material=#<OpenSSL::PKey::RSA:...
+
+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", ...
+
+fields = %w[date x-custom-header])
+signature = Linzer.sign(key, message, fields)
+# => #<Linzer::Signature:0x0000000111f77ad0 ...
+
+puts signature.to_h
+{"signature"=>
+  "sig1=:XQQnm4qyOdIa9yTebXzCQ4f7sXXnoe76D2g1gbFFc1DeqH...",
+ "signature-input"=>"sig1=(\"date\" \"x-custom-header\");created=1708690868;keyid=\"my-test-key-rsa-pss\""}
+```
+
+### To verify a valid signature:
+
+```ruby
+pubkey = Linzer::Key.new(key_id: "some-key-rsa-pss", material: OpenSSL::PKey::RSA.new(test_key_rsa_pss))
+# => #<struct Struct::Key material=#<OpenSSL::PKey::RSA:0x0000000106eade48 oid=rsaEncryption>, key_id="some-key-rsa-pss">
+
+headers = {"signature-input" => "...", signature => "...", "date" => "Fri, 23 Feb 2024 13:18:15 GMT", "x-custom-header" => "bar"})
+
+message = Linzer::Message.new(headers)
+# => #<Linzer::Message:0x0000000111b592a0 @headers={"date"=>"Fri, 23 Feb 2024 13:18:15 GMT", ...
+
+signature = Linzer::Signature.build(headers)
+# => #<Linzer::Signature:0x0000000112396008 ...
+
+Linzer.verify(pubkey, message, signature)
+# => true
+```
+
+### What if an invalid signature if verified?
+
+```ruby
+result = Linzer.verify(pubkey, message, signature)
+linzer/lib/linzer/verifier.rb:14:in `verify': Failed to verify message: Invalid signature. (Linzer::Error)
+```
+
+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, so only signatures RSASSA-PSS using SHA-512 like ones
+described in the RFC are supported.
 
-It's still early days, so only signatures RSASSA-PSS Using SHA-512 like ones described in the RFC are supported. I'll be expanding the library to cover more functionality specified in the RFC in subsequent releases.
+I'll be expanding the library to cover more functionality specified in the RFC
+in subsequent releases.
 
 
 ## Development

data/lib/linzer/message.rb

@@ -3,8 +3,9 @@
 module Linzer
   class Message
     def initialize(request_data)
-      @headers = Hash(request_data[:headers])
-      @http = Hash(request_data[:http])
+      @headers = Hash(request_data[:headers].clone).freeze
+      @http    = Hash(request_data[:http].clone).freeze
+      freeze
     end
 
     def empty?
@@ -15,16 +16,54 @@ module Linzer
       @headers.key?(header)
     end
 
+    def field?(f)
+      !!self[f]
+    end
+
     def [](field_name)
       return @headers[field_name] if !field_name.start_with?("@")
 
       case field_name
-      when "@method" then @http["method"]
+      when "@method"    then @http["method"]
       when "@authority" then @http["host"]
-      when "@path" then @http["path"]
+      when "@path"      then @http["path"]
       else # XXX: improve this and add support for all fields in the RFC
         raise Error.new "Unknown/unsupported field: \"#{field_name}\""
       end
     end
+
+    def signature_base(components, parameters)
+      validate_components components
+
+      signature_base = components.each_with_object(+"") do |comp, base|
+        base << "\"#{comp}\": #{self[comp]}\n"
+      end
+
+      signature_params =
+        Starry.serialize([Starry::InnerList.new(components, parameters)])
+
+      signature_base << "\"@signature-params\": #{signature_params}"
+      signature_base
+    end
+
+    class << self
+      def parse_structured_dictionary(str, field_name = nil)
+        Starry.parse_dictionary(str)
+      rescue Starry::ParseError => _
+        raise Error.new "Cannot parse \"#{field_name}\" field. Bailing out!"
+      end
+    end
+
+    private
+
+    def validate_components(components)
+      if components.include?("@signature-params")
+        raise Error.new "Invalid component in signature input"
+      end
+      msg = "Cannot verify signature. Missing component in message: %s"
+      components.each { |c| raise Error.new msg % "\"#{c}\"" unless field? c  }
+      msg = "Invalid signature. Duplicated component in signature input."
+      raise Error.new msg if components.size != components.uniq.size
+    end
   end
 end

data/lib/linzer/signature.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Signature
+    def initialize(metadata, value, label, parameters = {})
+      @metadata   = metadata.clone.freeze
+      @value      = value.clone.freeze
+      @parameters = parameters.clone.freeze
+      @label      = label.clone.freeze
+      freeze
+    end
+
+    attr_reader  :metadata, :value, :parameters, :label
+    alias_method :components, :metadata
+    alias_method :bytes, :value
+
+    def to_h
+      {
+        "signature" => Starry.serialize({label => value}),
+        "signature-input" =>
+          Starry.serialize({label =>
+            Starry::InnerList.new(components, parameters)})
+      }
+    end
+
+    class << self
+      private :new
+
+      def build(headers, options = {})
+        validate headers
+
+        input = parse_field(headers, "signature-input")
+        reject_multiple_signatures if input.size > 1 && options[:label].nil?
+        label = options[:label] || input.keys.first
+
+        signature = parse_field(headers, "signature")
+        fail_with_signature_not_found label unless signature.key?(label)
+
+        raw_signature = signature[label].value
+
+        fail_due_invalid_components unless input[label].value.respond_to?(:each)
+
+        components = input[label].value.map(&:value)
+        parameters = input[label].parameters
+
+        new(components, raw_signature, label, parameters)
+      end
+
+      private
+
+      def validate(headers)
+        raise Error.new "Cannot build signature: Request headers cannot be null"      if headers.nil?
+        raise Error.new "Cannot build signature: No request headers found"            if headers.empty?
+        raise Error.new "Cannot build signature: No \"signature-input\" header found" unless headers.key?("signature-input")
+        raise Error.new "Cannot build signature: No \"signature\" header found"       unless headers.key?("signature")
+      end
+
+      def reject_multiple_signatures
+        raise Error.new "Multiple signatures found but none was selected."
+      end
+
+      def fail_with_signature_not_found(label)
+        raise Error.new "Signature label not found: \"#{label}\""
+      end
+
+      def fail_due_invalid_components
+        raise Error.new "Unexpected value for covered components."
+      end
+
+      def parse_field(hsh, field_name)
+        Message.parse_structured_dictionary(hsh[field_name], field_name)
+      end
+    end
+  end
+end

data/lib/linzer/signer.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Linzer
+  module Signer
+    DEFAULT_LABEL = "sig1"
+
+    class << self
+      def sign(key, message, components, options = {})
+        validate key, message, components
+
+        parameters = populate_parameters(key, options)
+        signature_base = message.signature_base(components, parameters)
+
+        signature = _sign(key, signature_base, options)
+        label = options[:label] || DEFAULT_LABEL
+
+        Linzer::Signature.build(serialize(signature, components, parameters, label))
+      end
+
+      def default_label
+        DEFAULT_LABEL
+      end
+
+      private
+
+      def validate(key, message, components)
+        raise Error.new "Message to sign cannot be null"           if message.nil?
+        raise Error.new "Message cannot be signed with a null key" if key.nil?
+
+        if components.include?("@signature-params")
+          raise Error.new "Invalid component in signature input"
+        end
+
+        component_missing = 'Cannot sign message: component "%s" is not present in message'
+        components.each do |c|
+          raise Error.new component_missing % c unless message.field? c
+        end
+      end
+
+      def populate_parameters(key, options)
+        parameters = {}
+
+        parameters[:created] = options[:created] || Time.now.getutc.to_i
+
+        key_id = options[:keyid] || (key.key_id if key.respond_to?(:key_id))
+        parameters[:keyid] = key_id             unless key_id.nil?
+
+        (options.keys - %i[created keyid label]).each { |k| parameters[k] = options[k] }
+
+        parameters
+      end
+
+      def _sign(key, data, options)
+        # signature = key.sign_pss("SHA512", signature_base, salt_length: 64, mgf1_hash: "SHA512")
+        key.sign("SHA512", data)
+      end
+
+      def serialize(signature, components, parameters, label)
+        {
+          "signature" => Starry.serialize({label => signature}),
+          "signature-input" =>
+            Starry.serialize({label =>
+              Starry::InnerList.new(components, parameters)})
+        }
+      end
+    end
+  end
+end

data/lib/linzer/verifier.rb

@@ -1,101 +1,40 @@
 # frozen_string_literal: true
 
 module Linzer
-  class Verifier
-    def initialize(pubkeys = nil)
-      @pubkeys = Hash(pubkeys)
-    end
-
-    attr_reader :pubkeys
-
-    # XXX: probably all this validation can be moved to the Message class
-    def verify(message)
-      validate message
-
-      signature_input = parse_field(message, "signature-input")
-      signature = parse_field(message, "signature")
-
-      # XXX: this is a self-imposed limitation, fix later
-      reject_multiple(signature)
-
-      choosen_signature = signature.keys[0]
-      if !signature_input.key?(choosen_signature)
-        raise Error.new "Signature \"#{choosen_signature}\" is not found."
-      end
-
-      covered_components = signature_input[choosen_signature].to_a
-      signature_parameters = signature_input[choosen_signature].parameters
-
-      signature_value = signature[choosen_signature].value
-      # XXX to-do: have a mechanism to inspect components and parameters
+  module Verifier
+    class << self
+      def verify(key, message, signature)
+        validate message, key, signature
 
-      check_key_presence signature_parameters
-      check_components message, covered_components
+        parameters = signature.parameters
+        components = signature.components
 
-      signature_base = build_signature_base(message, signature_input)
+        signature_base = message.signature_base(components, parameters)
 
-      # XXX to-do: get rid of this hard-coded SHA512 values, support more algs
-      key = pubkeys[signature_parameters["keyid"]]
-      if !key.verify_pss("SHA512", signature_value, signature_base, salt_length: :auto, mgf1_hash: "SHA512")
+        return true if _verify(key, signature.value, signature_base)
         raise Error.new "Failed to verify message: Invalid signature."
       end
 
-      true
-    end
-
-    private
+      private
 
-    def validate(message)
-      raise Error.new "Message to verify cannot be null" if message.nil?
-      raise Error.new "Message to verify cannot be empty" if message.empty?
-      raise Error.new "Message signature cannot be incomplete" unless message.header?("signature-input")
-      raise Error.new "Message has no signature to verify" unless message.header?("signature")
-    end
+      def validate(message, key, signature)
+        raise Error.new "Message to verify cannot be null"       if message.nil?
+        raise Error.new "Key to verify signature cannot be null" if key.nil?
+        raise Error.new "Signature to verify cannot be null"     if signature.nil?
 
-    def parse_field(message, field_name)
-      Starry.parse_dictionary(message[field_name])
-    rescue Starry::ParseError => _
-      raise Error.new "Cannot parse \"#{field_name}\" field. Bailing out!"
-    end
-
-    def reject_multiple(hsh)
-      msg = "Messages with more than 1 signatures are not supported"
-      raise Error.new msg if hsh.keys.size > 1
-    end
-
-    def check_key_presence(parameters)
-      msg = "Cannot verify signature. Key not found"
-
-      key_id = parameters["keyid"]
-      raise Error.new msg if key_id.nil?
-      msg += ": \"#{key_id}\"" if !key_id.empty?
-
-      raise Error.new msg unless pubkeys.key?(key_id)
-    end
-
-    def check_components(message, components)
-      msg = "Cannot verify signature. Missing component in message: "
-      components
-        .map(&:value)
-        .reject { |component| message[component] }
-        .shift
-        .tap do |component|
-          if component
-            msg += "\"#{component}\""
-            raise Error.new msg
-          end
+        if !signature.respond_to?(:value) || !signature.respond_to?(:components)
+          raise Error.new "Signature is invalid"
         end
-    end
 
-    def build_signature_base(message, signature_input)
-      signature_base = +""
-      signature_params = ""
-      signature_input.each do |k, l|
-        signature_params = l.to_s
-        l.value.each { |c| signature_base << "\"#{c.value}\": #{message[c.value]}\n" }
+        raise Error.new "Signature raw value to cannot be null" if signature.value.nil?
+        raise Error.new "Components cannot be null"             if signature.components.nil?
+      end
+
+      def _verify(key, signature, data)
+        # XXX to-do: get rid of this hard-coded SHA512 values, support more algs
+        return true if key.material.verify_pss("SHA512", signature, data, salt_length: :auto, mgf1_hash: "SHA512")
+        false
       end
-      signature_base << "\"@signature-params\": #{signature_params}"
-      signature_base
     end
   end
 end

data/lib/linzer/version.rb

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

data/lib/linzer.rb

@@ -5,15 +5,29 @@ require "openssl"
 
 require_relative "linzer/version"
 require_relative "linzer/message"
+require_relative "linzer/signature"
+require_relative "linzer/signer"
 require_relative "linzer/verifier"
 
 module Linzer
   class Error < StandardError; end
 
+  Key = Struct.new("Key", :material, :key_id, keyword_init: true) do |clazz|
+    def sign(*args)
+      # XXX: probably this is going to grow in complexity and will need
+      # to be moved to its own class or dispatch to the signer
+      !material.nil? or raise Error.new "Cannot sign data, key material cannot be null."
+      material.sign(*args)
+    end
+  end
+
   class << self
-    def verify(pubkeys, message)
-      Linzer::Verifier.new(pubkeys)
-        .verify(message)
+    def verify(pubkey, message, signature)
+      Linzer::Verifier.verify(pubkey, message, signature)
+    end
+
+    def sign(key, message, components, options = {})
+      Linzer::Signer.sign(key, message, components, options)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: linzer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Miguel Landaeta
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-18 00:00:00.000000000 Z
+date: 2024-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ed25519
@@ -60,6 +60,8 @@ files:
 - Rakefile
 - lib/linzer.rb
 - lib/linzer/message.rb
+- lib/linzer/signature.rb
+- lib/linzer/signer.rb
 - lib/linzer/verifier.rb
 - lib/linzer/version.rb
 - linzer.gemspec