linzer 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b025e976012c79dc5153ebd4ca98f23df08a55bf0706c6d8427e0374b3cd7f5
-  data.tar.gz: b864415aad8cc6c9cbee217a64531378b92edbb62fb58b67a036e5997fec4a30
+  metadata.gz: 22298d26596b660ac67a7f039ed0d05cc41715a5413c4583a4703ce452e6548c
+  data.tar.gz: 735d31e3752eea02207baa7e093bd18a114281f4c493acf98cd7451d73e03fff
 SHA512:
-  metadata.gz: 9d2eea3036d11c6b7f8969d0f30b71fa3715d62820acde93c7d512689aa7c91d281436f8b2ea91e47b906f62167a4611298d2fad64bcf241b39b18f4405ed7a9
-  data.tar.gz: 6f85ffe146b8a52647969575dc80011f5fefdf299bdf082cd4f3b4de0fc605f60f8beaaa1cc4cf04843cf2b3a5f7d6441c7f6b3989d50ed559cca398bbc3d7b6
+  metadata.gz: 81428b963ffaa3f39e86ed28e52927923998aaeeb07f773a852bb01abe9272f812c8b0a593813293908845f57799c849163da00d4ae4ca2ef62d36687055ce81
+  data.tar.gz: 3f91ef995bd53bda69832e774ce383cf55a8ef903ffe615e8dbb1a586cf437b85a3d98f8082f39311a6757a3bd4f2657ac4b5d73c3270b4a4534ea571b9e8427

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,16 @@
 ## [Unreleased]
 
