jwt 2.5.0 → 2.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3098671a837e7b291103cde1921277c61ecaa0f0797b955e6adc65328498f0d
-  data.tar.gz: 3253833ac6d7743e40a5d5157b161cd0daecc9b77f61dfa7687d6b3da1be56ca
+  metadata.gz: af3792b982f014801d3ff7ae3410be6bd1e0b27f199c500942eb86267bb2b764
+  data.tar.gz: c37fc4b72cf3819210b15164548eff44579de1e8f8c48d9ce35864a84f007d9a
 SHA512:
-  metadata.gz: 306c946b1199301a3f1000c8ffba4a77d07fd05dd83f769da86fd29f254827b5af8488a4b6a54b11f1f7f3a028cb88caafb7ed67528e7004c0337f6506e595ea
-  data.tar.gz: 57d1eba7a06bc9d9f9fcb76b42aa3808415af5020c53969b4cada890b1646e7d348a96ce18010ab0a978e42825febbeb7b3f205b72e8ce60ef90132cf5887599
+  metadata.gz: 3f61fd13a1d56c657691abb4bfde3671a7d93b5c853785b804c0d119d27f4641685828eb9c65a8e4856487782530e791ecbce5f1a5f1cb61c883daff97a44367
+  data.tar.gz: ef36aa81991e28cb9d3df65f1ebbeb6599eb99dee8e1953aff1a6231e91c6a3f9633e3afd22fbbc6c09f6318c4e516ee7a908428eee303f3952fed890395b267

data/CHANGELOG.md

@@ -1,29 +1,98 @@
 # Changelog
 
+## [v2.8.1](https://github.com/jwt/ruby-jwt/tree/v2.8.1) (2024-02-29)
 
-## [v2.5.0](https://github.com/jwt/ruby-jwt/tree/v2.5.0) (NEXT)
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.8.0...v2.8.1)
 
