linzer 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9b2828e9333279ffabf8102d126f832ebece8e6b5ce26bec6897337bae773b4
-  data.tar.gz: 868c9763f3067b55eb8fc76dfb1b6c5e6529562a57ee08d41bbfb3f443311536
+  metadata.gz: 22298d26596b660ac67a7f039ed0d05cc41715a5413c4583a4703ce452e6548c
+  data.tar.gz: 735d31e3752eea02207baa7e093bd18a114281f4c493acf98cd7451d73e03fff
 SHA512:
-  metadata.gz: ef676846ea6c038465971a4c5fa47b77763f74e37adc357b5c967c483a5d3c767f0e3d1b0e073c16621ac311cc07bd524fe422e0272e9ef6e0b88091e15120e7
-  data.tar.gz: 8047b4e3ea2778e53764bc625d04c4ba4435f2399992885406f46128a69502158598a0130184b49887ad576252220bc71bfdbe451910971ce7357a84374f2818
+  metadata.gz: 81428b963ffaa3f39e86ed28e52927923998aaeeb07f773a852bb01abe9272f812c8b0a593813293908845f57799c849163da00d4ae4ca2ef62d36687055ce81
+  data.tar.gz: 3f91ef995bd53bda69832e774ce383cf55a8ef903ffe615e8dbb1a586cf437b85a3d98f8082f39311a6757a3bd4f2657ac4b5d73c3270b4a4534ea571b9e8427

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [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

data/README.md

@@ -17,27 +17,27 @@ Or just `gem install linzer`.
 ### To sign a HTTP message:
 
 ```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:...
+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])
+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\""}
+  "sig1=:8rLY3nFtezwwsK+sqZEMe7wzbNHojZJGEnvp3suKichgwH...",
+ "signature-input"=>"sig1=(\"date\" \"x-custom-header\");created=1709075013;keyid=\"test-key-ed25519\""}
 ```
 
 ### 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">
+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"})
 
@@ -55,13 +55,12 @@ Linzer.verify(pubkey, message, signature)
 
 ```ruby
 result = Linzer.verify(pubkey, message, signature)
-linzer/lib/linzer/verifier.rb:14:in `verify': Failed to verify message: Invalid signature. (Linzer::Error)
+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, so only signatures RSASSA-PSS using SHA-512 like ones
-described in the RFC are supported.
+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.
 
 I'll be expanding the library to cover more functionality specified in the RFC
 in subsequent releases.

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

@@ -27,25 +27,12 @@ module Linzer
       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}\""
       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)
@@ -53,17 +40,5 @@ module Linzer
         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/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/signer.rb

@@ -5,13 +5,15 @@ module Linzer
     DEFAULT_LABEL = "sig1"
 
     class << self
+      include Common
+
       def sign(key, message, components, options = {})
         validate key, message, components
 
         parameters = populate_parameters(key, options)
-        signature_base = message.signature_base(components, parameters)
+        signature_base = signature_base(message, components, parameters)
 
-        signature = _sign(key, signature_base, options)
+        signature = key.sign(signature_base)
         label = options[:label] || DEFAULT_LABEL
 
         Linzer::Signature.build(serialize(signature, components, parameters, label))
@@ -24,17 +26,12 @@ module Linzer
       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
+        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?
 
-        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
+        validate_components message, components
       end
 
       def populate_parameters(key, options)
@@ -50,11 +47,6 @@ module Linzer
         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}),

data/lib/linzer/verifier.rb

@@ -3,16 +3,17 @@
 module Linzer
   module Verifier
     class << self
+      include Common
+
       def verify(key, message, signature)
         validate message, key, signature
 
         parameters = signature.parameters
         components = signature.components
 
-        signature_base = message.signature_base(components, parameters)
+        signature_base = signature_base(message, components, parameters)
 
-        return true if _verify(key, signature.value, signature_base)
-        raise Error.new "Failed to verify message: Invalid signature."
+        verify_or_fail key, signature.value, signature_base
       end
 
       private
@@ -28,12 +29,13 @@ module Linzer
 
         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?
+
+        validate_components message, signature.components
       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
+      def verify_or_fail(key, signature, data)
+        return true if key.verify(signature, data)
+        raise Error.new "Failed to verify message: Invalid signature."
       end
     end
   end

data/lib/linzer/version.rb

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

data/lib/linzer.rb

@@ -4,24 +4,24 @@ 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
 
-  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
+    include Key::Helper
+
     def verify(pubkey, message, signature)
       Linzer::Verifier.verify(pubkey, message, signature)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: linzer
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Miguel Landaeta
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-23 00:00:00.000000000 Z
+date: 2024-02-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ed25519
@@ -59,7 +59,14 @@ 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