jwt 2.3.0 → 2.10.1

data/lib/jwt/error.rb

@@ -1,21 +1,57 @@
 # frozen_string_literal: true
 
 module JWT
+  # The EncodeError class is raised when there is an error encoding a JWT.
   class EncodeError < StandardError; end
+
+  # The DecodeError class is raised when there is an error decoding a JWT.
   class DecodeError < StandardError; end
+
+  # The RequiredDependencyError class is raised when a required dependency is missing.
   class RequiredDependencyError < StandardError; end
 
+  # The VerificationError class is raised when there is an error verifying a JWT.
   class VerificationError < DecodeError; end
+
+  # The ExpiredSignature class is raised when the JWT signature has expired.
   class ExpiredSignature < DecodeError; end
+
+  # The IncorrectAlgorithm class is raised when the JWT algorithm is incorrect.
   class IncorrectAlgorithm < DecodeError; end
+
+  # The ImmatureSignature class is raised when the JWT signature is immature.
   class ImmatureSignature < DecodeError; end
+
+  # The InvalidIssuerError class is raised when the JWT issuer is invalid.
   class InvalidIssuerError < DecodeError; end
+
+  # The UnsupportedEcdsaCurve class is raised when the ECDSA curve is unsupported.
+  class UnsupportedEcdsaCurve < IncorrectAlgorithm; end
+
+  # The InvalidIatError class is raised when the JWT issued at (iat) claim is invalid.
   class InvalidIatError < DecodeError; end
+
+  # The InvalidAudError class is raised when the JWT audience (aud) claim is invalid.
   class InvalidAudError < DecodeError; end
+
+  # The InvalidSubError class is raised when the JWT subject (sub) claim is invalid.
   class InvalidSubError < DecodeError; end
+
+  # The InvalidCritError class is raised when the JWT crit header is invalid.
+  class InvalidCritError < DecodeError; end
+
+  # The InvalidJtiError class is raised when the JWT ID (jti) claim is invalid.
   class InvalidJtiError < DecodeError; end
+
+  # The InvalidPayload class is raised when the JWT payload is invalid.
   class InvalidPayload < DecodeError; end
+
+  # The MissingRequiredClaim class is raised when a required claim is missing from the JWT.
   class MissingRequiredClaim < DecodeError; end
 
+  # The Base64DecodeError class is raised when there is an error decoding a Base64-encoded string.
+  class Base64DecodeError < DecodeError; end
+
+  # The JWKError class is raised when there is an error with the JSON Web Key (JWK).
   class JWKError < DecodeError; end
 end

data/lib/jwt/json.rb

@@ -3,7 +3,7 @@
 require 'json'
 
 module JWT
-  # JSON wrapper
+  # @api private
   class JSON
     class << self
       def generate(data)

