jwt 2.2.1 → 2.8.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at antmanj@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to [ruby-jwt](https://github.com/jwt/ruby-jwt)
+
+## Forking the project
+
+Fork the project on GitHub and clone your own fork. Instuctions on forking can be found from the [GitHub Docs](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
+
+```
+git clone git@github.com:you/ruby-jwt.git
+cd ruby-jwt
+git remote add upstream https://github.com/jwt/ruby-jwt
+```
+
+## Create a branch for your implementation
+
+Make sure you have the latest upstream main branch of the project.
+
+```
+git fetch --all
+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 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.
+
+[Rubocop](https://github.com/rubocop/rubocop) is used to enforce the Ruby style.
+
+To run the complete set of tests and linter run the following
+
+```bash
+bundle install
+bundle exec appraisal rake test
+bundle exec rubocop
+```
+
+## Implement your feature
+
+Implement tests and your change. Don't be shy adding a little something in the [README](README.md).
+Add a short description of the change in either the `Features` or `Fixes` section in the [CHANGELOG](CHANGELOG.md) file.
+
+The form of the row (You need to return to the row when you know the pull request id)
+```
+- Fix a little problem [#123](https://github.com/jwt/ruby-jwt/pull/123) - [@you](https://github.com/you).
+```
+
+## Push your branch and create a pull request
+
+Before pushing make sure the tests pass and RuboCop is happy.
+
+```
+bundle exec appraisal rake test
+bundle exec rubocop
+git push origin fix-a-little-problem
+```
+
+Make a new pull request on the [ruby-jwt project](https://github.com/jwt/ruby-jwt/pulls) with a description what the change is about.
+
+## Update the CHANGELOG, again
+
+Update the [CHANGELOG](CHANGELOG.md) with the pull request id from the previous step.
+
+You can ammend the previous commit with the updated changelog change and force push your branch. The PR will get automatically updated.
+
+```
+git add CHANGELOG.md
+git commit --amend --no-edit
+git push origin fix-a-little-problem -f
+```
+
+## Keep an eye on your pull request
+
+A maintainer will review and probably merge you changes when time allows, be patient.
+
+## Keeping your branch up-to-date
+
+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/main
+git push origin fix-a-little-problem -f
+```
+
+# Releasing a new version
+
+The version is using the [Semantic Versioning](http://semver.org/) and the version is located in the [version.rb](lib/jwt/version.rb) file.
+Also update the [CHANGELOG](CHANGELOG.md) to reflect the upcoming version release.
+
+```bash
+rake release
+```
+
+**If you want a release cut with your PR, please include a version bump according to **

data/README.md

@@ -1,26 +1,33 @@
 # JWT
 
 [![Gem Version](https://badge.fury.io/rb/jwt.svg)](https://badge.fury.io/rb/jwt)
-[![Build Status](https://travis-ci.org/jwt/ruby-jwt.svg)](https://travis-ci.org/jwt/ruby-jwt)
+[![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)
-[![Ebert](https://ebertapp.io/github/jwt/ruby-jwt.svg)](https://ebertapp.io/github/jwt/ruby-jwt)
 
 A ruby implementation of the [RFC 7519 OAuth JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) standard.
 
 If you have further questions related to development or usage, join us: [ruby-jwt google group](https://groups.google.com/forum/#!forum/ruby-jwt).
 
 ## Announcements
-
+* Ruby 2.4 support was dropped in version 2.4.0
 * Ruby 1.9.3 support was dropped at December 31st, 2016.
 * Version 1.5.3 yanked. See: [#132](https://github.com/jwt/ruby-jwt/issues/132) and [#133](https://github.com/jwt/ruby-jwt/issues/133)
 
+See [CHANGELOG.md](CHANGELOG.md) for a complete set of changes.
+
+## Sponsors
+
+|Logo|Message|
+|-|-|
+|![auth0 logo](https://user-images.githubusercontent.com/83319/31722733-de95bbde-b3ea-11e7-96bf-4f4e8f915588.png)|If you want to quickly add secure token-based authentication to Ruby projects, feel free to check Auth0's Ruby SDK and free plan at [auth0.com/developers](https://auth0.com/developers?utm_source=GHsponsor&utm_medium=GHsponsor&utm_campaign=rubyjwt&utm_content=auth)|
+
 ## Installing
 
 ### Using Rubygems:
 ```bash
-sudo gem install jwt
+gem install jwt
 ```
 
 ### Using Bundler:
@@ -32,11 +39,28 @@ And run `bundle install`
 
 ## Algorithms and Usage
 
-The JWT spec supports NONE, HMAC, RSASSA, ECDSA and RSASSA-PSS algorithms for cryptographic signing. Currently the jwt gem supports NONE, HMAC, RSASSA and ECDSA. If you are using cryptographic signing, you need to specify the algorithm in the options hash whenever you call JWT.decode to ensure that an attacker [cannot bypass the algorithm verification step](https://auth0.com/blog/2015/03/31/critical-vulnerabilities-in-json-web-token-libraries/). **It is strongly recommended that you hard code the algorithm, as you may leave yourself vulnerable by dynamically picking the algorithm**
+The JWT spec supports NONE, HMAC, RSASSA, ECDSA and RSASSA-PSS algorithms for cryptographic signing. Currently the jwt gem supports NONE, HMAC, RSASSA and ECDSA. If you are using cryptographic signing, you need to specify the algorithm in the options hash whenever you call JWT.decode to ensure that an attacker [cannot bypass the algorithm verification step](https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/). **It is strongly recommended that you hard code the algorithm, as you may leave yourself vulnerable by dynamically picking the algorithm**
 
 See: [ JSON Web Algorithms (JWA) 3.1. "alg" (Algorithm) Header Parameter Values for JWS](https://tools.ietf.org/html/rfc7518#section-3.1)
 
-**NONE**
+### 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
 
@@ -62,14 +86,14 @@ decoded_token = JWT.decode token, nil, false
 puts decoded_token
 ```
 
-**HMAC**
+### **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. 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'
@@ -87,13 +111,7 @@ 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**
+### **RSA**
 
 * RS256 - RSA using SHA-256 hash algorithm
 * RS384 - RSA using SHA-384 hash algorithm
@@ -118,24 +136,22 @@ decoded_token = JWT.decode token, rsa_public, true, { algorithm: 'RS256' }
 puts decoded_token
 ```
 
-**ECDSA**
+### **ECDSA**
 
 * ES256 - ECDSA using P-256 and SHA-256
 * ES384 - ECDSA using P-384 and SHA-384
 * ES512 - ECDSA using P-521 and SHA-512
+* ES256K - ECDSA using P-256K and SHA-256
 
 ```ruby
-ecdsa_key = OpenSSL::PKey::EC.new 'prime256v1'
-ecdsa_key.generate_key
-ecdsa_public = OpenSSL::PKey::EC.new ecdsa_key
-ecdsa_public.private_key = nil
+ecdsa_key = OpenSSL::PKey::EC.generate('prime256v1')
 
 token = JWT.encode payload, ecdsa_key, 'ES256'
 
 # eyJhbGciOiJFUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.AlLW--kaF7EX1NMX9WJRuIW8NeRJbn2BLXHns7Q5TZr7Hy3lF6MOpMlp7GoxBFRLISQ6KrD0CJOrR8aogEsPeg
 puts token
 
-decoded_token = JWT.decode token, ecdsa_public, true, { algorithm: 'ES256' }
+decoded_token = JWT.decode token, ecdsa_key, true, { algorithm: 'ES256' }
 
 # Array
 # [
@@ -145,7 +161,7 @@ decoded_token = JWT.decode token, ecdsa_public, true, { algorithm: 'ES256' }
 puts decoded_token
 ```
 
-**EDDSA**
+### **EDDSA**
 
 In order to use this algorithm you need to add the `RbNaCl` gem to you `Gemfile`.
 
@@ -153,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
 
@@ -174,9 +190,9 @@ decoded_token = JWT.decode token, public_key, true, { algorithm: 'ED25519' }
 
 ```
 
-**RSASSA-PSS**
+### **RSASSA-PSS**
 
-In order to use this algorithm you need to add the `openssl` gem to you `Gemfile` with a version greater or equal to `2.1`.
+In order to use this algorithm you need to add the `openssl` gem to your `Gemfile` with a version greater or equal to `2.1`.
 
 ```ruby
 gem 'openssl', '~> 2.1'
@@ -205,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:
@@ -270,6 +313,12 @@ rescue JWT::ExpiredSignature
 end
 ```
 
+The Expiration Claim verification can be disabled.
+```ruby
+# Decode token without raising JWT::ExpiredSignature error
+JWT.decode token, hmac_secret, true, { verify_expiration: false, algorithm: 'HS256' }
+```
+
 **Adding Leeway**
 
 ```ruby
@@ -310,6 +359,12 @@ rescue JWT::ImmatureSignature
 end
 ```
 
+The Not Before Claim verification can be disabled.
+```ruby
+# Decode token without raising JWT::ImmatureSignature error
+JWT.decode token, hmac_secret, true, { verify_not_before: false, algorithm: 'HS256' }
+```
+
 **Adding Leeway**
 
 ```ruby
@@ -351,6 +406,36 @@ rescue JWT::InvalidIssuerError
 end
 ```
 
+You can also pass a Regexp or Proc (with arity 1), verification will pass if the regexp matches or the proc returns truthy.
+On supported ruby versions (>= 2.5) you can also delegate to methods, on older versions you will have
+to convert them to proc (using `to_proc`)
+
+```ruby
+JWT.decode token, hmac_secret, true,
+           iss: %r'https://my.awesome.website/',
+           verify_iss: true,
+           algorithm: 'HS256'
+```
+
+```ruby
+JWT.decode token, hmac_secret, true,
+           iss: ->(issuer) { issuer.start_with?('My Awesome Company Inc') },
+           verify_iss: true,
+           algorithm: 'HS256'
+```
+
+```ruby
+JWT.decode token, hmac_secret, true,
+           iss: method(:valid_issuer?),
+           verify_iss: true,
+           algorithm: 'HS256'
+
+# somewhere in the same class:
+def valid_issuer?(issuer)
+  # custom validation
+end
+```
+
 ### Audience Claim
 
 From [Oauth JSON Web Token 4.1.3. "aud" (Audience) Claim](https://tools.ietf.org/html/rfc7519#section-4.1.3):
@@ -391,6 +476,8 @@ begin
   #decoded_token = JWT.decode token, hmac_secret, true, { verify_jti: true, algorithm: 'HS256' }
   # Alternatively, pass a proc with your own code to check if the JTI has already been used
   decoded_token = JWT.decode token, hmac_secret, true, { verify_jti: proc { |jti| my_validation_method(jti) }, algorithm: 'HS256' }
+  # or
+  decoded_token = JWT.decode token, hmac_secret, true, { verify_jti: proc { |jti, payload| my_validation_method(jti, payload) }, algorithm: 'HS256' }
 rescue JWT::InvalidJtiError
   # Handle invalid token, e.g. logout user or deny access
   puts 'Error'
@@ -439,31 +526,170 @@ rescue JWT::InvalidSubError
 end
 ```
 
+### Finding a Key
+
+To dynamically find the key for verifying the JWT signature, pass a block to the decode block. The block receives headers and the original payload as parameters. It should return with the key to verify the signature that was used to sign the JWT.
+
+```ruby
+issuers = %w[My_Awesome_Company1 My_Awesome_Company2]
+iss_payload = { data: 'data', iss: issuers.first }
+
+secrets = { issuers.first => hmac_secret, issuers.last => 'hmac_secret2' }
+
+token = JWT.encode iss_payload, hmac_secret, 'HS256'
+
+begin
+  # Add iss to the validation to check if the token has been manipulated
+  decoded_token = JWT.decode(token, nil, true, { iss: issuers, verify_iss: true, algorithm: 'HS256' }) do |_headers, payload|
+    secrets[payload['iss']]
+  end
+rescue JWT::InvalidIssuerError
+  # Handle invalid token, e.g. logout user or deny access
+end
+```
+
+### Required Claims
+
+You can specify claims that must be present for decoding to be successful. JWT::MissingRequiredClaim will be raised if any are missing
+```ruby
+# Will raise a JWT::MissingRequiredClaim error if the 'exp' claim is absent
+JWT.decode token, hmac_secret, true, { required_claims: ['exp'], algorithm: 'HS256' }
+```
+
+### X.509 certificates in x5c header
+
+A JWT signature can be verified using certificate(s) given in the `x5c` header. Before doing that, the trustworthiness of these certificate(s) must be established. This is done in accordance with RFC 5280 which (among other things) verifies the certificate(s) are issued by a trusted root certificate, the timestamps are valid, and none of the certificate(s) are revoked (i.e. being present in the root certificate's Certificate Revocation List).
+
+```ruby
+root_certificates = [] # trusted `OpenSSL::X509::Certificate` objects
+crl_uris = root_certificates.map(&:crl_uris)
+crls = crl_uris.map do |uri|
+  # look up cached CRL by `uri` and return it if found, otherwise continue
+  crl = Net::HTTP.get(uri)
+  crl = OpenSSL::X509::CRL.new(crl)
+  # cache `crl` using `uri` as the key, expiry set to `crl.next_update` timestamp
+end
+
+begin
+  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
+```
+
 ### JSON Web Key (JWK)
 
-JWK is a JSON structure representing a cryptographic key. Currently only supports RSA public keys.
+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.
+
+To encode a JWT using your JWK:
+
+```ruby
+optional_parameters = { kid: 'my-kid', use: 'sig', alg: 'RS512' }
+jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), optional_parameters)
+
+# Encoding
+payload = { data: 'data' }
+token = JWT.encode(payload, jwk.signing_key, jwk[:alg], kid: jwk[:kid])
+
+# JSON Web Key Set for advertising your signing keys
+jwks_hash = JWT::JWK::Set.new(jwk).export
+```
+
+To decode a JWT using a trusted entity's JSON Web Key Set (JWKS):
 
 ```ruby
-jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048))
-payload, headers = { data: 'data' }, { kid: jwk.kid }
+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)
+```
 
-token = JWT.encode(payload, jwk.keypair, 'RS512', headers)
 
-# The jwk loader would fetch the set of JWKs from a trusted source
-jwk_loader = ->(options) do
-  @cached_keys = nil if options[:invalidate] # need to reload the keys
-  @cached_keys ||= { keys: [jwk.export] }
+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: jwk_loader})
+  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. 
+  # 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 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
+# 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.
+
+```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), nil, kid_generator: ::JWT::JWK::Thumbprint)
+
+jwk_hash = jwk.export
+
+thumbprint_as_the_kid = jwk_hash[:kid]
+```
+
 # Development and Tests
 
 We depend on [Bundler](http://rubygems.org/gems/bundler) for defining gemspec and performing releases to rubygems.org, which can be done with
@@ -472,18 +698,20 @@ We depend on [Bundler](http://rubygems.org/gems/bundler) for defining gemspec an
 rake release
 ```
 
-The tests are written with rspec. Given you have installed the dependencies via bundler, you can run tests with
+The tests are written with rspec. [Appraisal](https://github.com/thoughtbot/appraisal) is used to ensure compatibility with 3rd party dependencies providing cryptographic features.
 
 ```bash
-bundle exec rspec
+bundle install
+bundle exec appraisal rake test
 ```
 
-**If you want a release cut with your PR, please include a version bump according to [Semantic Versioning](http://semver.org/)**
+## How to contribute
+See [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Contributors
 
-See `AUTHORS` file.
+See [AUTHORS](AUTHORS).
 
 ## License
 
-See `LICENSE` file.
+See [LICENSE](LICENSE).

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