jwt 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bc851245c9a662d91209f426033dc2b2521de4cd07f11529aa34c0e69ad9201
-  data.tar.gz: fa9ae48864cb04df26a6e003e90430b1dcf85ad4ba1da707ea688b6efd43b9b4
+  metadata.gz: a9dd430911612a1bef370bffdf46f432a9ec2027f2091efd8d47e6d237d8c935
+  data.tar.gz: 6fa7001bc60edeb8c984cddef3bf5d9beb42656555593ad8ffc2dfe3ef4b76e8
 SHA512:
-  metadata.gz: 26e15ad0fa03a06b830b380d74b2efbc23a85ecdc8f3a72b1d938706622c83d28217167e87eec73c7633dfc0ee3656c0c2d2ba4fd604cedb1289cc36d730706c
-  data.tar.gz: 0076ad48c7dcc3ddc3fa55b776ca4566452c17aae211af36616634429e37fd687fb29fcf5e0fea5ee32945fe2359784f2ee48535a76509f90813dfe481892394
+  metadata.gz: 11a6a56acb50a86223e7f60f413ac723c34997bd7ad5f2bbf2376e6c66fbfca1991a08301147062e7d5835f8fd530509b53a80876781d890d52e7fab7389fe18
+  data.tar.gz: 44f001cb3c746e4fe502a72fa9bc9234066a687145443c14cd4b09ef2bd184d119bf0d99accbfd3cd748e0eb1e8696fd90446cc3be4851ead641adbba9246b7c

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [v3.1.0](https://github.com/jwt/ruby-jwt/tree/v3.1.0) (2025-06-23)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v3.0.0...v3.1.0)
+
+**Features:**
+
+- Add support for x5t header parameter for X.509 certificate thumbprint verification [#669](https://github.com/jwt/ruby-jwt/pull/669) ([@hieuk09](https://github.com/hieuk09))
+- Raise an error if the ECDSA signing or verification key is not an instance of `OpenSSL::PKey::EC` [#688](https://github.com/jwt/ruby-jwt/pull/688) ([@anakinj](https://github.com/anakinj))
+- Allow `OpenSSL::PKey::EC::Point` to be used as the verification key in ECDSA [#689](https://github.com/jwt/ruby-jwt/pull/689) ([@anakinj](https://github.com/anakinj))
+- Require claims to have been verified before accessing the `JWT::EncodedToken#payload` [#690](https://github.com/jwt/ruby-jwt/pull/690) ([@anakinj](https://github.com/anakinj))
+- Support signing and verifying tokens using a JWK [#692](https://github.com/jwt/ruby-jwt/pull/692) ([@anakinj](https://github.com/anakinj))
+
 ## [v3.0.0](https://github.com/jwt/ruby-jwt/tree/v3.0.0) (2025-06-14)
 
 [Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.10.1...v3.0.0)

data/README.md

@@ -9,11 +9,7 @@ A ruby implementation of the [RFC 7519 OAuth JSON Web Token (JWT)](https://tools
 
 If you have further questions related to development or usage, join us: [ruby-jwt google group](https://groups.google.com/forum/#!forum/ruby-jwt).
 
-See [CHANGELOG.md](CHANGELOG.md) for a complete set of changes.
-
-## Upcoming breaking changes
-
-Check out breaking changes in the upcoming **version 3.0** from the [upgrade guide](UPGRADING.md)
+See [CHANGELOG.md](CHANGELOG.md) for a complete set of changes and [upgrade guide](UPGRADING.md) for upgrading between major versions.
 
 ## Sponsors
 
@@ -60,24 +56,15 @@ See [JSON Web Algorithms (JWA) 3.1. "alg" (Algorithm) Header Parameter Values fo
 - none - unsigned token
 
 ```ruby
-
 payload = { data: 'test' }
+token   = JWT.encode(payload, nil, 'none')
+# => "eyJhbGciOiJub25lIn0.eyJkYXRhIjoidGVzdCJ9."
 
-# IMPORTANT: set nil as password parameter
-token = JWT.encode(payload, nil, 'none')
-
-# eyJhbGciOiJub25lIn0.eyJkYXRhIjoidGVzdCJ9.
-puts token
-
-# Set password to nil and validation to false otherwise this won't work
-decoded_token = JWT.decode(token, nil, false)
-
-# Array
-# [
-#   {"data"=>"test"}, # payload
-#   {"alg"=>"none"} # header
-# ]
-puts decoded_token
+decoded_token = JWT.decode(token, nil, true, { algorithm: 'none' })
+#  => [
+#       {"data"=>"test"}, # payload
+#       {"alg"=>"none"} # header
+#     ]
 ```
 
 ### **HMAC**
@@ -87,22 +74,17 @@ puts decoded_token
 - HS512 - HMAC using SHA-512 hash algorithm
 
 ```ruby
-# The secret must be a string. With OpenSSL 3.0/openssl gem `<3.0.1`, JWT::DecodeError will be raised if it isn't provided.
+payload     = { data: 'test' }
 hmac_secret = 'my$ecretK3y'
 
 token = JWT.encode(payload, hmac_secret, 'HS256')
-
-# eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.pNIWIL34Jo13LViZAJACzK6Yf0qnvT_BuwOxiMCPE-Y
-puts token
+# => "eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.pNIWIL34Jo13LViZAJACzK6Yf0qnvT_BuwOxiMCPE-Y"
 
 decoded_token = JWT.decode(token, hmac_secret, true, { algorithm: 'HS256' })
-
-# Array
-# [
-#   {"data"=>"test"}, # payload
-#   {"alg"=>"HS256"} # header
-# ]
-puts decoded_token
+# => [
+#      {"data"=>"test"}, # payload
+#      {"alg"=>"HS256"} # header
+#    ]
 ```
 
 ### **RSA**
@@ -112,22 +94,18 @@ puts decoded_token
 - RS512 - RSA using SHA-512 hash algorithm
 
 ```ruby
+payload     = { data: 'test' }
 rsa_private = OpenSSL::PKey::RSA.generate(2048)
-rsa_public = rsa_private.public_key
+rsa_public  = rsa_private.public_key
 
 token = JWT.encode(payload, rsa_private, 'RS256')
-
-# eyJhbGciOiJSUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.GplO4w1spRgvEJQ3-FOtZr-uC8L45Jt7SN0J4woBnEXG_OZBSNcZjAJWpjadVYEe2ev3oUBFDYM1N_-0BTVeFGGYvMewu8E6aMjSZvOpf1cZBew-Vt4poSq7goG2YRI_zNPt3af2lkPqXD796IKC5URrEvcgF5xFQ-6h07XRDpSRx1ECrNsUOt7UM3l1IB4doY11GzwQA5sHDTmUZ0-kBT76ZMf12Srg_N3hZwphxBtudYtN5VGZn420sVrQMdPE_7Ni3EiWT88j7WCr1xrF60l8sZT3yKCVleG7D2BEXacTntB7GktBv4Xo8OKnpwpqTpIlC05dMowMkz3rEAAYbQ
-puts token
+# => "eyJhbGciOiJSUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.CCkO35qFPijW8Gwhbt8a80PB9fc9FJ19hCMnXSgoDF6Mlvlt0A4G-ah..."
 
 decoded_token = JWT.decode(token, rsa_public, true, { algorithm: 'RS256' })
-
-# Array
-# [
-#   {"data"=>"test"}, # payload
-#   {"alg"=>"RS256"} # header
-# ]
-puts decoded_token
+# => [
+#      {"data"=>"test"}, # payload
+#      {"alg"=>"RS256"} # header
+#    ]
 ```
 
 ### **ECDSA**
@@ -138,26 +116,22 @@ puts decoded_token
 - ES256K - ECDSA using P-256K and SHA-256
 
 ```ruby
+payload   = { data: 'test' }
 ecdsa_key = OpenSSL::PKey::EC.generate('prime256v1')
 
 token = JWT.encode(payload, ecdsa_key, 'ES256')
-
-# eyJhbGciOiJFUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.AlLW--kaF7EX1NMX9WJRuIW8NeRJbn2BLXHns7Q5TZr7Hy3lF6MOpMlp7GoxBFRLISQ6KrD0CJOrR8aogEsPeg
-puts token
+# => "eyJhbGciOiJFUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.AlLW--kaF7EX1NMX9WJRuIW8NeRJbn2BLXHns7Q5TZr7Hy3lF6MOpMlp7GoxBFRLISQ6KrD0CJOrR8aogEsPeg"
 
 decoded_token = JWT.decode(token, ecdsa_key, true, { algorithm: 'ES256' })
-
-# Array
-# [
-#    {"test"=>"data"}, # payload
-#    {"alg"=>"ES256"} # header
-# ]
-puts decoded_token
+# => [
+#      {"test"=>"data"}, # payload
+#      {"alg"=>"ES256"} # header
+#    ]
 ```
 
 ### **EdDSA**
 
-This algorithm has since version 3.0 been moved to the [jwt-eddsa gem](https://rubygems.org/gems/jwt-eddsa).
+Since version 3.0, the EdDSA algorithm has been moved to the [jwt-eddsa gem](https://rubygems.org/gems/jwt-eddsa).
 
 ### **RSASSA-PSS**
 
@@ -166,22 +140,18 @@ This algorithm has since version 3.0 been moved to the [jwt-eddsa gem](https://r
 - PS512 - RSASSA-PSS using SHA-512 hash algorithm
 
 ```ruby
+payload     = { data: 'test' }
 rsa_private = OpenSSL::PKey::RSA.generate(2048)
-rsa_public = rsa_private.public_key
+rsa_public  = rsa_private.public_key
 
 token = JWT.encode(payload, rsa_private, 'PS256')
-
-# eyJhbGciOiJQUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.KEmqagMUHM-NcmXo6818ZazVTIAkn9qU9KQFT1c5Iq91n0KRpAI84jj4ZCdkysDlWokFs3Dmn4MhcXP03oJKLFgnoPL40_Wgg9iFr0jnIVvnMUp1kp2RFUbL0jqExGTRA3LdAhuvw6ZByGD1bkcWjDXygjQw-hxILrT1bENjdr0JhFd-cB0-ps5SB0mwhFNcUw-OM3Uu30B1-mlFaelUY8jHJYKwLTZPNxHzndt8RGXF8iZLp7dGb06HSCKMcVzhASGMH4ZdFystRe2hh31cwcvnl-Eo_D4cdwmpN3Abhk_8rkxawQJR3duh8HNKc4AyFPo7SabEaSu2gLnLfN3yfg
-puts token
+# => "eyJhbGciOiJQUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.BRWizdUjD5zAWw-EDBcrl3dDpQDAePz9Ol3XKC43SggU47G8OWwveA_..."
 
 decoded_token = JWT.decode(token, rsa_public, true, { algorithm: 'PS256' })
-
-# Array
-# [
-#   {"data"=>"test"}, # payload
-#   {"alg"=>"PS256"} # header
-# ]
-puts decoded_token
+# => [
+#      {"data"=>"test"}, # payload
+#      {"alg"=>"PS256"} # header
+#    ]
 ```
 
 ### **Custom algorithms**
@@ -210,8 +180,15 @@ module CustomHS512Algorithm
   end
 end
 
-token = ::JWT.encode({'pay' => 'load'}, 'secret', CustomHS512Algorithm)
-payload, header = ::JWT.decode(token, 'secret', true, algorithm: CustomHS512Algorithm)
+payload  = { data: 'test' }
+token    = JWT.encode(payload, 'secret', CustomHS512Algorithm)
+# => "eyJhbGciOiJIUzUxMiJ9.eyJkYXRhIjoidGVzdCJ9.aBNoejLEM2WMF3TxzRDKlehYdG2ATvFpGNauTI4GSD2VJseS_sC8covrVMlgslf0aJM4SKb3EIeORJBFPtZ33w"
+
+decoded_token = JWT.decode(token, 'secret', true, algorithm: CustomHS512Algorithm)
+# => [
+#      {"data"=>"test"}, # payload
+#      {"alg"=>"HS512"} # header
+#    ]
 ```
 
 ### Add custom header fields
@@ -220,30 +197,16 @@ The ruby-jwt gem supports custom [header fields](https://tools.ietf.org/html/rfc
 To add custom header fields you need to pass `header_fields` parameter
 
 ```ruby
-token = JWT.encode(payload, key, 'HS256', {})
-```
-
-**Example:**
-
-```ruby
-
 payload = { data: 'test' }
 
-# IMPORTANT: set nil as password parameter
 token = JWT.encode(payload, nil, 'none', { typ: 'JWT' })
+# => "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJkYXRhIjoidGVzdCJ9."
 
-# eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJkYXRhIjoidGVzdCJ9.
-puts token
-
-# Set password to nil and validation to false otherwise this won't work
-decoded_token = JWT.decode(token, nil, false)
-
-# Array
-# [
-#   {"data"=>"test"}, # payload
-#   {"typ"=>"JWT", "alg"=>"none"} # header
-# ]
-puts decoded_token
+decoded_token = JWT.decode(token, nil, true, { algorithm: 'none' })
+#  => [
+#       {"data"=>"test"}, # payload
+#       {"typ"=>"JWT", "alg"=>"none"} # header
+#     ]
 ```
 
 ## `JWT::Token` and `JWT::EncodedToken`
@@ -253,10 +216,14 @@ The `JWT::Token` and `JWT::EncodedToken` classes can be used to manage your JWTs
 ### Signing and encoding a token
 
 ```ruby
-token = JWT::Token.new(payload: { exp: Time.now.to_i + 60, jti: '1234', sub: "my-subject" }, header: { kid: 'hmac' })
+payload = { exp: Time.now.to_i + 60, jti: '1234', sub: "my-subject" }
+header =  { kid: 'hmac' }
+
+token = JWT::Token.new(payload: payload, header: header)
 token.sign!(algorithm: 'HS256', key: "secret")
 
-token.jwt # => "eyJhbGciOiJIUzI1N..."
+token.jwt
+# => "eyJraWQiOiJobWFjIiwiYWxnIjoiSFMyNTYifQ.eyJleHAiOjE3NTAwMDU0NzksImp0aSI6IjEyMzQiLCJzdWIiOiJteS1zdWJqZWN0In0.NRLcK6fYr3IdNfmncJePMWLQ34M4n14EgqSYrQIjL9w"
 ```
 
 ### Verifying and decoding a token
@@ -284,7 +251,27 @@ encoded_token.payload # => { 'exp'=>1234, 'jti'=>'1234", 'sub'=>'my-subject' }
 encoded_token.header # {'kid'=>'hmac', 'alg'=>'HS256'}
 ```
 
-#### Keyfinders
+A JWK can be used to sign and verify the token if it's possible to derive the signing algorithm from the key.
+
+```ruby
+jwk_json = '{
+ "kty": "oct",
+ "k": "c2VjcmV0",
+ "alg": "HS256",
+ "kid": "hmac"
+}'
+
+jwk = JWT::JWK.import(JSON.parse(jwk_json))
+
+token = JWT::Token.new(payload: payload, header: header)
+
+token.sign!(key: jwk)
+
+encoded_token = JWT::EncodedToken.new(token.jwt)
+encoded_token.verify!(signature: { key: jwk})
+```
+
+#### Using a keyfinder
 
 A keyfinder can be used to verify a signature. A keyfinder is an object responding to the `#call` method. The method expects to receive one argument, which is the token to be verified.
 
@@ -677,13 +664,14 @@ algorithms = jwks.map { |key| key[:alg] }.compact.uniq
 JWT.decode(token, nil, true, algorithms: algorithms, jwks: jwks)
 ```
 
-The `jwks` option can also be given as a lambda that evaluates every time a kid is resolved.
+The `jwks` option can also be given as a lambda that evaluates every time a key identifier is resolved.
 This can be used to implement caching of remotely fetched JWK Sets.
 
-If the requested `kid` is not found from the given set the loader will be called a second time with the `kid_not_found` option set to `true`.
+Key identifiers can be specified using `kid`, `x5t` header parameters.
+If the requested identifier is not found from the given set the loader will be called a second time with the `kid_not_found` option set to `true`.
 The application can choose to implement some kind of JWK cache invalidation or other mechanism to handle such cases.
 
-Tokens without a specified `kid` are rejected by default.
+Tokens without a specified key identifier (`kid` or `x5t`) are rejected by default.
 This behaviour may be overwritten by setting the `allow_nil_kid` option for `decode` to `true`.
 
 ```ruby

data/lib/jwt/decode.rb

@@ -65,7 +65,14 @@ module JWT
 
     def set_key
       @key = find_key(&@keyfinder) if @keyfinder
-      @key = ::JWT::JWK::KeyFinder.new(jwks: @options[:jwks], allow_nil_kid: @options[:allow_nil_kid]).key_for(token.header['kid']) if @options[:jwks]
+      if @options[:jwks]
+        @key = ::JWT::JWK::KeyFinder.new(
+          jwks: @options[:jwks],
+          allow_nil_kid: @options[:allow_nil_kid],
+          key_fields: @options[:key_fields]
+        ).call(token)
+      end
+
       return unless (x5c_options = @options[:x5c])
 
       @key = X5cKeyFinder.new(x5c_options[:root_certificates], x5c_options[:crls]).from(token.header['x5c'])

data/lib/jwt/encoded_token.rb

@@ -28,6 +28,10 @@ module JWT
       end
     end
 
+    DEFAULT_CLAIMS = [:exp].freeze
+
+    private_constant(:DEFAULT_CLAIMS)
+
     # Returns the original token provided to the class.
     # @return [String] The JWT token.
     attr_reader :jwt
@@ -41,6 +45,8 @@ module JWT
 
       @jwt = jwt
       @signature_verified = false
+      @claims_verified    = false
+
       @encoded_header, @encoded_payload, @encoded_signature = jwt.split('.')
     end
 
@@ -68,12 +74,13 @@ module JWT
     # @return [String] the encoded header.
     attr_reader :encoded_header
 
-    # Returns the payload of the JWT token. Access requires the signature to have been verified.
+    # Returns the payload of the JWT token. Access requires the signature and claims to have been verified.
     #
     # @return [Hash] the payload.
     # @raise [JWT::DecodeError] if the signature has not been verified.
     def payload
       raise JWT::DecodeError, 'Verify the token signature before accessing the payload' unless @signature_verified
+      raise JWT::DecodeError, 'Verify the token claims before accessing the payload' unless @claims_verified
 
       decoded_payload
     end
@@ -106,12 +113,23 @@ module JWT
     # @param claims [Array<Symbol>, Hash] the claims to verify (see {#verify_claims!}).
     # @return [nil]
     # @raise [JWT::DecodeError] if the signature or claim verification fails.
-    def verify!(signature:, claims: [:exp])
+    def verify!(signature:, claims: nil)
       verify_signature!(**signature)
       claims.is_a?(Array) ? verify_claims!(*claims) : verify_claims!(claims)
       nil
     end
 
+    # Verifies the token signature and claims.
+    # By default it verifies the 'exp' claim.
+
+    # @param signature [Hash] the parameters for signature verification (see {#verify_signature!}).
+    # @param claims [Array<Symbol>, Hash] the claims to verify (see {#verify_claims!}).
+    # @return [Boolean] true if the signature and claims are valid, false otherwise.
+    def valid?(signature:, claims: nil)
+      valid_signature?(**signature) &&
+        (claims.is_a?(Array) ? valid_claims?(*claims) : valid_claims?(claims))
+    end
+
     # Verifies the signature of the JWT token.
     #
     # @param algorithm [String, Array<String>, Object, Array<Object>] the algorithm(s) to use for verification.
@@ -120,12 +138,8 @@ module JWT
     # @return [nil]
     # @raise [JWT::VerificationError] if the signature verification fails.
     # @raise [ArgumentError] if neither key nor key_finder is provided, or if both are provided.
-    def verify_signature!(algorithm:, key: nil, key_finder: nil)
-      raise ArgumentError, 'Provide either key or key_finder, not both or neither' if key.nil? == key_finder.nil?
-
-      key ||= key_finder.call(self)
-
-      return if valid_signature?(algorithm: algorithm, key: key)
+    def verify_signature!(algorithm: nil, key: nil, key_finder: nil)
+      return if valid_signature?(algorithm: algorithm, key: key, key_finder: key_finder)
 
       raise JWT::VerificationError, 'Signature verification failed'
     end
@@ -133,43 +147,59 @@ module JWT
     # Checks if the signature of the JWT token is valid.
     #
     # @param algorithm [String, Array<String>, Object, Array<Object>] the algorithm(s) to use for verification.
-    # @param key [String, Array<String>] the key(s) to use for verification.
+    # @param key [String, Array<String>, JWT::JWK::KeyBase, Array<JWT::JWK::KeyBase>] the key(s) to use for verification.
+    # @param key_finder [#call] an object responding to `call` to find the key for verification.
     # @return [Boolean] true if the signature is valid, false otherwise.
-    def valid_signature?(algorithm:, key:)
-      valid = Array(JWA.resolve_and_sort(algorithms: algorithm, preferred_algorithm: header['alg'])).any? do |algo|
-        Array(key).any? do |one_key|
-          algo.verify(data: signing_input, signature: signature, verification_key: one_key)
-        end
-      end
+    def valid_signature?(algorithm: nil, key: nil, key_finder: nil)
+      raise ArgumentError, 'Provide either key or key_finder, not both or neither' if key.nil? == key_finder.nil?
+
+      keys      = Array(key || key_finder.call(self))
+      verifiers = JWA.create_verifiers(algorithms: algorithm, keys: keys, preferred_algorithm: header['alg'])
 
+      raise JWT::VerificationError, 'No algorithm provided' if verifiers.empty?
+
+      valid = verifiers.any? do |jwa|
+        jwa.verify(data: signing_input, signature: signature)
+      end
       valid.tap { |verified| @signature_verified = verified }
     end
 
     # Verifies the claims of the token.
-    # @param options [Array<Symbol>, Hash] the claims to verify.
+    # @param options [Array<Symbol>, Hash] the claims to verify. By default, it checks the 'exp' claim.
     # @raise [JWT::DecodeError] if the claims are invalid.
     def verify_claims!(*options)
-      Claims::Verifier.verify!(ClaimsContext.new(self), *options)
+      Claims::Verifier.verify!(ClaimsContext.new(self), *claims_options(options)).tap do
+        @claims_verified = true
+      end
+    rescue StandardError
+      @claims_verified = false
+      raise
     end
 
     # Returns the errors of the claims of the token.
-    # @param options [Array<Symbol>, Hash] the claims to verify.
+    # @param options [Array<Symbol>, Hash] the claims to verify. By default, it checks the 'exp' claim.
     # @return [Array<Symbol>] the errors of the claims.
     def claim_errors(*options)
-      Claims::Verifier.errors(ClaimsContext.new(self), *options)
+      Claims::Verifier.errors(ClaimsContext.new(self), *claims_options(options))
     end
 
     # Returns whether the claims of the token are valid.
-    # @param options [Array<Symbol>, Hash] the claims to verify.
+    # @param options [Array<Symbol>, Hash] the claims to verify. By default, it checks the 'exp' claim.
     # @return [Boolean] whether the claims are valid.
     def valid_claims?(*options)
-      claim_errors(*options).empty?
+      claim_errors(*claims_options(options)).empty?.tap { |verified| @claims_verified = verified }
     end
 
     alias to_s jwt
 
     private
 
+    def claims_options(options)
+      return DEFAULT_CLAIMS if options.first.nil?
+
+      options
+    end
+
     def decode_payload
       raise JWT::DecodeError, 'Encoded payload is empty' if encoded_payload == ''
 

data/lib/jwt/jwa/ecdsa.rb

@@ -12,14 +12,22 @@ module JWT
       end
 
       def sign(data:, signing_key:)
+        raise_sign_error!("The given key is a #{signing_key.class}. It has to be an OpenSSL::PKey::EC instance") unless signing_key.is_a?(::OpenSSL::PKey::EC)
+        raise_sign_error!('The given key is not a private key') unless signing_key.private?
+
         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:)
+        verification_key = self.class.create_public_key_from_point(verification_key) if verification_key.is_a?(::OpenSSL::PKey::EC::Point)
+
+        raise_verify_error!("The given key is a #{verification_key.class}. It has to be an OpenSSL::PKey::EC instance") unless verification_key.is_a?(::OpenSSL::PKey::EC)
+
         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
@@ -56,12 +64,29 @@ module JWT
         register_algorithm(new(v[:algorithm], v[:digest]))
       end
 
+      # @api private
       def self.curve_by_name(name)
         NAMED_CURVES.fetch(name) do
           raise UnsupportedEcdsaCurve, "The ECDSA curve '#{name}' is not supported"
         end
       end
 
+      if ::JWT.openssl_3?
+        def self.create_public_key_from_point(point)
+          sequence = OpenSSL::ASN1::Sequence([
+                                               OpenSSL::ASN1::Sequence([OpenSSL::ASN1::ObjectId('id-ecPublicKey'), OpenSSL::ASN1::ObjectId(point.group.curve_name)]),
+                                               OpenSSL::ASN1::BitString(point.to_octet_string(:uncompressed))
+                                             ])
+          OpenSSL::PKey::EC.new(sequence.to_der)
+        end
+      else
+        def self.create_public_key_from_point(point)
+          OpenSSL::PKey::EC.new(point.group.curve_name).tap do |key|
+            key.public_key = point
+          end
+        end
+      end
+
       private
 
       attr_reader :digest

data/lib/jwt/jwa.rb

@@ -13,11 +13,43 @@ require_relative 'jwa/unsupported'
 module JWT
   # The JWA module contains all supported algorithms.
   module JWA
+    # @api private
+    class VerifierContext
+      def initialize(jwa:, keys:)
+        @jwa = jwa
+        @keys = Array(keys)
+      end
+
+      def verify(*args, **kwargs)
+        @keys.any? do |key|
+          @jwa.verify(*args, **kwargs, verification_key: key)
+        end
+      end
+    end
+
+    # @api private
+    class SignerContext
+      def initialize(jwa:, key:)
+        @jwa = jwa
+        @key = key
+      end
+
+      def sign(*args, **kwargs)
+        @jwa.sign(*args, **kwargs, signing_key: @key)
+      end
+
+      def jwa_header
+        @jwa.header
+      end
+    end
+
     class << self
       # @api private
       def resolve(algorithm)
         return find(algorithm) if algorithm.is_a?(String) || algorithm.is_a?(Symbol)
 
+        raise ArgumentError, 'Algorithm must be provided' if algorithm.nil?
+
         raise ArgumentError, 'Custom algorithms are required to include JWT::JWA::SigningAlgorithm' unless algorithm.is_a?(SigningAlgorithm)
 
         algorithm
@@ -25,8 +57,25 @@ module JWT
 
       # @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
+        Array(algorithms).map { |alg| JWA.resolve(alg) }
+                         .partition { |alg| alg.valid_alg?(preferred_algorithm) }
+                         .flatten
+      end
+
+      # @api private
+      def create_signer(algorithm:, key:)
+        return key if key.is_a?(JWK::KeyBase)
+
+        SignerContext.new(jwa: resolve(algorithm), key: key)
+      end
+
+      # @api private
+      def create_verifiers(algorithms:, keys:, preferred_algorithm:)
+        jwks, other_keys = keys.partition { |key| key.is_a?(JWK::KeyBase) }
+
+        jwks + resolve_and_sort(algorithms: algorithms,
+                                preferred_algorithm: preferred_algorithm)
+               .map { |jwa| VerifierContext.new(jwa: jwa, keys: other_keys) }
       end
     end
   end

data/lib/jwt/jwk/ec.rb

@@ -73,6 +73,13 @@ module JWT
 
       private
 
+      def jwa
+        return super if self[:alg]
+
+        curve_name = self.class.to_openssl_curve(self[:crv])
+        JWA.resolve(JWA::Ecdsa.curve_by_name(curve_name)[:algorithm])
+      end
+
       def ec_key
         @ec_key ||= create_ec_key(self[:crv], self[:x], self[:y], self[:d])
       end
@@ -136,67 +143,54 @@ module JWT
         }.compact
       end
 
-      if ::JWT.openssl_3?
-        def create_ec_key(jwk_crv, jwk_x, jwk_y, jwk_d) # rubocop:disable Metrics/MethodLength
-          curve = EC.to_openssl_curve(jwk_crv)
-          x_octets = decode_octets(jwk_x)
-          y_octets = decode_octets(jwk_y)
-
-          point = OpenSSL::PKey::EC::Point.new(
-            OpenSSL::PKey::EC::Group.new(curve),
-            OpenSSL::BN.new([0x04, x_octets, y_octets].pack('Ca*a*'), 2)
-          )
-
-          sequence = if jwk_d
-                       # https://datatracker.ietf.org/doc/html/rfc5915.html
-                       # ECPrivateKey ::= SEQUENCE {
-                       #   version        INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),
-                       #   privateKey     OCTET STRING,
-                       #   parameters [0] ECParameters {{ NamedCurve }} OPTIONAL,
-                       #   publicKey  [1] BIT STRING OPTIONAL
-                       # }
-
-                       OpenSSL::ASN1::Sequence([
-                                                 OpenSSL::ASN1::Integer(1),
-                                                 OpenSSL::ASN1::OctetString(OpenSSL::BN.new(decode_octets(jwk_d), 2).to_s(2)),
-                                                 OpenSSL::ASN1::ObjectId(curve, 0, :EXPLICIT),
-                                                 OpenSSL::ASN1::BitString(point.to_octet_string(:uncompressed), 1, :EXPLICIT)
-                                               ])
-                     else
-                       OpenSSL::ASN1::Sequence([
-                                                 OpenSSL::ASN1::Sequence([OpenSSL::ASN1::ObjectId('id-ecPublicKey'), OpenSSL::ASN1::ObjectId(curve)]),
-                                                 OpenSSL::ASN1::BitString(point.to_octet_string(:uncompressed))
-                                               ])
-                     end
+      def create_point(jwk_crv, jwk_x, jwk_y)
+        curve = EC.to_openssl_curve(jwk_crv)
+        x_octets = decode_octets(jwk_x)
+        y_octets = decode_octets(jwk_y)
+
+        # The details of the `Point` instantiation are covered in:
+        # - https://docs.ruby-lang.org/en/2.4.0/OpenSSL/PKey/EC.html
+        # - https://www.openssl.org/docs/manmaster/man3/EC_POINT_new.html
+        # - https://tools.ietf.org/html/rfc5480#section-2.2
+        # - https://www.secg.org/SEC1-Ver-1.0.pdf
+        # Section 2.3.3 of the last of these references specifies that the
+        # encoding of an uncompressed point consists of the byte `0x04` followed
+        # by the x value then the y value.
+        OpenSSL::PKey::EC::Point.new(
+          OpenSSL::PKey::EC::Group.new(curve),
+          OpenSSL::BN.new([0x04, x_octets, y_octets].pack('Ca*a*'), 2)
+        )
+      end
 
+      if ::JWT.openssl_3?
+        def create_ec_key(jwk_crv, jwk_x, jwk_y, jwk_d)
+          point = create_point(jwk_crv, jwk_x, jwk_y)
+
+          return ::JWT::JWA::Ecdsa.create_public_key_from_point(point) unless jwk_d
+
+          # https://datatracker.ietf.org/doc/html/rfc5915.html
+          # ECPrivateKey ::= SEQUENCE {
+          #   version        INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),
+          #   privateKey     OCTET STRING,
+          #   parameters [0] ECParameters {{ NamedCurve }} OPTIONAL,
+          #   publicKey  [1] BIT STRING OPTIONAL
+          # }
+
+          sequence = OpenSSL::ASN1::Sequence([
+                                               OpenSSL::ASN1::Integer(1),
+                                               OpenSSL::ASN1::OctetString(OpenSSL::BN.new(decode_octets(jwk_d), 2).to_s(2)),
+                                               OpenSSL::ASN1::ObjectId(point.group.curve_name, 0, :EXPLICIT),
+                                               OpenSSL::ASN1::BitString(point.to_octet_string(:uncompressed), 1, :EXPLICIT)
+                                             ])
           OpenSSL::PKey::EC.new(sequence.to_der)
         end
       else
         def create_ec_key(jwk_crv, jwk_x, jwk_y, jwk_d)
-          curve = EC.to_openssl_curve(jwk_crv)
-
-          x_octets = decode_octets(jwk_x)
-          y_octets = decode_octets(jwk_y)
-
-          key = OpenSSL::PKey::EC.new(curve)
-
-          # The details of the `Point` instantiation are covered in:
-          # - https://docs.ruby-lang.org/en/2.4.0/OpenSSL/PKey/EC.html
-          # - https://www.openssl.org/docs/manmaster/man3/EC_POINT_new.html
-          # - https://tools.ietf.org/html/rfc5480#section-2.2
-          # - https://www.secg.org/SEC1-Ver-1.0.pdf
-          # Section 2.3.3 of the last of these references specifies that the
-          # encoding of an uncompressed point consists of the byte `0x04` followed
-          # by the x value then the y value.
-          point = OpenSSL::PKey::EC::Point.new(
-            OpenSSL::PKey::EC::Group.new(curve),
-            OpenSSL::BN.new([0x04, x_octets, y_octets].pack('Ca*a*'), 2)
-          )
-
-          key.public_key = point
-          key.private_key = OpenSSL::BN.new(decode_octets(jwk_d), 2) if jwk_d
-
-          key
+          point = create_point(jwk_crv, jwk_x, jwk_y)
+
+          ::JWT::JWA::Ecdsa.create_public_key_from_point(point).tap do |key|
+            key.private_key = OpenSSL::BN.new(decode_octets(jwk_d), 2) if jwk_d
+          end
         end
       end
 
@@ -205,7 +199,7 @@ module JWT
         # Some base64 encoders on some platform omit a single 0-byte at
         # the start of either Y or X coordinate of the elliptic curve point.
         # This leads to an encoding error when data is passed to OpenSSL BN.
-        # It is know to have happend to exported JWKs on a Java application and
+        # It is know to have happened to exported JWKs on a Java application and
         # on a Flutter/Dart application (both iOS and Android). All that is
         # needed to fix the problem is adding a leading 0-byte. We know the
         # required byte is 0 because with any other byte the point is no longer

data/lib/jwt/jwk/key_base.rb

@@ -42,6 +42,19 @@ module JWT
         other.is_a?(::JWT::JWK::KeyBase) && self[:kid] == other[:kid]
       end
 
+      def verify(**kwargs)
+        jwa.verify(**kwargs, verification_key: verify_key)
+      end
+
+      def sign(**kwargs)
+        jwa.sign(**kwargs, signing_key: signing_key)
+      end
+
+      # @api private
+      def jwa_header
+        jwa.header
+      end
+
       alias eql? ==
 
       def <=>(other)
@@ -52,6 +65,12 @@ module JWT
 
       private
 
+      def jwa
+        raise JWT::JWKError, 'Could not resolve the JWA, the "alg" parameter is missing' unless self[:alg]
+
+        JWA.resolve(self[:alg])
+      end
+
       attr_reader :parameters
     end
   end

data/lib/jwt/jwk/key_finder.rb

@@ -9,6 +9,9 @@ module JWT
       # @param [Hash] options the options to create a KeyFinder with
       # @option options [Proc, JWT::JWK::Set] :jwks the jwks or a loader proc
       # @option options [Boolean] :allow_nil_kid whether to allow nil kid
+      # @option options [Array] :key_fields the fields to use for key matching,
+      #                         the order of the fields are used to determine
+      #                         the priority of the keys.
       def initialize(options)
         @allow_nil_kid = options[:allow_nil_kid]
         jwks_or_loader = options[:jwks]
@@ -18,15 +21,16 @@ module JWT
                        else
                          ->(_options) { jwks_or_loader }
                        end
+
+        @key_fields = options[:key_fields] || %i[kid]
       end
 
       # Returns the verification key for the given kid
       # @param [String] kid the key id
-      def key_for(kid)
-        raise ::JWT::DecodeError, 'No key id (kid) found from token headers' unless kid || @allow_nil_kid
-        raise ::JWT::DecodeError, 'Invalid type for kid header parameter' unless kid.nil? || kid.is_a?(String)
+      def key_for(kid, key_field = :kid)
+        raise ::JWT::DecodeError, "Invalid type for #{key_field} header parameter" unless kid.nil? || kid.is_a?(String)
 
-        jwk = resolve_key(kid)
+        jwk = resolve_key(kid, key_field)
 
         raise ::JWT::DecodeError, 'No keys found in jwks' unless @jwks.any?
         raise ::JWT::DecodeError, "Could not find public key for kid #{kid}" unless jwk
@@ -37,22 +41,31 @@ module JWT
       # Returns the key for the given token
       # @param [JWT::EncodedToken] token the token
       def call(token)
-        key_for(token.header['kid'])
+        @key_fields.each do |key_field|
+          field_value = token.header[key_field.to_s]
+
+          return key_for(field_value, key_field) if field_value
+        end
+
+        raise ::JWT::DecodeError, 'No key id (kid) or x5t found from token headers' unless @allow_nil_kid
+
+        kid = token.header['kid']
+        key_for(kid)
       end
 
       private
 
-      def resolve_key(kid)
-        key_matcher = ->(key) { (kid.nil? && @allow_nil_kid) || key[:kid] == kid }
+      def resolve_key(kid, key_field)
+        key_matcher = ->(key) { (kid.nil? && @allow_nil_kid) || key[key_field] == kid }
 
         # First try without invalidation to facilitate application caching
-        @jwks ||= JWT::JWK::Set.new(@jwks_loader.call(kid: kid))
+        @jwks ||= JWT::JWK::Set.new(@jwks_loader.call(key_field => kid))
         jwk = @jwks.find { |key| key_matcher.call(key) }
 
         return jwk if jwk
 
         # Second try, invalidate for backwards compatibility
-        @jwks = JWT::JWK::Set.new(@jwks_loader.call(invalidate: true, kid_not_found: true, kid: kid))
+        @jwks = JWT::JWK::Set.new(@jwks_loader.call(invalidate: true, kid_not_found: true, key_field => kid))
         @jwks.find { |key| key_matcher.call(key) }
       end
     end

data/lib/jwt/jwk/rsa.rb

@@ -51,6 +51,7 @@ module JWT
       def export(options = {})
         exported = parameters.clone
         exported.reject! { |k, _| RSA_PRIVATE_KEY_ELEMENTS.include? k } unless private? && options[:include_private] == true
+
         exported
       end
 

data/lib/jwt/token.rb

@@ -87,16 +87,16 @@ module JWT
 
     # Signs the JWT token.
     #
+    # @param key [String, JWT::JWK::KeyBase] the key to use for signing.
     # @param algorithm [String, Object] the algorithm to use for signing.
-    # @param key [String] the key to use for signing.
     # @return [void]
     # @raise [JWT::EncodeError] if the token is already signed or other problems when signing
-    def sign!(algorithm:, key:)
+    def sign!(key:, algorithm: nil)
       raise ::JWT::EncodeError, 'Token already signed' if @signature
 
-      JWA.resolve(algorithm).tap do |algo|
-        header.merge!(algo.header) { |_key, old, _new| old }
-        @signature = algo.sign(data: signing_input, signing_key: key)
+      JWA.create_signer(algorithm: algorithm, key: key).tap do |signer|
+        header.merge!(signer.jwa_header) { |_key, old, _new| old }
+        @signature = signer.sign(data: signing_input)
       end
 
       nil

data/lib/jwt/version.rb

@@ -15,7 +15,7 @@ module JWT
   # Version constants
   module VERSION
     MAJOR = 3
-    MINOR = 0
+    MINOR = 1
     TINY  = 0
     PRE   = nil
 

data/ruby-jwt.gemspec

@@ -35,6 +35,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'appraisal'
   spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'irb'
   spec.add_development_dependency 'logger'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jwt
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Tim Rudat
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
@@ -185,7 +199,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/jwt/ruby-jwt/issues
-  changelog_uri: https://github.com/jwt/ruby-jwt/blob/v3.0.0/CHANGELOG.md
+  changelog_uri: https://github.com/jwt/ruby-jwt/blob/v3.1.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: