jwt 2.8.2 → 2.10.2

data/lib/jwt/jwa/hmac.rb

@@ -2,35 +2,42 @@
 
 module JWT
   module JWA
-    module Hmac
-      module_function
+    # Implementation of the HMAC family of algorithms
+    class Hmac
+      include JWT::JWA::SigningAlgorithm
 
-      MAPPING = {
-        'HS256' => OpenSSL::Digest::SHA256,
-        'HS384' => OpenSSL::Digest::SHA384,
-        'HS512' => OpenSSL::Digest::SHA512
-      }.freeze
-
-      SUPPORTED = MAPPING.keys
+      def self.from_algorithm(algorithm)
+        new(algorithm, OpenSSL::Digest.new(algorithm.downcase.gsub('hs', 'sha')))
+      end
 
-      def sign(algorithm, msg, key)
-        key ||= ''
+      def initialize(alg, digest)
+        @alg = alg
+        @digest = digest
+      end
 
-        raise JWT::DecodeError, 'HMAC key expected to be a String' unless key.is_a?(String)
+      def sign(data:, signing_key:)
+        signing_key ||= ''
+        raise_verify_error!('HMAC key expected to be a String') unless signing_key.is_a?(String)
 
-        OpenSSL::HMAC.digest(MAPPING[algorithm].new, key, msg)
+        OpenSSL::HMAC.digest(digest.new, signing_key, data)
       rescue OpenSSL::HMACError => e
-        if key == '' && e.message == 'EVP_PKEY_new_mac_key: malloc failure'
-          raise JWT::DecodeError, 'OpenSSL 3.0 does not support nil or empty hmac_secret'
-        end
+        raise_verify_error!('OpenSSL 3.0 does not support nil or empty hmac_secret') if signing_key == '' && e.message == 'EVP_PKEY_new_mac_key: malloc failure'
 
         raise e
       end
 
-      def verify(algorithm, key, signing_input, signature)
-        SecurityUtils.secure_compare(signature, sign(algorithm, signing_input, key))
+      def verify(data:, signature:, verification_key:)
+        SecurityUtils.secure_compare(signature, sign(data: data, signing_key: verification_key))
       end
 
+      register_algorithm(new('HS256', OpenSSL::Digest::SHA256))
+      register_algorithm(new('HS384', OpenSSL::Digest::SHA384))
+      register_algorithm(new('HS512', OpenSSL::Digest::SHA512))
+
+      private
+
+      attr_reader :digest
+
       # Copy of https://github.com/rails/rails/blob/v7.0.3.1/activesupport/lib/active_support/security_utils.rb
       # rubocop:disable Naming/MethodParameterName, Style/StringLiterals, Style/NumericPredicate
       module SecurityUtils

data/lib/jwt/jwa/hmac_rbnacl.rb

@@ -1,49 +1,49 @@
 # frozen_string_literal: true
 
 module JWT