+## [0.3.0] - 2024-02-28
+
+- Add support for the following algorithms: Ed25519, HMAC-SHA256 and
+  ECDSA (P-256 and P-384 curves).
+
+## [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,56 @@ 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
+irb(main):001:0> 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", ...
+
+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\""}
+```
+
+### To verify a valid signature:
+
+```ruby
+pubkey = Linzer.new_ed25519_public_key(test_ed25519_key_pub, "some-key-ed25519")
+# => #<Linzer::Ed25519::Key:0x00000fe19b9384b0
+
+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)
+lib/linzer/verifier.rb:34:in `verify_or_fail': 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 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 curve. ECDSA P-384 curve was also added but not tested yet.
 
-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/common.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Linzer
+  module Common
+    def signature_base(message, components, parameters)
+      signature_base = components.each_with_object(+"") do |component, base|
+        base << "\"#{component}\": #{message[component]}\n"
+      end
+
+      signature_params =
+        Starry.serialize([Starry::InnerList.new(components, parameters)])
+
+      signature_base << "\"@signature-params\": #{signature_params}"
+      signature_base
+    end
+
+    def validate_components(message, 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 message.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/ecdsa.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Linzer
+  module ECDSA
+    class Key < Linzer::Key
+      def validate
+        super
+        validate_digest
+      end
+
+      def sign(data)
+        material.sign(@params[:digest], data)
+      end
+
+      def verify(signature, data)
+        material.verify(@params[:digest], signature, data)
+      end
+    end
+  end
+end

data/lib/linzer/ed25519.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "ed25519"
+
+module Linzer
+  module Ed25519
+    class Key < Linzer::Key
+      def sign(data)
+        material.sign(data)
+      end
+
+      def verify(signature, data)
+        verify_key = material.is_a?(::Ed25519::SigningKey) ? material.verify_key : material
+        verify_key.verify(signature, data)
+      rescue ::Ed25519::VerifyError
+        false
+      end
+    end
+  end
+end

data/lib/linzer/hmac.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Linzer
+  module HMAC
+    class Key < Linzer::Key
+      def validate
+        super
+        validate_digest
+      end
+
+      def sign(data)
+        OpenSSL::HMAC.digest(@params[:digest], material, data)
+      end
+
+      def verify(signature, data)
+        signature == sign(data)
+      end
+    end
+  end
+end

data/lib/linzer/key/helper.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+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")
+      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")
+      end
+
+      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")
+      end
+
+      # XXX: to-do
+      # Linzer::RSA::Key
+      # def new_rsa_v1_5_sha256_key
+      # def generate_rsa_v1_5_sha256_key
+
+      def generate_hmac_sha256_key(key_id = nil)
+        material = OpenSSL::Random.random_bytes(64)
+        Linzer::HMAC::Key.new(material, id: key_id, digest: "SHA256")
+      end
+
+      def new_hmac_sha256_key(material, key_id = nil)
+        Linzer::HMAC::Key.new(material, id: key_id, digest: "SHA256")
+      end
+
+      def generate_ed25519_key(key_id = nil)
+        material = ::Ed25519::SigningKey.generate
+        Linzer::Ed25519::Key.new(material, id: key_id)
+      end
+
+      def new_ed25519_key(material, key_id = nil)
+        key = ::Ed25519::SigningKey.new(material)
+        Linzer::Ed25519::Key.new(key, id: key_id)
+      end
+
+      def new_ed25519_public_key(material, key_id = nil)
+        key = ::Ed25519::VerifyKey.new(material)
+        Linzer::Ed25519::Key.new(key, id: key_id)
+      end
+
+      # https://www.rfc-editor.org/rfc/rfc4492.html#appendix-A
+      # Table 6: Equivalent curves defined by SECG, ANSI, and NIST
+      # secp256r1   |  prime256v1   |   NIST P-256
+      def generate_ecdsa_p256_sha256_key(key_id = nil)
+        material = OpenSSL::PKey::EC.generate("prime256v1")
+        Linzer::ECDSA::Key.new(material, id: key_id, digest: "SHA256")
+      end
+
+      def new_ecdsa_p256_sha256_key(material, key_id = nil)
+        key = OpenSSL::PKey::EC.new(material)
+        Linzer::ECDSA::Key.new(key, id: key_id, digest: "SHA256")
+      end
+
+      # https://www.rfc-editor.org/rfc/rfc4492.html#appendix-A
+      # Table 6: Equivalent curves defined by SECG, ANSI, and NIST
+      # secp384r1   |               |   NIST P-384
+      def generate_ecdsa_p384_sha256_key(key_id = nil)
+        material = OpenSSL::PKey::EC.generate("secp384r1")
+        Linzer::ECDSA::Key.new(material, id: key_id, digest: "SHA384")
+      end
+
+      def new_ecdsa_p384_sha384_key(material, key_id = nil)
+        key = OpenSSL::PKey::EC.new(material)
+        Linzer::ECDSA::Key.new(key, id: key_id, digest: "SHA384")
+      end
+    end
+  end
+end

data/lib/linzer/key.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Key
+    def initialize(material, params = {})
+      @material = material
+      @params   = Hash(params).clone.freeze
+      validate
+      freeze
+    end
+
+    attr_reader :material
+
+    def key_id
+      @params[:id]
+    end
+
+    def sign(*args)
+      abstract_error = "Cannot sign data, \"#{self.class}\" is an abstract class."
+      raise Error.new abstract_error
+    end
+
+    def verify(*args)
+      abstract_error = "Cannot verify signature, \"#{self.class}\" is an abstract class."
+      raise Error.new abstract_error
+    end
+
+    private
+
+    def validate
+      !material.nil? or raise Error.new "Invalid key. No key material provided."
+    end
+
+    def validate_digest
+      no_digest = !@params.key?(:digest) || @params[:digest].nil? || String(@params[:digest]).empty?
+      no_digest_error = "Invalid key definition, no digest algorithm was selected."
+      raise Linzer::Error.new no_digest_error if no_digest
+    end
+  end
+end

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,29 @@ 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"]
+      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}\""
       end
     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
   end
 end

data/lib/linzer/rsa.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Linzer
+  module RSA
+    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)
+      end
+
+      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]
+        )
+        false
+      end
+    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,60 @@
+# frozen_string_literal: true
+
+module Linzer
+  module Signer
+    DEFAULT_LABEL = "sig1"
+
+    class << self
+      include Common
+
+      def sign(key, message, components, options = {})
+        validate key, message, components
+
+        parameters = populate_parameters(key, options)
+        signature_base = signature_base(message, components, parameters)
+
+        signature = key.sign(signature_base)
+        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)
+        msg = "Message cannot be signed with null %s"
+        raise Error.new msg % "value"     if message.nil?
+        raise Error.new msg % "key"       if key.nil?
+        raise Error.new msg % "component" if components.nil?
+
+        validate_components message, components
+      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 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,42 @@
 # frozen_string_literal: true
 
 module Linzer
-  class Verifier
-    def initialize(pubkeys = nil)
-      @pubkeys = Hash(pubkeys)
-    end
-
-    attr_reader :pubkeys
+  module Verifier
+    class << self
+      include Common
 
-    # XXX: probably all this validation can be moved to the Message class
-    def verify(message)
-      validate message
+      def verify(key, message, signature)
+        validate message, key, signature
 
-      signature_input = parse_field(message, "signature-input")
-      signature = parse_field(message, "signature")
+        parameters = signature.parameters
+        components = signature.components
 
-      # XXX: this is a self-imposed limitation, fix later
-      reject_multiple(signature)
+        signature_base = signature_base(message, components, parameters)
 
-      choosen_signature = signature.keys[0]
-      if !signature_input.key?(choosen_signature)
-        raise Error.new "Signature \"#{choosen_signature}\" is not found."
+        verify_or_fail key, signature.value, signature_base
       end
 
-      covered_components = signature_input[choosen_signature].to_a
-      signature_parameters = signature_input[choosen_signature].parameters
+      private
 
-      signature_value = signature[choosen_signature].value
-      # XXX to-do: have a mechanism to inspect components and parameters
+      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?
 
-      check_key_presence signature_parameters
-      check_components message, covered_components
+        if !signature.respond_to?(:value) || !signature.respond_to?(:components)
+          raise Error.new "Signature is invalid"
+        end
 
-      signature_base = build_signature_base(message, signature_input)
+        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?
 
-      # 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")
-        raise Error.new "Failed to verify message: Invalid signature."
+        validate_components message, signature.components
       end
 
-      true
-    end
-
-    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 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
-        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" }
+      def verify_or_fail(key, signature, data)
+        return true if key.verify(signature, data)
+        raise Error.new "Failed to verify message: Invalid signature."
       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.3.0"
 end

data/lib/linzer.rb

@@ -4,16 +4,30 @@ require "starry"
 require "openssl"
 
 require_relative "linzer/version"
+require_relative "linzer/common"
 require_relative "linzer/message"
+require_relative "linzer/signature"
+require_relative "linzer/key"
+require_relative "linzer/rsa"
+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"
 
 module Linzer
   class Error < StandardError; end
 
   class << self
-    def verify(pubkeys, message)
-      Linzer::Verifier.new(pubkeys)
-        .verify(message)
+    include Key::Helper
+
+    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.3.0
 platform: ruby
 authors:
 - Miguel Landaeta
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-18 00:00:00.000000000 Z
+date: 2024-02-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ed25519
@@ -59,7 +59,16 @@ files:
 - README.md
 - Rakefile
 - lib/linzer.rb
+- lib/linzer/common.rb
+- lib/linzer/ecdsa.rb
+- lib/linzer/ed25519.rb
+- lib/linzer/hmac.rb
+- lib/linzer/key.rb
+- lib/linzer/key/helper.rb
 - lib/linzer/message.rb
+- lib/linzer/rsa.rb
+- lib/linzer/signature.rb
+- lib/linzer/signer.rb
 - lib/linzer/verifier.rb
 - lib/linzer/version.rb
 - linzer.gemspec