data/lib/jwt/jwa/compat.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module JWT
+  module JWA
+    # Provides backwards compatibility for algorithms
+    # @api private
+    module Compat
+      # @api private
+      module ClassMethods
+        def from_algorithm(algorithm)
+          new(algorithm)
+        end
+
+        def sign(algorithm, msg, key)
+          Deprecations.warning('Support for calling sign with positional arguments will be removed in future ruby-jwt versions')
+
+          from_algorithm(algorithm).sign(data: msg, signing_key: key)
+        end
+
+        def verify(algorithm, key, signing_input, signature)
+          Deprecations.warning('Support for calling verify with positional arguments will be removed in future ruby-jwt versions')
+
+          from_algorithm(algorithm).verify(data: signing_input, signature: signature, verification_key: key)
+        end
+      end
+
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/jwt/jwa/ecdsa.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module JWT
+  module JWA
+    # ECDSA signing algorithm
+    class Ecdsa
+      include JWT::JWA::SigningAlgorithm
+
+      def initialize(alg, digest)
+        @alg = alg
+        @digest = OpenSSL::Digest.new(digest)
+      end
+
+      def sign(data:, signing_key:)
+        curve_definition = curve_by_name(signing_key.group.curve_name)
+        key_algorithm = curve_definition[:algorithm]
+        raise IncorrectAlgorithm, "payload algorithm is #{alg} but #{key_algorithm} signing key was provided" if alg != key_algorithm
+
+        asn1_to_raw(signing_key.dsa_sign_asn1(digest.digest(data)), signing_key)
+      end
+
+      def verify(data:, signature:, verification_key:)
+        curve_definition = curve_by_name(verification_key.group.curve_name)
+        key_algorithm = curve_definition[:algorithm]
+        raise IncorrectAlgorithm, "payload algorithm is #{alg} but #{key_algorithm} verification key was provided" if alg != key_algorithm
+
+        verification_key.dsa_verify_asn1(digest.digest(data), raw_to_asn1(signature, verification_key))
+      rescue OpenSSL::PKey::PKeyError
+        raise JWT::VerificationError, 'Signature verification raised'
+      end
+
+      NAMED_CURVES = {
+        'prime256v1' => {
+          algorithm: 'ES256',
+          digest: 'sha256'
+        },
+        'secp256r1' => { # alias for prime256v1
+          algorithm: 'ES256',
+          digest: 'sha256'
+        },
+        'secp384r1' => {
+          algorithm: 'ES384',
+          digest: 'sha384'
+        },
+        'secp521r1' => {
+          algorithm: 'ES512',
+          digest: 'sha512'
+        },
+        'secp256k1' => {
+          algorithm: 'ES256K',
+          digest: 'sha256'
+        }
+      }.freeze
+
+      NAMED_CURVES.each_value do |v|
+        register_algorithm(new(v[:algorithm], v[:digest]))
+      end
+
+      def self.from_algorithm(algorithm)
+        new(algorithm, algorithm.downcase.gsub('es', 'sha'))
+      end
+
+      def self.curve_by_name(name)
+        NAMED_CURVES.fetch(name) do
+          raise UnsupportedEcdsaCurve, "The ECDSA curve '#{name}' is not supported"
+        end
+      end
+
+      private
+
+      attr_reader :digest
+
+      def curve_by_name(name)
+        self.class.curve_by_name(name)
+      end
+
+      def raw_to_asn1(signature, private_key)
+        byte_size = (private_key.group.degree + 7) / 8
+        sig_bytes = signature[0..(byte_size - 1)]
+        sig_char = signature[byte_size..-1] || ''
+        OpenSSL::ASN1::Sequence.new([sig_bytes, sig_char].map { |int| OpenSSL::ASN1::Integer.new(OpenSSL::BN.new(int, 2)) }).to_der
+      end
+
+      def asn1_to_raw(signature, public_key)
+        byte_size = (public_key.group.degree + 7) / 8
+        OpenSSL::ASN1.decode(signature).value.map { |value| value.value.to_s(2).rjust(byte_size, "\x00") }.join
+      end
+    end
+  end
+end

data/lib/jwt/jwa/eddsa.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module JWT
+  module JWA
+    # Implementation of the EdDSA family of algorithms
+    class Eddsa
+      include JWT::JWA::SigningAlgorithm
+
+      def initialize(alg)
+        @alg = alg
+      end
+
+      def sign(data:, signing_key:)
+        raise_sign_error!("Key given is a #{signing_key.class} but has to be an RbNaCl::Signatures::Ed25519::SigningKey") unless signing_key.is_a?(RbNaCl::Signatures::Ed25519::SigningKey)
+
+        Deprecations.warning('Using Ed25519 keys is deprecated and will be removed in a future version of ruby-jwt. Please use the ruby-eddsa gem instead.')
+
+        signing_key.sign(data)
+      end
+
+      def verify(data:, signature:, verification_key:)
+        raise_verify_error!("key given is a #{verification_key.class} but has to be a RbNaCl::Signatures::Ed25519::VerifyKey") unless verification_key.is_a?(RbNaCl::Signatures::Ed25519::VerifyKey)
+
+        Deprecations.warning('Using Ed25519 keys is deprecated and will be removed in a future version of ruby-jwt. Please use the ruby-eddsa gem instead.')
+
+        verification_key.verify(signature, data)
+      rescue RbNaCl::CryptoError
+        false
+      end
+
+      register_algorithm(new('ED25519'))
+      register_algorithm(new('EdDSA'))
+    end
+  end
+end

data/lib/jwt/jwa/hmac.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module JWT
+  module JWA
+    # Implementation of the HMAC family of algorithms
+    class Hmac
+      include JWT::JWA::SigningAlgorithm
+
+      def self.from_algorithm(algorithm)
+        new(algorithm, OpenSSL::Digest.new(algorithm.downcase.gsub('hs', 'sha')))
+      end
+
+      def initialize(alg, digest)
+        @alg = alg
+        @digest = digest
+      end
+
+      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(digest.new, signing_key, data)
+      rescue OpenSSL::HMACError => e
+        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(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
+        # Constant time string comparison, for fixed length strings.
+        #
+        # The values compared should be of fixed length, such as strings
+        # that have already been processed by HMAC. Raises in case of length mismatch.
+
+        if defined?(OpenSSL.fixed_length_secure_compare)
+          def fixed_length_secure_compare(a, b)
+            OpenSSL.fixed_length_secure_compare(a, b)
+          end
+        else
+          # :nocov:
+          def fixed_length_secure_compare(a, b)
+            raise ArgumentError, "string length mismatch." unless a.bytesize == b.bytesize
+
+            l = a.unpack "C#{a.bytesize}"
+
+            res = 0
+            b.each_byte { |byte| res |= byte ^ l.shift }
+            res == 0
+          end
+          # :nocov:
+        end
+        module_function :fixed_length_secure_compare
+
+        # Secure string comparison for strings of variable length.
+        #
+        # While a timing attack would not be able to discern the content of
+        # a secret compared via secure_compare, it is possible to determine
+        # the secret length. This should be considered when using secure_compare
+        # to compare weak, short secrets to user input.
+        def secure_compare(a, b)
+          a.bytesize == b.bytesize && fixed_length_secure_compare(a, b)
+        end
+        module_function :secure_compare
+      end
+      # rubocop:enable Naming/MethodParameterName, Style/StringLiterals, Style/NumericPredicate
+    end
+  end
+end

data/lib/jwt/jwa/hmac_rbnacl.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module JWT
+  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
+end

data/lib/jwt/jwa/hmac_rbnacl_fixed.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module JWT
+  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
+end

data/lib/jwt/jwa/none.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module JWT
+  module JWA
+    # Implementation of the none algorithm
+    class None
+      include JWT::JWA::SigningAlgorithm
+
+      def initialize
+        @alg = 'none'
+      end
+
+      def sign(*)
+        ''
+      end
+
+      def verify(*)
+        true
+      end
+
+      register_algorithm(new)
+    end
+  end
+end

data/lib/jwt/jwa/ps.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module JWT
+  module JWA
+    # Implementation of the RSASSA-PSS family of algorithms
+    class Ps
+      include JWT::JWA::SigningAlgorithm
+
+      def initialize(alg)
+        @alg = alg
+        @digest_algorithm = alg.sub('PS', 'sha')
+      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)
+
+        signing_key.sign_pss(digest_algorithm, data, salt_length: :digest, mgf1_hash: digest_algorithm)
+      end
+
+      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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module JWT
+  module JWA
+    # Implementation of the RSA family of algorithms
+    class Rsa
+      include JWT::JWA::SigningAlgorithm
+
+      def initialize(alg)
+        @alg = alg
+        @digest = OpenSSL::Digest.new(alg.sub('RS', 'SHA'))
+      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)
+
+        signing_key.sign(digest, data)
+      end
+
+      def verify(data:, signature:, verification_key:)
+        verification_key.verify(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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module JWT
+  module JWA
+    # Represents an unsupported algorithm
+    module Unsupported
+      class << self
+        include JWT::JWA::SigningAlgorithm
+
+        def sign(*)
+          raise_sign_error!('Unsupported signing method')
+        end
+
+        def verify(*)
+          raise JWT::VerificationError, 'Algorithm not supported'
+        end
+      end
+    end
+  end
+end

data/lib/jwt/jwa/wrapper.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module JWT
+  module JWA
+    # @api private
+    class Wrapper
+      include SigningAlgorithm
+
+      def initialize(algorithm)
+        @algorithm = algorithm
+      end
+
+      def alg
+        return @algorithm.alg if @algorithm.respond_to?(:alg)
+
+        super
+      end
+
+      def valid_alg?(alg_to_check)
+        return @algorithm.valid_alg?(alg_to_check) if @algorithm.respond_to?(:valid_alg?)
+
+        super
+      end
+
+      def header(*args, **kwargs)
+        return @algorithm.header(*args, **kwargs) if @algorithm.respond_to?(:header)
+
+        super
+      end
+
+      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
+end

data/lib/jwt/jwa.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+begin
+  require 'rbnacl'
+rescue LoadError
+  raise if defined?(RbNaCl)
+end
+
+require_relative 'jwa/compat'
+require_relative 'jwa/signing_algorithm'
+require_relative 'jwa/ecdsa'
+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
+    class << self
+      # @api private
+      def resolve(algorithm)
+        return find(algorithm) if algorithm.is_a?(String) || algorithm.is_a?(Symbol)
+
+        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
+
+        algorithm
+      end
+
+      # @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
+
+      # @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
+end