-  module Algos
-    module HmacRbNaCl
-      MAPPING   = { 'HS512256' => ::RbNaCl::HMAC::SHA512256 }.freeze
-      SUPPORTED = MAPPING.keys
-      class << self
-        def sign(algorithm, msg, key)
-          Deprecations.warning("The use of the algorithm #{algorithm} is deprecated and will be removed in the next major version of ruby-jwt")
-          if (hmac = resolve_algorithm(algorithm))
-            hmac.auth(key_for_rbnacl(hmac, key).encode('binary'), msg.encode('binary'))
-          else
-            Hmac.sign(algorithm, msg, key)
-          end
-        end
-
-        def verify(algorithm, key, signing_input, signature)
-          Deprecations.warning("The use of the algorithm #{algorithm} is deprecated and will be removed in the next major version of ruby-jwt")
-          if (hmac = resolve_algorithm(algorithm))
-            hmac.verify(key_for_rbnacl(hmac, key).encode('binary'), signature.encode('binary'), signing_input.encode('binary'))
-          else
-            Hmac.verify(algorithm, key, signing_input, signature)
-          end
-        rescue ::RbNaCl::BadAuthenticatorError, ::RbNaCl::LengthError
-          false
-        end
-
-        private
-
-        def key_for_rbnacl(hmac, key)
-          key ||= ''
-          raise JWT::DecodeError, 'HMAC key expected to be a String' unless key.is_a?(String)
-
-          return padded_empty_key(hmac.key_bytes) if key == ''
-
-          key
-        end
-
-        def resolve_algorithm(algorithm)
-          MAPPING.fetch(algorithm)
-        end
-
-        def padded_empty_key(length)
-          Array.new(length, 0x0).pack('C*').encode('binary')
-        end
+  module JWA
+    # Implementation of the HMAC family of algorithms (using RbNaCl)
+    class HmacRbNaCl
+      include JWT::JWA::SigningAlgorithm
+
+      def self.from_algorithm(algorithm)
+        new(algorithm, ::RbNaCl::HMAC.const_get(algorithm.upcase.gsub('HS', 'SHA')))
+      end
+
+      def initialize(alg, hmac)
+        @alg = alg
+        @hmac = hmac
+      end
+
+      def sign(data:, signing_key:)
+        Deprecations.warning("The use of the algorithm #{alg} is deprecated and will be removed in the next major version of ruby-jwt")
+        hmac.auth(key_for_rbnacl(hmac, signing_key).encode('binary'), data.encode('binary'))
+      end
+
+      def verify(data:, signature:, verification_key:)
+        Deprecations.warning("The use of the algorithm #{alg} is deprecated and will be removed in the next major version of ruby-jwt")
+        hmac.verify(key_for_rbnacl(hmac, verification_key).encode('binary'), signature.encode('binary'), data.encode('binary'))
+      rescue ::RbNaCl::BadAuthenticatorError, ::RbNaCl::LengthError
+        false
+      end
+
+      register_algorithm(new('HS512256', ::RbNaCl::HMAC::SHA512256))
+
+      private
+
+      attr_reader :hmac
+
+      def key_for_rbnacl(hmac, key)
+        key ||= ''
+        raise JWT::DecodeError, 'HMAC key expected to be a String' unless key.is_a?(String)
+
+        return padded_empty_key(hmac.key_bytes) if key == ''
+
+        key
+      end
+
+      def padded_empty_key(length)
+        Array.new(length, 0x0).pack('C*').encode('binary')
       end
     end
   end

data/lib/jwt/jwa/hmac_rbnacl_fixed.rb

@@ -1,45 +1,46 @@
 # frozen_string_literal: true
 
 module JWT
-  module Algos
-    module HmacRbNaClFixed
-      MAPPING   = { 'HS512256' => ::RbNaCl::HMAC::SHA512256 }.freeze
-      SUPPORTED = MAPPING.keys
-
-      class << self
-        def sign(algorithm, msg, key)
-          key ||= ''
-          Deprecations.warning("The use of the algorithm #{algorithm} is deprecated and will be removed in the next major version of ruby-jwt")
-          raise JWT::DecodeError, 'HMAC key expected to be a String' unless key.is_a?(String)
-
-          if (hmac = resolve_algorithm(algorithm)) && key.bytesize <= hmac.key_bytes
-            hmac.auth(padded_key_bytes(key, hmac.key_bytes), msg.encode('binary'))
-          else
-            Hmac.sign(algorithm, msg, key)
-          end
-        end
-
-        def verify(algorithm, key, signing_input, signature)
-          key ||= ''
-          Deprecations.warning("The use of the algorithm #{algorithm} is deprecated and will be removed in the next major version of ruby-jwt")
-          raise JWT::DecodeError, 'HMAC key expected to be a String' unless key.is_a?(String)
-
-          if (hmac = resolve_algorithm(algorithm)) && key.bytesize <= hmac.key_bytes
-            hmac.verify(padded_key_bytes(key, hmac.key_bytes), signature.encode('binary'), signing_input.encode('binary'))
-          else
-            Hmac.verify(algorithm, key, signing_input, signature)
-          end
-        rescue ::RbNaCl::BadAuthenticatorError, ::RbNaCl::LengthError
-          false
-        end
-
-        def resolve_algorithm(algorithm)
-          MAPPING.fetch(algorithm)
-        end
-
-        def padded_key_bytes(key, bytesize)
-          key.bytes.fill(0, key.bytesize...bytesize).pack('C*')
-        end
+  module JWA
+    # Implementation of the HMAC family of algorithms (using RbNaCl prior to a certain version)
+    class HmacRbNaClFixed
+      include JWT::JWA::SigningAlgorithm
+
+      def self.from_algorithm(algorithm)
+        new(algorithm, ::RbNaCl::HMAC.const_get(algorithm.upcase.gsub('HS', 'SHA')))
+      end
+
+      def initialize(alg, hmac)
+        @alg = alg
+        @hmac = hmac
+      end
+
+      def sign(data:, signing_key:)
+        signing_key ||= ''
+        Deprecations.warning("The use of the algorithm #{alg} is deprecated and will be removed in the next major version of ruby-jwt")
+        raise JWT::DecodeError, 'HMAC key expected to be a String' unless signing_key.is_a?(String)
+
+        hmac.auth(padded_key_bytes(signing_key, hmac.key_bytes), data.encode('binary'))
+      end
+
+      def verify(data:, signature:, verification_key:)
+        verification_key ||= ''
+        Deprecations.warning("The use of the algorithm #{alg} is deprecated and will be removed in the next major version of ruby-jwt")
+        raise JWT::DecodeError, 'HMAC key expected to be a String' unless verification_key.is_a?(String)
+
+        hmac.verify(padded_key_bytes(verification_key, hmac.key_bytes), signature.encode('binary'), data.encode('binary'))
+      rescue ::RbNaCl::BadAuthenticatorError, ::RbNaCl::LengthError
+        false
+      end
+
+      register_algorithm(new('HS512256', ::RbNaCl::HMAC::SHA512256))
+
+      private
+
+      attr_reader :hmac
+
+      def padded_key_bytes(key, bytesize)
+        key.bytes.fill(0, key.bytesize...bytesize).pack('C*')
       end
     end
   end

data/lib/jwt/jwa/none.rb

@@ -2,10 +2,13 @@
 
 module JWT
   module JWA
-    module None
-      module_function
+    # Implementation of the none algorithm
+    class None
+      include JWT::JWA::SigningAlgorithm
 
-      SUPPORTED = %w[none].freeze
+      def initialize
+        @alg = 'none'
+      end
 
       def sign(*)
         ''
@@ -14,6 +17,8 @@ module JWT
       def verify(*)
         true
       end
+
+      register_algorithm(new)
     end
   end
 end

data/lib/jwt/jwa/ps.rb

@@ -2,29 +2,34 @@
 
 module JWT
   module JWA
-    module Ps
-      # RSASSA-PSS signing algorithms
+    # Implementation of the RSASSA-PSS family of algorithms
+    class Ps
+      include JWT::JWA::SigningAlgorithm
 
-      module_function
-
-      SUPPORTED = %w[PS256 PS384 PS512].freeze
-
-      def sign(algorithm, msg, key)
-        unless key.is_a?(::OpenSSL::PKey::RSA)
-          raise EncodeError, "The given key is a #{key_class}. It has to be an OpenSSL::PKey::RSA instance."
-        end
+      def initialize(alg)
+        @alg = alg
+        @digest_algorithm = alg.sub('PS', 'sha')
+      end
 
-        translated_algorithm = algorithm.sub('PS', 'sha')
+      def sign(data:, signing_key:)
+        raise_sign_error!("The given key is a #{signing_key.class}. It has to be an OpenSSL::PKey::RSA instance.") unless signing_key.is_a?(::OpenSSL::PKey::RSA)
 
-        key.sign_pss(translated_algorithm, msg, salt_length: :digest, mgf1_hash: translated_algorithm)
+        signing_key.sign_pss(digest_algorithm, data, salt_length: :digest, mgf1_hash: digest_algorithm)
       end
 
-      def verify(algorithm, public_key, signing_input, signature)
-        translated_algorithm = algorithm.sub('PS', 'sha')
-        public_key.verify_pss(translated_algorithm, signature, signing_input, salt_length: :auto, mgf1_hash: translated_algorithm)
+      def verify(data:, signature:, verification_key:)
+        verification_key.verify_pss(digest_algorithm, signature, data, salt_length: :auto, mgf1_hash: digest_algorithm)
       rescue OpenSSL::PKey::PKeyError
         raise JWT::VerificationError, 'Signature verification raised'
       end
+
+      register_algorithm(new('PS256'))
+      register_algorithm(new('PS384'))
+      register_algorithm(new('PS512'))
+
+      private
+
+      attr_reader :digest_algorithm
     end
   end
 end

data/lib/jwt/jwa/rsa.rb

@@ -2,24 +2,34 @@
 
 module JWT
   module JWA
-    module Rsa
-      module_function
+    # Implementation of the RSA family of algorithms
+    class Rsa
+      include JWT::JWA::SigningAlgorithm
 
-      SUPPORTED = %w[RS256 RS384 RS512].freeze
+      def initialize(alg)
+        @alg = alg
+        @digest = alg.sub('RS', 'SHA')
+      end
 
-      def sign(algorithm, msg, key)
-        unless key.is_a?(OpenSSL::PKey::RSA)
-          raise EncodeError, "The given key is a #{key.class}. It has to be an OpenSSL::PKey::RSA instance"
-        end
+      def sign(data:, signing_key:)
+        raise_sign_error!("The given key is a #{signing_key.class}. It has to be an OpenSSL::PKey::RSA instance") unless signing_key.is_a?(OpenSSL::PKey::RSA)
 
-        key.sign(OpenSSL::Digest.new(algorithm.sub('RS', 'sha')), msg)
+        signing_key.sign(OpenSSL::Digest.new(digest), data)
       end
 
-      def verify(algorithm, public_key, signing_input, signature)
-        public_key.verify(OpenSSL::Digest.new(algorithm.sub('RS', 'sha')), signature, signing_input)
+      def verify(data:, signature:, verification_key:)
+        verification_key.verify(OpenSSL::Digest.new(digest), signature, data)
       rescue OpenSSL::PKey::PKeyError
         raise JWT::VerificationError, 'Signature verification raised'
       end
+
+      register_algorithm(new('RS256'))
+      register_algorithm(new('RS384'))
+      register_algorithm(new('RS512'))
+
+      private
+
+      attr_reader :digest
     end
   end
 end

data/lib/jwt/jwa/signing_algorithm.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module JWT
+  # JSON Web Algorithms
+  module JWA
+    # Base functionality for signing algorithms
+    module SigningAlgorithm
+      # Class methods for the SigningAlgorithm module
+      module ClassMethods
+        def register_algorithm(algo)
+          ::JWT::JWA.register_algorithm(algo)
+        end
+      end
+
+      def self.included(klass)
+        klass.extend(ClassMethods)
+        klass.include(JWT::JWA::Compat)
+      end
+
+      attr_reader :alg
+
+      def valid_alg?(alg_to_check)
+        alg&.casecmp(alg_to_check)&.zero? == true
+      end
+
+      def header(*)
+        { 'alg' => alg }
+      end
+
+      def sign(*)
+        raise_sign_error!('Algorithm implementation is missing the sign method')
+      end
+
+      def verify(*)
+        raise_verify_error!('Algorithm implementation is missing the verify method')
+      end
+
+      def raise_verify_error!(message)
+        raise(DecodeError.new(message).tap { |e| e.set_backtrace(caller(1)) })
+      end
+
+      def raise_sign_error!(message)
+        raise(EncodeError.new(message).tap { |e| e.set_backtrace(caller(1)) })
+      end
+    end
+
+    class << self
+      def register_algorithm(algo)
+        algorithms[algo.alg.to_s.downcase] = algo
+      end
+
+      def find(algo)
+        algorithms.fetch(algo.to_s.downcase, Unsupported)
+      end
+
+      private
+
+      def algorithms
+        @algorithms ||= {}
+      end
+    end
+  end
+end