-[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.4.1...master)
+**Features:**
+
+- Configurable base64 decode behaviour [#589](https://github.com/jwt/ruby-jwt/pull/589) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Output deprecation warnings once [#589](https://github.com/jwt/ruby-jwt/pull/589) ([@anakinj](https://github.com/anakinj))
+
+## [v2.8.0](https://github.com/jwt/ruby-jwt/tree/v2.8.0) (2024-02-17)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.7.1...v2.8.0)
+
+**Features:**
+
+- Updated rubocop to 1.56 [#573](https://github.com/jwt/ruby-jwt/pull/573) ([@anakinj](https://github.com/anakinj))
+- Run CI on Ruby 3.3 [#577](https://github.com/jwt/ruby-jwt/pull/577) ([@anakinj](https://github.com/anakinj))
+- Deprecation warning added for the HMAC algorithm HS512256 (HMAC-SHA-512 truncated to 256-bits) [#575](https://github.com/jwt/ruby-jwt/pull/575) ([@anakinj](https://github.com/anakinj))
+- Stop using RbNaCl for standard HMAC algorithms [#575](https://github.com/jwt/ruby-jwt/pull/575) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Fix signature has expired error if payload is a string [#555](https://github.com/jwt/ruby-jwt/pull/555) ([@GobinathAL](https://github.com/GobinathAL))
+- Fix key base equality and spaceship operators [#569](https://github.com/jwt/ruby-jwt/pull/569) ([@magneland](https://github.com/magneland))
+- Remove explicit base64 require from x5c_key_finder [#580](https://github.com/jwt/ruby-jwt/pull/580) ([@anakinj](https://github.com/anakinj))
+- Performance improvements and cleanup of tests [#581](https://github.com/jwt/ruby-jwt/pull/581) ([@anakinj](https://github.com/anakinj))
+- Repair EC x/y coordinates when importing JWK [#585](https://github.com/jwt/ruby-jwt/pull/585) ([@julik](https://github.com/julik))
+- Explicit dependency to the base64 gem [#582](https://github.com/jwt/ruby-jwt/pull/582) ([@anakinj](https://github.com/anakinj))
+- Deprecation warning for decoding content not compliant with RFC 4648 [#582](https://github.com/jwt/ruby-jwt/pull/582) ([@anakinj](https://github.com/anakinj))
+- Algorithms moved under the `::JWT::JWA` module ([@anakinj](https://github.com/anakinj))
+
+## [v2.7.1](https://github.com/jwt/ruby-jwt/tree/v2.8.0) (2023-06-09)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.7.0...v2.7.1)
+
+**Fixes and enhancements:**
+
+- Handle invalid algorithm when decoding JWT [#559](https://github.com/jwt/ruby-jwt/pull/559) ([@nataliastanko](https://github.com/nataliastanko))
+- Do not raise error when verifying bad HMAC signature [#563](https://github.com/jwt/ruby-jwt/pull/563) ([@hieuk09](https://github.com/hieuk09))
+
+## [v2.7.0](https://github.com/jwt/ruby-jwt/tree/v2.7.0) (2023-02-01)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.6.0...v2.7.0)
+
+**Features:**
+
+- Support OKP (Ed25519) keys for JWKs [#540](https://github.com/jwt/ruby-jwt/pull/540) ([@anakinj](https://github.com/anakinj))
+- JWK Sets can now be used for tokens with nil kid [#543](https://github.com/jwt/ruby-jwt/pull/543) ([@bellebaum](https://github.com/bellebaum))
+
+**Fixes and enhancements:**
+
+- Fix issue with multiple keys returned by keyfinder and multiple allowed algorithms [#545](https://github.com/jwt/ruby-jwt/pull/545) ([@mpospelov](https://github.com/mpospelov))
+- Non-string `kid` header values are now rejected [#543](https://github.com/jwt/ruby-jwt/pull/543) ([@bellebaum](https://github.com/bellebaum))
+
+## [v2.6.0](https://github.com/jwt/ruby-jwt/tree/v2.6.0) (2022-12-22)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.5.0...v2.6.0)
+
+**Features:**
+
+- Support custom algorithms by passing algorithm objects [#512](https://github.com/jwt/ruby-jwt/pull/512) ([@anakinj](https://github.com/anakinj))
+- Support descriptive (not key related) JWK parameters [#520](https://github.com/jwt/ruby-jwt/pull/520) ([@bellebaum](https://github.com/bellebaum))
+- Support for JSON Web Key Sets [#525](https://github.com/jwt/ruby-jwt/pull/525) ([@bellebaum](https://github.com/bellebaum))
+- Support HMAC keys over 32 chars when using RbNaCl [#521](https://github.com/jwt/ruby-jwt/pull/521) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Raise descriptive error on empty hmac_secret and OpenSSL 3.0/openssl gem <3.0.1 [#530](https://github.com/jwt/ruby-jwt/pull/530) ([@jonmchan](https://github.com/jonmchan))
+
+## [v2.5.0](https://github.com/jwt/ruby-jwt/tree/v2.5.0) (2022-08-25)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.4.1...v2.5.0)
 
 **Features:**
 
-- Support JWK thumbprints as key ids [#481](https://github.com/jwt/ruby-jwt/pull/481) ([@anakinj](https://github.com/anakinj)).
-- Your contribution here
+- Support JWK thumbprints as key ids [#481](https://github.com/jwt/ruby-jwt/pull/481) ([@anakinj](https://github.com/anakinj))
+- Support OpenSSL >= 3.0 [#496](https://github.com/jwt/ruby-jwt/pull/496) ([@anakinj](https://github.com/anakinj))
 
 **Fixes and enhancements:**
-- Bring back the old Base64 (RFC2045) deocode mechanisms [#488](https://github.com/jwt/ruby-jwt/pull/488) ([@anakinj](https://github.com/anakinj)).
-- Rescue RbNaCl exception for EdDSA wrong key [#491](https://github.com/jwt/ruby-jwt/pull/491) ([@n-studio](https://github.com/n-studio)).
-- New parameter name for cases when kid is not found using JWK key loader proc [#501](https://github.com/jwt/ruby-jwt/pull/501) ([@anakinj](https://github.com/anakinj)).
-- Fix NoMethodError when a 2 segment token is missing 'alg' header [#502](https://github.com/jwt/ruby-jwt/pull/502) ([@cmrd-senya](https://github.com/cmrd-senya)).
-- Support OpenSSL >= 3.0 [#496](https://github.com/jwt/ruby-jwt/pull/496) ([@anakinj](https://github.com/anakinj)).
-- Your contribution here
+- Bring back the old Base64 (RFC2045) deocode mechanisms [#488](https://github.com/jwt/ruby-jwt/pull/488) ([@anakinj](https://github.com/anakinj))
+- Rescue RbNaCl exception for EdDSA wrong key [#491](https://github.com/jwt/ruby-jwt/pull/491) ([@n-studio](https://github.com/n-studio))
+- New parameter name for cases when kid is not found using JWK key loader proc [#501](https://github.com/jwt/ruby-jwt/pull/501) ([@anakinj](https://github.com/anakinj))
+- Fix NoMethodError when a 2 segment token is missing 'alg' header [#502](https://github.com/jwt/ruby-jwt/pull/502) ([@cmrd-senya](https://github.com/cmrd-senya))
 
 ## [v2.4.1](https://github.com/jwt/ruby-jwt/tree/v2.4.1) (2022-06-07)
 
 [Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.4.0...v2.4.1)
 
 **Fixes and enhancements:**
-- Raise JWT::DecodeError on invalid signature [\#484](https://github.com/jwt/ruby-jwt/pull/484) ([@freakyfelt!](https://github.com/freakyfelt!)).
+- Raise JWT::DecodeError on invalid signature [\#484](https://github.com/jwt/ruby-jwt/pull/484) ([@freakyfelt!](https://github.com/freakyfelt!))
 
 ## [v2.4.0](https://github.com/jwt/ruby-jwt/tree/v2.4.0) (2022-06-06)
 
@@ -31,20 +100,20 @@
 
 **Features:**
 
-- Dropped support for Ruby 2.5 and older [#453](https://github.com/jwt/ruby-jwt/pull/453) - [@anakinj](https://github.com/anakinj).
-- Use Ruby built-in url-safe base64 methods [#454](https://github.com/jwt/ruby-jwt/pull/454) - [@bdewater](https://github.com/bdewater).
-- Updated rubocop to 1.23.0 [#457](https://github.com/jwt/ruby-jwt/pull/457) - [@anakinj](https://github.com/anakinj).
-- Add x5c header key finder [#338](https://github.com/jwt/ruby-jwt/pull/338) - [@bdewater](https://github.com/bdewater).
-- Author driven changelog process [#463](https://github.com/jwt/ruby-jwt/pull/463) - [@anakinj](https://github.com/anakinj).
-- Allow regular expressions and procs to verify issuer [\#437](https://github.com/jwt/ruby-jwt/pull/437) ([rewritten](https://github.com/rewritten)).
-- Add Support to be able to verify from multiple keys [\#425](https://github.com/jwt/ruby-jwt/pull/425) ([ritikesh](https://github.com/ritikesh)).
+- Dropped support for Ruby 2.5 and older [#453](https://github.com/jwt/ruby-jwt/pull/453) - ([@anakinj](https://github.com/anakinj))
+- Use Ruby built-in url-safe base64 methods [#454](https://github.com/jwt/ruby-jwt/pull/454) - ([@bdewater](https://github.com/bdewater))
+- Updated rubocop to 1.23.0 [#457](https://github.com/jwt/ruby-jwt/pull/457) - ([@anakinj](https://github.com/anakinj))
+- Add x5c header key finder [#338](https://github.com/jwt/ruby-jwt/pull/338) - ([@bdewater](https://github.com/bdewater))
+- Author driven changelog process [#463](https://github.com/jwt/ruby-jwt/pull/463) - ([@anakinj](https://github.com/anakinj))
+- Allow regular expressions and procs to verify issuer [\#437](https://github.com/jwt/ruby-jwt/pull/437) ([rewritten](https://github.com/rewritten))
+- Add Support to be able to verify from multiple keys [\#425](https://github.com/jwt/ruby-jwt/pull/425) ([ritikesh](https://github.com/ritikesh))
 
 **Fixes and enhancements:**
-- Readme: Typo fix re MissingRequiredClaim [\#451](https://github.com/jwt/ruby-jwt/pull/451) ([antonmorant](https://github.com/antonmorant)).
-- Fix RuboCop TODOs [\#476](https://github.com/jwt/ruby-jwt/pull/476) ([typhoon2099](https://github.com/typhoon2099)).
-- Make specific algorithms in README linkable [\#472](https://github.com/jwt/ruby-jwt/pull/472) ([milieu](https://github.com/milieu)).
-- Update note about supported JWK types [\#475](https://github.com/jwt/ruby-jwt/pull/475) ([dpashkevich](https://github.com/dpashkevich)).
-- Create CODE\_OF\_CONDUCT.md [\#449](https://github.com/jwt/ruby-jwt/pull/449) ([loic5](https://github.com/loic5)).
+- Readme: Typo fix re MissingRequiredClaim [\#451](https://github.com/jwt/ruby-jwt/pull/451) ([antonmorant](https://github.com/antonmorant))
+- Fix RuboCop TODOs [\#476](https://github.com/jwt/ruby-jwt/pull/476) ([typhoon2099](https://github.com/typhoon2099))
+- Make specific algorithms in README linkable [\#472](https://github.com/jwt/ruby-jwt/pull/472) ([milieu](https://github.com/milieu))
+- Update note about supported JWK types [\#475](https://github.com/jwt/ruby-jwt/pull/475) ([dpashkevich](https://github.com/dpashkevich))
+- Create CODE\_OF\_CONDUCT.md [\#449](https://github.com/jwt/ruby-jwt/pull/449) ([loic5](https://github.com/loic5))
 
 ## [v2.3.0](https://github.com/jwt/ruby-jwt/tree/v2.3.0) (2021-10-03)
 

data/CONTRIBUTING.md

@@ -12,19 +12,19 @@ git remote add upstream https://github.com/jwt/ruby-jwt
 
 ## Create a branch for your implementation
 
-Make sure you have the latest upstream master branch of the project.
+Make sure you have the latest upstream main branch of the project.
 
 ```
 git fetch --all
-git checkout master
-git rebase upstream/master
-git push origin master
+git checkout main
+git rebase upstream/main
+git push origin main
 git checkout -b fix-a-little-problem
 ```
 
 ## Running the tests and linter
 
-Before you start with your implementation make sure you are able to get a succesful test run with the current revision.
+Before you start with your implementation make sure you are able to get a successful test run with the current revision.
 
 The tests are written with rspec and [Appraisal](https://github.com/thoughtbot/appraisal) is used to ensure compatibility with 3rd party dependencies providing cryptographic features.
 
@@ -78,12 +78,12 @@ A maintainer will review and probably merge you changes when time allows, be pat
 
 ## Keeping your branch up-to-date
 
-It's recommended that you keep your branch up-to-date by rebasing to the upstream master.
+It's recommended that you keep your branch up-to-date by rebasing to the upstream main.
 
 ```
 git fetch upstream
 git checkout fix-a-little-problem
-git rebase upstream/master
+git rebase upstream/main
 git push origin fix-a-little-problem -f
 ```
 

data/README.md

@@ -1,11 +1,10 @@
 # JWT
 
 [![Gem Version](https://badge.fury.io/rb/jwt.svg)](https://badge.fury.io/rb/jwt)
-[![Build Status](https://github.com/jwt/ruby-jwt/workflows/test/badge.svg?branch=master)](https://github.com/jwt/ruby-jwt/actions)
+[![Build Status](https://github.com/jwt/ruby-jwt/workflows/test/badge.svg?branch=main)](https://github.com/jwt/ruby-jwt/actions)
 [![Code Climate](https://codeclimate.com/github/jwt/ruby-jwt/badges/gpa.svg)](https://codeclimate.com/github/jwt/ruby-jwt)
 [![Test Coverage](https://codeclimate.com/github/jwt/ruby-jwt/badges/coverage.svg)](https://codeclimate.com/github/jwt/ruby-jwt/coverage)
 [![Issue Count](https://codeclimate.com/github/jwt/ruby-jwt/badges/issue_count.svg)](https://codeclimate.com/github/jwt/ruby-jwt)
-[![SourceLevel](https://app.sourcelevel.io/github/jwt/-/ruby-jwt.svg)](https://app.sourcelevel.io/github/jwt/-/ruby-jwt)
 
 A ruby implementation of the [RFC 7519 OAuth JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) standard.
 
@@ -44,6 +43,23 @@ The JWT spec supports NONE, HMAC, RSASSA, ECDSA and RSASSA-PSS algorithms for cr
 
 See: [ JSON Web Algorithms (JWA) 3.1. "alg" (Algorithm) Header Parameter Values for JWS](https://tools.ietf.org/html/rfc7518#section-3.1)
 
+### Deprecation warnings
+
+Deprecation warnings are logged once (`:once` option) by default to avoid spam in logs. Other options are `:silent` to completely silence warnings and `:warn` to log every time a deprecated path is executed.
+
+```ruby
+  JWT.configuration.deprecation_warnings = :warn # default is :once
+```
+
+### Base64 decoding
+
+In the past the gem has been supporting the Base64 decoding specified in [RFC2045](https://www.rfc-editor.org/rfc/rfc2045) allowing newlines and blanks in the base64 encoded payload. In future versions base64 decoding will be stricter and only comply to [RFC4648](https://www.rfc-editor.org/rfc/rfc4648).
+
+The stricter base64 decoding when processing tokens can be done via the `strict_base64_decoding` configuration accessor.
+```ruby
+  JWT.configuration.strict_base64_decoding = true # default is false
+```
+
 ### **NONE**
 
 * none - unsigned token
@@ -73,12 +89,11 @@ puts decoded_token
 ### **HMAC**
 
 * HS256 - HMAC using SHA-256 hash algorithm
-* HS512256 - HMAC using SHA-512-256 hash algorithm (only available with RbNaCl; see note below)
 * HS384 - HMAC using SHA-384 hash algorithm
 * HS512 - HMAC using SHA-512 hash algorithm
 
 ```ruby
-# The secret must be a string. A JWT::DecodeError will be raised if it isn't provided.
+# 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.
 hmac_secret = 'my$ecretK3y'
 
 token = JWT.encode payload, hmac_secret, 'HS256'
@@ -96,12 +111,6 @@ decoded_token = JWT.decode token, hmac_secret, true, { algorithm: 'HS256' }
 puts decoded_token
 ```
 
-Note: If [RbNaCl](https://github.com/cryptosphere/rbnacl) is loadable, ruby-jwt will use it for HMAC-SHA256, HMAC-SHA512-256, and HMAC-SHA512. RbNaCl enforces a maximum key size of 32 bytes for these algorithms.
-
-[RbNaCl](https://github.com/cryptosphere/rbnacl) requires
-[libsodium](https://github.com/jedisct1/libsodium), it can be installed
-on MacOS with `brew install libsodium`.
-
 ### **RSA**
 
 * RS256 - RSA using SHA-256 hash algorithm
@@ -160,7 +169,7 @@ In order to use this algorithm you need to add the `RbNaCl` gem to you `Gemfile`
 gem 'rbnacl'
 ```
 
-For more detailed installation instruction check the official [repository](https://github.com/cryptosphere/rbnacl) on GitHub.
+For more detailed installation instruction check the official [repository](https://github.com/RubyCrypto/rbnacl) on GitHub.
 
 * ED25519
 
@@ -212,6 +221,33 @@ decoded_token = JWT.decode token, rsa_public, true, { algorithm: 'PS256' }
 puts decoded_token
 ```
 
+### **Custom algorithms**
+
+An object implementing custom signing or verification behaviour can be passed in the `algorithm` option when encoding and decoding. The given object needs to implement the method `valid_alg?` and `verify` and/or `alg` and `sign`, depending if object is used for encoding or decoding.
+
+```ruby
+module CustomHS512Algorithm
+  def self.alg
+    'HS512'
+  end
+
+  def self.valid_alg?(alg_to_validate)
+    alg_to_validate == alg
+  end
+
+  def self.sign(data:, signing_key:)
+    OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha512'), data, signing_key)
+  end
+
+  def self.verify(data:, signature:, verification_key:)
+    ::OpenSSL.secure_compare(sign(data: data, signing_key: verification_key), signature)
+  end
+end
+
+token = ::JWT.encode({'pay' => 'load'}, 'secret', CustomHS512Algorithm)
+payload, header = ::JWT.decode(token, 'secret', true, algorithm: CustomHS512Algorithm)
+```
+
 ## Support for reserved claim names
 JSON Web Token defines some reserved claim names and defines how they should be
 used. JWT supports these reserved claim names:
@@ -535,7 +571,7 @@ crls = crl_uris.map do |uri|
 end
 
 begin
-  JWT.decode(token, nil, true, { x5c: { root_certificates: root_certificates, crls: crls })
+  JWT.decode(token, nil, true, { x5c: { root_certificates: root_certificates, crls: crls } })
 rescue JWT::DecodeError
   # Handle error, e.g. x5c header certificate revoked or expired
 end
@@ -543,73 +579,115 @@ end
 
 ### JSON Web Key (JWK)
 
-JWK is a JSON structure representing a cryptographic key. Currently only supports RSA, EC and HMAC keys. The `jwks` option can be given as a lambda that evaluates every time a kid is resolved.
+JWK is a JSON structure representing a cryptographic key. This gem currently supports RSA, EC, OKP and HMAC keys. OKP support requires [RbNaCl](https://github.com/RubyCrypto/rbnacl) and currently only supports the Ed25519 curve.
 
-If the 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`. The application can choose to implement some kind of JWK cache invalidation or other mechanism to handle such cases.
+To encode a JWT using your JWK:
 
 ```ruby
-  jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), 'optional-kid')
-  payload = { data: 'data' }
-  headers = { kid: jwk.kid }
-
-  token = JWT.encode(payload, jwk.keypair, 'RS512', headers)
+optional_parameters = { kid: 'my-kid', use: 'sig', alg: 'RS512' }
+jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), optional_parameters)
 
-  # The jwk loader would fetch the set of JWKs from a trusted source,
-  # to avoid malicious requests triggering cache invalidations there needs to be some kind of grace time or other logic for determining the validity of the invalidation.
-  # This example only allows cache invalidations every 5 minutes.
-  jwk_loader = ->(options) do
-    if options[:kid_not_found] && @cache_last_update < Time.now.to_i - 300
-      logger.info("Invalidating JWK cache. #{options[:kid]} not found from previous cache")
-      @cached_keys = nil
-    end
-    @cached_keys ||= begin
-      @cache_last_update = Time.now.to_i
-      { keys: [jwk.export] }
-    end
-  end
+# Encoding
+payload = { data: 'data' }
+token = JWT.encode(payload, jwk.signing_key, jwk[:alg], kid: jwk[:kid])
 
-  begin
-    JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwk_loader })
-  rescue JWT::JWKError
-    # Handle problems with the provided JWKs
-  rescue JWT::DecodeError
-    # Handle other decode related issues e.g. no kid in header, no matching public key found etc.
-  end
+# JSON Web Key Set for advertising your signing keys
+jwks_hash = JWT::JWK::Set.new(jwk).export
 ```
 
-or by passing the JWKs as a simple Hash
+To decode a JWT using a trusted entity's JSON Web Key Set (JWKS):
 
+```ruby
+jwks = JWT::JWK::Set.new(jwks_hash)
+jwks.filter! {|key| key[:use] == 'sig' } # Signing keys only!
+algorithms = jwks.map { |key| key[:alg] }.compact.uniq
+JWT.decode(token, nil, true, algorithms: algorithms, jwks: jwks)
 ```
-jwks = { keys: [{ ... }] } # keys accepts both of string and symbol
-JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwks})
+
+
+The `jwks` option can also be given as a lambda that evaluates every time a kid 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`.
+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.
+This behaviour may be overwritten by setting the `allow_nil_kid` option for `decode` to `true`.
+
+```ruby
+jwks_loader = ->(options) do
+  # The jwk loader would fetch the set of JWKs from a trusted source.
+  # To avoid malicious requests triggering cache invalidations there needs to be
+  # some kind of grace time or other logic for determining the validity of the invalidation.
+  # This example only allows cache invalidations every 5 minutes.
+  if options[:kid_not_found] && @cache_last_update < Time.now.to_i - 300
+    logger.info("Invalidating JWK cache. #{options[:kid]} not found from previous cache")
+    @cached_keys = nil
+  end
+  @cached_keys ||= begin
+    @cache_last_update = Time.now.to_i
+    # Replace with your own JWKS fetching routine
+    jwks = JWT::JWK::Set.new(jwks_hash)
+    jwks.select! { |key| key[:use] == 'sig' } # Signing Keys only
+    jwks
+  end
+end
+
+begin
+  JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwks_loader })
+rescue JWT::JWKError
+  # Handle problems with the provided JWKs
+rescue JWT::DecodeError
+  # Handle other decode related issues e.g. no kid in header, no matching public key found etc.
+end
 ```
 
 ### Importing and exporting JSON Web Keys
 
-The ::JWT::JWK class can be used to import and export both the public key (default behaviour) and the private key. To include the private key in the export pass the `include_private` parameter to the export method.
+The ::JWT::JWK class can be used to import both JSON Web Keys and OpenSSL keys
+and export to either format with and without the private key included.
+
+To include the private key in the export pass the `include_private` parameter to the export method.
 
 ```ruby
-jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048))
+# Import a JWK Hash (showing an HMAC example)
+jwk = JWT::JWK.new({ kty: 'oct', k: 'my-secret', kid: 'my-kid' })
+
+# Import an OpenSSL key
+# You can optionally add descriptive parameters to the JWK
+desc_params = { kid: 'my-kid', use: 'sig' }
+jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), desc_params)
 
+# Export as JWK Hash (public key only by default)
 jwk_hash = jwk.export
 jwk_hash_with_private_key = jwk.export(include_private: true)
+
+# Export as OpenSSL key
+public_key = jwk.verify_key
+private_key = jwk.signing_key if jwk.private?
+
+# You can also import and export entire JSON Web Key Sets
+jwks_hash = { keys: [{ kty: 'oct', k: 'my-secret', kid: 'my-kid' }] }
+jwks = JWT::JWK::Set.new(jwks_hash)
+jwks_hash = jwks.export
 ```
 
 ### Key ID (kid) and JWKs
 
-The key id (kid) generation in the gem is a custom algorithm and not based on any standards. To use a standardized JWK thumbprint (RFC 7638) as the kid for JWKs a generator type can be specified in the global configuration or can be given to the JWK instance on initialization.
+The key id (kid) generation in the gem is a custom algorithm and not based on any standards.
+To use a standardized JWK thumbprint (RFC 7638) as the kid for JWKs a generator type can be specified in the global configuration
+or can be given to the JWK instance on initialization.
 
 ```ruby
 JWT.configuration.jwk.kid_generator_type = :rfc7638_thumbprint
 # OR
 JWT.configuration.jwk.kid_generator = ::JWT::JWK::Thumbprint
 # OR
-jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), kid_generator: ::JWT::JWK::Thumbprint)
+jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), nil, kid_generator: ::JWT::JWK::Thumbprint)
 
 jwk_hash = jwk.export
 
 thumbprint_as_the_kid = jwk_hash[:kid]
-
 ```
 
 # Development and Tests

data/lib/jwt/base64.rb

@@ -3,14 +3,28 @@
 require 'base64'
 
 module JWT
-  # Base64 helpers
+  # Base64 encoding and decoding
   class Base64
     class << self
+      # Encode a string with URL-safe Base64 complying with RFC 4648 (not padded).
       def url_encode(str)
-        ::Base64.encode64(str).tr('+/', '-_').gsub(/[\n=]/, '')
+        ::Base64.urlsafe_encode64(str, padding: false)
       end
 
+      # Decode a string with URL-safe Base64 complying with RFC 4648.
+      # Deprecated support for RFC 2045 remains for now. ("All line breaks or other characters not found in Table 1 must be ignored by decoding software")
       def url_decode(str)
+        ::Base64.urlsafe_decode64(str)
+      rescue ArgumentError => e
+        raise unless e.message == 'invalid base64'
+        raise Base64DecodeError, 'Invalid base64 encoding' if JWT.configuration.strict_base64_decoding
+
+        loose_urlsafe_decode64(str).tap do
+          Deprecations.warning('Invalid base64 input detected, could be because of invalid padding, trailing whitespaces or newline chars. Graceful handling of invalid input will be dropped in the next major version of ruby-jwt')
+        end
+      end
+
+      def loose_urlsafe_decode64(str)
         str += '=' * (4 - str.length.modulo(4))
         ::Base64.decode64(str.tr('-_', '+/'))
       end

data/lib/jwt/claims_validator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative './error'
+require_relative 'error'
 
 module JWT
   class ClaimsValidator

data/lib/jwt/configuration/container.rb

@@ -6,15 +6,26 @@ require_relative 'jwk_configuration'
 module JWT
   module Configuration
     class Container
-      attr_accessor :decode, :jwk
+      attr_accessor :decode, :jwk, :strict_base64_decoding
+      attr_reader :deprecation_warnings
 
       def initialize
         reset!
       end
 
       def reset!
-        @decode = DecodeConfiguration.new
-        @jwk    = JwkConfiguration.new
+        @decode                 = DecodeConfiguration.new
+        @jwk                    = JwkConfiguration.new
+        @strict_base64_decoding = false
+
+        self.deprecation_warnings = :once
+      end
+
+      DEPRECATION_WARNINGS_VALUES = %i[once warn silent].freeze
+      def deprecation_warnings=(value)
+        raise ArgumentError, "Invalid deprecation_warnings value #{value}. Supported values: #{DEPRECATION_WARNINGS_VALUES}" unless DEPRECATION_WARNINGS_VALUES.include?(value)
+
+        @deprecation_warnings = value
       end
     end
   end

data/lib/jwt/decode.rb

@@ -2,9 +2,9 @@
 
 require 'json'
 
-require 'jwt/signature'
 require 'jwt/verify'
 require 'jwt/x5c_key_finder'
+
 # JWT::Decode module
 module JWT
   # Decoding logic for JWT
@@ -24,7 +24,7 @@ module JWT
     def decode_segments
       validate_segment_count!
       if @verify
-        decode_crypto
+        decode_signature
         verify_algo
         set_key
         verify_signature
@@ -51,40 +51,57 @@ module JWT
 
     def verify_algo
       raise(JWT::IncorrectAlgorithm, 'An algorithm must be specified') if allowed_algorithms.empty?
-      raise(JWT::IncorrectAlgorithm, 'Token is missing alg header') unless algorithm
-      raise(JWT::IncorrectAlgorithm, 'Expected a different algorithm') unless options_includes_algo_in_header?
+      raise(JWT::IncorrectAlgorithm, 'Token is missing alg header') unless alg_in_header
+      raise(JWT::IncorrectAlgorithm, 'Expected a different algorithm') if allowed_and_valid_algorithms.empty?
     end
 
     def set_key
       @key = find_key(&@keyfinder) if @keyfinder
-      @key = ::JWT::JWK::KeyFinder.new(jwks: @options[:jwks]).key_for(header['kid']) if @options[:jwks]
+      @key = ::JWT::JWK::KeyFinder.new(jwks: @options[:jwks], allow_nil_kid: @options[:allow_nil_kid]).key_for(header['kid']) if @options[:jwks]
       if (x5c_options = @options[:x5c])
         @key = X5cKeyFinder.new(x5c_options[:root_certificates], x5c_options[:crls]).from(header['x5c'])
       end
     end
 
     def verify_signature_for?(key)
-      Signature.verify(algorithm, key, signing_input, @signature)
+      allowed_and_valid_algorithms.any? do |alg|
+        alg.verify(data: signing_input, signature: @signature, verification_key: key)
+      end
     end
 
-    def options_includes_algo_in_header?
-      allowed_algorithms.any? { |alg| alg.casecmp(algorithm).zero? }
+    def allowed_and_valid_algorithms
+      @allowed_and_valid_algorithms ||= allowed_algorithms.select { |alg| alg.valid_alg?(alg_in_header) }
     end
 
-    def allowed_algorithms
-      # Order is very important - first check for string keys, next for symbols
-      algos = if @options.key?('algorithm')
-        @options['algorithm']
-      elsif @options.key?(:algorithm)
-        @options[:algorithm]
-      elsif @options.key?('algorithms')
-        @options['algorithms']
-      elsif @options.key?(:algorithms)
-        @options[:algorithms]
-      else
-        []
+    # Order is very important - first check for string keys, next for symbols
+    ALGORITHM_KEYS = ['algorithm',
+                      :algorithm,
+                      'algorithms',
+                      :algorithms].freeze
+
+    def given_algorithms
+      ALGORITHM_KEYS.each do |alg_key|
+        alg = @options[alg_key]
+        return Array(alg) if alg
       end
-      Array(algos)
+      []
+    end
+
+    def allowed_algorithms
+      @allowed_algorithms ||= resolve_allowed_algorithms
+    end
+
+    def resolve_allowed_algorithms
+      algs = given_algorithms.map { |alg| JWA.create(alg) }
+
+      sort_by_alg_header(algs)
+    end
+
+    # Move algorithms matching the JWT alg header to the beginning of the list
+    def sort_by_alg_header(algs)
+      return algs if algs.size <= 1
+
+      algs.partition { |alg| alg.valid_alg?(alg_in_header) }.flatten
     end
 
     def find_key(&keyfinder)
@@ -113,14 +130,14 @@ module JWT
     end
 
     def none_algorithm?
-      algorithm == 'none'
+      alg_in_header == 'none'
     end
 
-    def decode_crypto
+    def decode_signature
       @signature = ::JWT::Base64.url_decode(@segments[2] || '')
     end
 
-    def algorithm
+    def alg_in_header
       header['alg']
     end