jwt 2.3.0 → 2.5.0

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 master branch of the project.
+
+```
+git fetch --all
+git checkout master
+git rebase upstream/master
+git push origin master
+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.
+
+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 master.
+
+```
+git fetch upstream
+git checkout fix-a-little-problem
+git rebase upstream/master
+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/Gemfile

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec
 
-gem 'rubocop', '~> 0.52.0' # Same as codeclimate default
+gem 'rubocop', '~> 1.23.0' # Keep .codeclimate.yml channel in sync with this one

data/README.md

@@ -12,10 +12,12 @@ 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).
 
 ## 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|
@@ -42,7 +44,7 @@ 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)
 
-**NONE**
+### **NONE**
 
 * none - unsigned token
 
@@ -68,7 +70,7 @@ 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)
@@ -100,7 +102,7 @@ Note: If [RbNaCl](https://github.com/cryptosphere/rbnacl) is loadable, ruby-jwt
 [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
@@ -125,24 +127,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
 # [
@@ -152,7 +152,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`.
 
@@ -181,9 +181,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'
@@ -370,6 +370,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):
@@ -486,36 +516,68 @@ end
 
 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::ExpiredSignature error if the 'exp' claim is absent
+# Will raise a JWT::MissingRequiredClaim error if the 'exp' claim is absent
 JWT.decode token, hmac_secret, true, { required_claims: ['exp'], algorithm: 'HS256' }
 ```
 
-### JSON Web Key (JWK)
+### X.509 certificates in x5c header
 
-JWK is a JSON structure representing a cryptographic key. Currently only supports RSA public keys.
+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
-jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), "optional-kid")
-payload, headers = { data: 'data' }, { kid: jwk.kid }
-
-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] }
+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, { algorithms: ['RS512'], jwks: jwk_loader})
-rescue JWT::JWKError
-  # Handle problems with the provided JWKs
+  JWT.decode(token, nil, true, { x5c: { root_certificates: root_certificates, crls: crls })
 rescue JWT::DecodeError
-  # Handle other decode related issues e.g. no kid in header, no matching public key found etc.
+  # Handle error, e.g. x5c header certificate revoked or expired
 end
 ```
 
-or by passing JWK as a simple Hash
+### 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.
+
+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.
+
+```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)
+
+  # 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
+
+  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
+```
+
+or by passing the JWKs as a simple Hash
 
 ```
 jwks = { keys: [{ ... }] } # keys accepts both of string and symbol
@@ -524,7 +586,7 @@ JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwks})
 
 ### 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 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.
 
 ```ruby
 jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048))
@@ -533,6 +595,23 @@ jwk_hash = jwk.export
 jwk_hash_with_private_key = jwk.export(include_private: true)
 ```
 
+### 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), 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
@@ -548,12 +627,13 @@ 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/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'bundler/setup'
 require 'bundler/gem_tasks'
 

data/lib/jwt/algos/ecdsa.rb

@@ -1,35 +1,64 @@
+# frozen_string_literal: true
+
 module JWT
   module Algos
     module Ecdsa
       module_function
 
-      SUPPORTED = %w[ES256 ES384 ES512].freeze
       NAMED_CURVES = {
-        'prime256v1' => 'ES256',
-        'secp384r1' => 'ES384',
-        'secp521r1' => 'ES512'
+        'prime256v1' => {
+          algorithm: 'ES256',
+          digest: 'sha256'
+        },
+        'secp256r1' => { # alias for prime256v1
+          algorithm: 'ES256',
+          digest: 'sha256'
+        },
+        'secp384r1' => {
+          algorithm: 'ES384',
+          digest: 'sha384'
+        },
+        'secp521r1' => {
+          algorithm: 'ES512',
+          digest: 'sha512'
+        },
+        'secp256k1' => {
+          algorithm: 'ES256K',
+          digest: 'sha256'
+        }
       }.freeze
 
+      SUPPORTED = NAMED_CURVES.map { |_, c| c[:algorithm] }.uniq.freeze
+
       def sign(to_sign)
         algorithm, msg, key = to_sign.values
-        key_algorithm = NAMED_CURVES[key.group.curve_name]
+        curve_definition = curve_by_name(key.group.curve_name)
+        key_algorithm = curve_definition[:algorithm]
         if algorithm != key_algorithm
           raise IncorrectAlgorithm, "payload algorithm is #{algorithm} but #{key_algorithm} signing key was provided"
         end
 
-        digest = OpenSSL::Digest.new(algorithm.sub('ES', 'sha'))
+        digest = OpenSSL::Digest.new(curve_definition[:digest])
         SecurityUtils.asn1_to_raw(key.dsa_sign_asn1(digest.digest(msg)), key)
       end
 
       def verify(to_verify)
         algorithm, public_key, signing_input, signature = to_verify.values
-        key_algorithm = NAMED_CURVES[public_key.group.curve_name]
+        curve_definition = curve_by_name(public_key.group.curve_name)
+        key_algorithm = curve_definition[:algorithm]
         if algorithm != key_algorithm
           raise IncorrectAlgorithm, "payload algorithm is #{algorithm} but #{key_algorithm} verification key was provided"
         end
-        digest = OpenSSL::Digest.new(algorithm.sub('ES', 'sha'))
+
+        digest = OpenSSL::Digest.new(curve_definition[:digest])
         public_key.dsa_verify_asn1(digest.digest(signing_input), SecurityUtils.raw_to_asn1(signature, public_key))
       end
+
+      def curve_by_name(name)
+        NAMED_CURVES.fetch(name) do
+          raise UnsupportedEcdsaCurve, "The ECDSA curve '#{name}' is not supported"
+        end
+      end
     end
   end
 end

data/lib/jwt/algos/eddsa.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JWT
   module Algos
     module Eddsa
@@ -23,7 +25,10 @@ module JWT
           raise IncorrectAlgorithm, "payload algorithm is #{algorithm} but #{key.primitive} signing key was provided"
         end
         raise DecodeError, "key given is a #{public_key.class} but has to be a RbNaCl::Signatures::Ed25519::VerifyKey" if public_key.class != RbNaCl::Signatures::Ed25519::VerifyKey
+
         public_key.verify(signature, signing_input)
+      rescue RbNaCl::CryptoError
+        false
       end
     end
   end

data/lib/jwt/algos/hmac.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JWT
   module Algos
     module Hmac

data/lib/jwt/algos/none.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JWT
   module Algos
     module None

data/lib/jwt/algos/ps.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JWT
   module Algos
     module Ps
@@ -29,9 +31,7 @@ module JWT
 
       def require_openssl!
         if Object.const_defined?('OpenSSL')
-          major, minor = OpenSSL::VERSION.split('.').first(2)
-
-          unless major.to_i >= 2 && minor.to_i >= 1
+          if ::Gem::Version.new(OpenSSL::VERSION) < ::Gem::Version.new('2.1')
             raise JWT::RequiredDependencyError, "You currently have OpenSSL #{OpenSSL::VERSION}. PS support requires >= 2.1"
           end
         else

data/lib/jwt/algos/rsa.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JWT
   module Algos
     module Rsa
@@ -7,7 +9,8 @@ module JWT
 
       def sign(to_sign)
         algorithm, msg, key = to_sign.values
-        raise EncodeError, "The given key is a #{key.class}. It has to be an OpenSSL::PKey::RSA instance." if key.class == String
+        raise EncodeError, "The given key is a #{key.class}. It has to be an OpenSSL::PKey::RSA instance." if key.instance_of?(String)
+
         key.sign(OpenSSL::Digest.new(algorithm.sub('RS', 'sha')), msg)
       end
 

data/lib/jwt/algos/unsupported.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JWT
   module Algos
     module Unsupported

data/lib/jwt/claims_validator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative './error'
 
 module JWT
@@ -9,7 +11,7 @@ module JWT
     ].freeze
 
     def initialize(payload)
-      @payload = payload.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+      @payload = payload.transform_keys(&:to_sym)
     end
 
     def validate!

data/lib/jwt/configuration/container.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'decode_configuration'
+require_relative 'jwk_configuration'
+
+module JWT
+  module Configuration
+    class Container
+      attr_accessor :decode, :jwk
+
+      def initialize
+        reset!
+      end
+
+      def reset!
+        @decode = DecodeConfiguration.new
+        @jwk    = JwkConfiguration.new
+      end
+    end
+  end
+end

data/lib/jwt/configuration/decode_configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module JWT
+  module Configuration
+    class DecodeConfiguration
+      attr_accessor :verify_expiration,
+                    :verify_not_before,
+                    :verify_iss,
+                    :verify_iat,
+                    :verify_jti,
+                    :verify_aud,
+                    :verify_sub,
+                    :leeway,
+                    :algorithms,
+                    :required_claims
+
+      def initialize
+        @verify_expiration = true
+        @verify_not_before = true
+        @verify_iss = false
+        @verify_iat = false
+        @verify_jti = false
+        @verify_aud = false
+        @verify_sub = false
+        @leeway = 0
+        @algorithms = ['HS256']
+        @required_claims = []
+      end
+
+      def to_h
+        {
+          verify_expiration: verify_expiration,
+          verify_not_before: verify_not_before,
+          verify_iss: verify_iss,
+          verify_iat: verify_iat,
+          verify_jti: verify_jti,
+          verify_aud: verify_aud,
+          verify_sub: verify_sub,
+          leeway: leeway,
+          algorithms: algorithms,
+          required_claims: required_claims
+        }
+      end
+    end
+  end
+end

data/lib/jwt/configuration/jwk_configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../jwk/kid_as_key_digest'
+require_relative '../jwk/thumbprint'
+
+module JWT
+  module Configuration
+    class JwkConfiguration
+      def initialize
+        self.kid_generator_type = :key_digest
+      end
+
+      def kid_generator_type=(value)
+        self.kid_generator = case value
+                             when :key_digest
+                               JWT::JWK::KidAsKeyDigest
+                             when :rfc7638_thumbprint
+                               JWT::JWK::Thumbprint
+                             else
+                               raise ArgumentError, "#{value} is not a valid kid generator type."
+        end
+      end
+
+      attr_accessor :kid_generator
+    end
+  end
+end

data/lib/jwt/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'configuration/container'
+
+module JWT
+  module Configuration
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= ::JWT::Configuration::Container.new
+    end
+  end
+end