data/lib/jwt/jwa/unsupported.rb

@@ -2,17 +2,18 @@
 
 module JWT
   module JWA
+    # Represents an unsupported algorithm
     module Unsupported
-      module_function
+      class << self
+        include JWT::JWA::SigningAlgorithm
 
-      SUPPORTED = [].freeze
+        def sign(*)
+          raise_sign_error!('Unsupported signing method')
+        end
 
-      def sign(*)
-        raise NotImplementedError, 'Unsupported signing method'
-      end
-
-      def verify(*)
-        raise JWT::VerificationError, 'Algorithm not supported'
+        def verify(*)
+          raise JWT::VerificationError, 'Algorithm not supported'
+        end
       end
     end
   end

data/lib/jwt/jwa/wrapper.rb

@@ -2,24 +2,42 @@
 
 module JWT
   module JWA
+    # @api private
     class Wrapper
-      attr_reader :alg, :cls
+      include SigningAlgorithm
 
-      def initialize(alg, cls)
-        @alg = alg
-        @cls = cls
+      def initialize(algorithm)
+        @algorithm = algorithm
+      end
+
+      def alg
+        return @algorithm.alg if @algorithm.respond_to?(:alg)
+
+        super
       end
 
       def valid_alg?(alg_to_check)
-        alg&.casecmp(alg_to_check)&.zero? == true
+        return @algorithm.valid_alg?(alg_to_check) if @algorithm.respond_to?(:valid_alg?)
+
+        super
       end
 
-      def sign(data:, signing_key:)
-        cls.sign(alg, data, signing_key)
+      def header(*args, **kwargs)
+        return @algorithm.header(*args, **kwargs) if @algorithm.respond_to?(:header)
+
+        super
       end
 
-      def verify(data:, signature:, verification_key:)
-        cls.verify(alg, verification_key, data, signature)
+      def sign(*args, **kwargs)
+        return @algorithm.sign(*args, **kwargs) if @algorithm.respond_to?(:sign)
+
+        super
+      end
+
+      def verify(*args, **kwargs)
+        return @algorithm.verify(*args, **kwargs) if @algorithm.respond_to?(:verify)
+
+        super
       end
     end
   end

data/lib/jwt/jwa.rb

@@ -8,54 +8,50 @@ rescue LoadError
   raise if defined?(RbNaCl)
 end
 
-require_relative 'jwa/hmac'
-require_relative 'jwa/eddsa'
+require_relative 'jwa/compat'
+require_relative 'jwa/signing_algorithm'
 require_relative 'jwa/ecdsa'
-require_relative 'jwa/rsa'
-require_relative 'jwa/ps'
+require_relative 'jwa/hmac'
 require_relative 'jwa/none'
+require_relative 'jwa/ps'
+require_relative 'jwa/rsa'
 require_relative 'jwa/unsupported'
 require_relative 'jwa/wrapper'
 
+require_relative 'jwa/eddsa' if JWT.rbnacl?
+
+if JWT.rbnacl_6_or_greater?
+  require_relative 'jwa/hmac_rbnacl'
+elsif JWT.rbnacl?
+  require_relative 'jwa/hmac_rbnacl_fixed'
+end
+
 module JWT
+  # The JWA module contains all supported algorithms.
   module JWA
-    ALGOS = [Hmac, Ecdsa, Rsa, Eddsa, Ps, None, Unsupported].tap do |l|
-      if ::JWT.rbnacl_6_or_greater?
-        require_relative 'jwa/hmac_rbnacl'
-        l << Algos::HmacRbNaCl
-      elsif ::JWT.rbnacl?
-        require_relative 'jwa/hmac_rbnacl_fixed'
-        l << Algos::HmacRbNaClFixed
-      end
-    end.freeze
-
     class << self
-      def find(algorithm)
-        indexed[algorithm&.downcase]
-      end
+      # @api private
+      def resolve(algorithm)
+        return find(algorithm) if algorithm.is_a?(String) || algorithm.is_a?(Symbol)
 
-      def create(algorithm)
-        return algorithm if JWA.implementation?(algorithm)
+        unless algorithm.is_a?(SigningAlgorithm)
+          Deprecations.warning('Custom algorithms are required to include JWT::JWA::SigningAlgorithm. Custom algorithms that do not include this module may stop working in the next major version of ruby-jwt.')
+          return Wrapper.new(algorithm)
+        end
 
-        Wrapper.new(*find(algorithm))
+        algorithm
       end
 
-      def implementation?(algorithm)
-        (algorithm.respond_to?(:valid_alg?) && algorithm.respond_to?(:verify)) ||
-          (algorithm.respond_to?(:alg) && algorithm.respond_to?(:sign))
+      # @api private
+      def resolve_and_sort(algorithms:, preferred_algorithm:)
+        algs = Array(algorithms).map { |alg| JWA.resolve(alg) }
+        algs.partition { |alg| alg.valid_alg?(preferred_algorithm) }.flatten
       end
 
-      private
-
-      def indexed
-        @indexed ||= begin
-          fallback = [nil, Unsupported]
-          ALGOS.each_with_object(Hash.new(fallback)) do |cls, hash|
-            cls.const_get(:SUPPORTED).each do |alg|
-              hash[alg.downcase] = [alg, cls]
-            end
-          end
-        end
+      # @deprecated The `::JWT::JWA.create` method is deprecated and will be removed in the next major version of ruby-jwt.
+      def create(algorithm)
+        Deprecations.warning('The ::JWT::JWA.create method is deprecated and will be removed in the next major version of ruby-jwt.')
+        resolve(algorithm)
       end
     end
   end

data/lib/jwt/jwk/ec.rb

@@ -4,6 +4,7 @@ require 'forwardable'
 
 module JWT
   module JWK
+    # JWK representation for Elliptic Curve (EC) keys
     class EC < KeyBase # rubocop:disable Metrics/ClassLength
       KTY    = 'EC'
       KTYS   = [KTY, OpenSSL::PKey::EC, JWT::JWK::EC].freeze
@@ -65,9 +66,7 @@ module JWT
       end
 
       def []=(key, value)
-        if EC_KEY_ELEMENTS.include?(key.to_sym)
-          raise ArgumentError, 'cannot overwrite cryptographic key attributes'
-        end
+        raise ArgumentError, 'cannot overwrite cryptographic key attributes' if EC_KEY_ELEMENTS.include?(key.to_sym)
 
         super(key, value)
       end

data/lib/jwt/jwk/hmac.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # JWK for HMAC keys
     class HMAC < KeyBase
       KTY  = 'oct'
       KTYS = [KTY, String, JWT::JWK::HMAC].freeze
@@ -61,9 +62,7 @@ module JWT
       end
 
       def []=(key, value)
-        if HMAC_KEY_ELEMENTS.include?(key.to_sym)
-          raise ArgumentError, 'cannot overwrite cryptographic key attributes'
-        end
+        raise ArgumentError, 'cannot overwrite cryptographic key attributes' if HMAC_KEY_ELEMENTS.include?(key.to_sym)
 
         super(key, value)
       end

data/lib/jwt/jwk/key_base.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # Base for JWK implementations
     class KeyBase
       def self.inherited(klass)
         super

data/lib/jwt/jwk/key_finder.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # @api private
     class KeyFinder
       def initialize(options)
         @allow_nil_kid = options[:allow_nil_kid]

data/lib/jwt/jwk/kid_as_key_digest.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module JWK
+    # @api private
     class KidAsKeyDigest
       def initialize(jwk)
         @jwk = jwk