jwt 2.3.0 → 2.4.1

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 is going to be 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,11 +127,12 @@ 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'
@@ -152,7 +155,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,7 +184,7 @@ 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`.
 
@@ -370,6 +373,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,13 +519,34 @@ 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' }
 ```
 
+### 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. Currently only supports RSA, EC and HMAC keys.
 
 ```ruby
 jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), "optional-kid")
@@ -524,7 +578,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,27 +587,14 @@ jwk_hash = jwk.export
 jwk_hash_with_private_key = jwk.export(include_private: true)
 ```
 
-# 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
-
-```bash
-rake release
-```
-
-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 install
-bundle exec appraisal rake test
-```
+## How to contribute
 
-**If you want a release cut with your PR, please include a version bump according to [Semantic Versioning](http://semver.org/)**
+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,6 +25,7 @@ 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)
       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/decode.rb

@@ -4,12 +4,14 @@ require 'json'
 
 require 'jwt/signature'
 require 'jwt/verify'
+require 'jwt/x5c_key_finder'
 # JWT::Decode module
 module JWT
   # Decoding logic for JWT
   class Decode
     def initialize(jwt, key, verify, options, &keyfinder)
       raise(JWT::DecodeError, 'Nil JSON web token') unless jwt
+
       @jwt = jwt
       @key = key
       @options = options
@@ -23,28 +25,50 @@ module JWT
       validate_segment_count!
       if @verify
         decode_crypto
+        verify_algo
+        set_key
         verify_signature
         verify_claims
       end
       raise(JWT::DecodeError, 'Not enough or too many segments') unless header && payload
+
       [payload, header]
     end
 
     private
 
     def verify_signature
+      return unless @key || @verify
+
+      return if none_algorithm?
+
+      raise JWT::DecodeError, 'No verification key available' unless @key
+
+      return if Array(@key).any? { |key| verify_signature_for?(key) }
+
+      raise(JWT::VerificationError, 'Signature verification failed')
+    end
+
+    def verify_algo
       raise(JWT::IncorrectAlgorithm, 'An algorithm must be specified') if allowed_algorithms.empty?
-      raise(JWT::IncorrectAlgorithm, 'Token is missing alg header') unless header['alg']
+      raise(JWT::IncorrectAlgorithm, 'Token is missing alg header') unless algorithm
       raise(JWT::IncorrectAlgorithm, 'Expected a different algorithm') unless options_includes_algo_in_header?
+    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]
+      if (x5c_options = @options[:x5c])
+        @key = X5cKeyFinder.new(x5c_options[:root_certificates], x5c_options[:crls]).from(header['x5c'])
+      end
+    end
 
-      Signature.verify(header['alg'], @key, signing_input, @signature)
+    def verify_signature_for?(key)
+      Signature.verify(algorithm, key, signing_input, @signature)
     end
 
     def options_includes_algo_in_header?
-      allowed_algorithms.any? { |alg| alg.casecmp(header['alg']).zero? }
+      allowed_algorithms.any? { |alg| alg.casecmp(algorithm).zero? }
     end
 
     def allowed_algorithms
@@ -65,8 +89,10 @@ module JWT
 
     def find_key(&keyfinder)
       key = (keyfinder.arity == 2 ? yield(header, payload) : yield(header))
-      raise JWT::DecodeError, 'No verification key available' unless key
-      key
+      # key can be of type [string, nil, OpenSSL::PKey, Array]
+      return key if key && !Array(key).empty?
+
+      raise JWT::DecodeError, 'No verification key available'
     end
 
     def verify_claims
@@ -77,7 +103,7 @@ module JWT
     def validate_segment_count!
       return if segment_length == 3
       return if !@verify && segment_length == 2 # If no verifying required, the signature is not needed
-      return if segment_length == 2 && header['alg'] == 'none'
+      return if segment_length == 2 && none_algorithm?
 
       raise(JWT::DecodeError, 'Not enough or too many segments')
     end
@@ -86,8 +112,18 @@ module JWT
       @segments.count
     end
 
+    def none_algorithm?
+      algorithm.casecmp('none').zero?
+    end
+
     def decode_crypto
-      @signature = JWT::Base64.url_decode(@segments[2] || '')
+      @signature = Base64.urlsafe_decode64(@segments[2] || '')
+    rescue ArgumentError
+      raise(JWT::DecodeError, 'Invalid segment encoding')
+    end
+
+    def algorithm
+      header['alg']
     end
 
     def header
@@ -103,8 +139,8 @@ module JWT
     end
 
     def parse_and_decode(segment)
-      JWT::JSON.parse(JWT::Base64.url_decode(segment))
-    rescue ::JSON::ParserError
+      JWT::JSON.parse(Base64.urlsafe_decode64(segment))
+    rescue ::JSON::ParserError, ArgumentError
       raise JWT::DecodeError, 'Invalid segment encoding'
     end
   end

data/lib/jwt/default_options.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JWT
   module DefaultOptions
     DEFAULT_OPTIONS = {

data/lib/jwt/encode.rb

@@ -7,14 +7,14 @@ require_relative './claims_validator'
 module JWT
   # Encoding logic for JWT
   class Encode
-    ALG_NONE = 'none'.freeze
-    ALG_KEY  = 'alg'.freeze
+    ALG_NONE = 'none'
+    ALG_KEY  = 'alg'
 
     def initialize(options)
       @payload = options[:payload]
       @key = options[:key]
       _, @algorithm = Algos.find(options[:algorithm])
-      @headers = options[:headers].each_with_object({}) { |(key, value), headers| headers[key.to_s] = value }
+      @headers = options[:headers].transform_keys(&:to_s)
     end
 
     def segments
@@ -45,7 +45,7 @@ module JWT
     end
 
     def encode_payload
-      if @payload && @payload.is_a?(Hash)
+      if @payload.is_a?(Hash)
         ClaimsValidator.new(@payload).validate!
       end
 
@@ -55,11 +55,11 @@ module JWT
     def encode_signature
       return '' if @algorithm == ALG_NONE
 
-      JWT::Base64.url_encode(JWT::Signature.sign(@algorithm, encoded_header_and_payload, @key))
+      Base64.urlsafe_encode64(JWT::Signature.sign(@algorithm, encoded_header_and_payload, @key), padding: false)
     end
 
     def encode(data)
-      JWT::Base64.url_encode(JWT::JSON.generate(data))
+      Base64.urlsafe_encode64(JWT::JSON.generate(data), padding: false)
     end
 
     def combine(*parts)

data/lib/jwt/error.rb

@@ -10,6 +10,7 @@ module JWT
   class IncorrectAlgorithm < DecodeError; end
   class ImmatureSignature < DecodeError; end
   class InvalidIssuerError < DecodeError; end
+  class UnsupportedEcdsaCurve < IncorrectAlgorithm; end
   class InvalidIatError < DecodeError; end
   class InvalidAudError < DecodeError; end
   class InvalidSubError < DecodeError; end

data/lib/jwt/jwk/ec.rb

@@ -8,7 +8,7 @@ module JWT
       extend Forwardable
       def_delegators :@keypair, :public_key
 
-      KTY    = 'EC'.freeze
+      KTY    = 'EC'
       KTYS   = [KTY, OpenSSL::PKey::EC].freeze
       BINARY = 2
 
@@ -59,6 +59,9 @@ module JWT
         when 'prime256v1'
           crv = 'P-256'
           x_octets, y_octets = encoded_point.unpack('xa32a32')
+        when 'secp256k1'
+          crv = 'P-256K'
+          x_octets, y_octets = encoded_point.unpack('xa32a32')
         when 'secp384r1'
           crv = 'P-384'
           x_octets, y_octets = encoded_point.unpack('xa48a48')
@@ -72,11 +75,11 @@ module JWT
       end
 
       def encode_octets(octets)
-        ::JWT::Base64.url_encode(octets)
+        Base64.urlsafe_encode64(octets, padding: false)
       end
 
       def encode_open_ssl_bn(key_part)
-        ::JWT::Base64.url_encode(key_part.to_s(BINARY))
+        Base64.urlsafe_encode64(key_part.to_s(BINARY), padding: false)
       end
 
       class << self
@@ -98,6 +101,7 @@ module JWT
           when 'P-256' then 'prime256v1'
           when 'P-384' then 'secp384r1'
           when 'P-521' then 'secp521r1'
+          when 'P-256K' then 'secp256k1'
           else raise JWT::JWKError, 'Invalid curve provided'
           end
         end
@@ -138,11 +142,11 @@ module JWT
         end
 
         def decode_octets(jwk_data)
-          ::JWT::Base64.url_decode(jwk_data)
+          Base64.urlsafe_decode64(jwk_data)
         end
 
         def decode_open_ssl_bn(jwk_data)
-          OpenSSL::BN.new(::JWT::Base64.url_decode(jwk_data), BINARY)
+          OpenSSL::BN.new(Base64.urlsafe_decode64(jwk_data), BINARY)
         end
       end
     end

data/lib/jwt/jwk/hmac.rb

@@ -3,7 +3,7 @@
 module JWT
   module JWK
     class HMAC < KeyBase
-      KTY = 'oct'.freeze
+      KTY = 'oct'
       KTYS = [KTY, String].freeze
 
       def initialize(keypair, kid = nil)
@@ -50,7 +50,7 @@ module JWT
 
           raise JWT::JWKError, 'Key format is invalid for HMAC' unless jwk_k
 
-          self.new(jwk_k, jwk_kid)
+          new(jwk_k, jwk_kid)
         end
       end
     end

data/lib/jwt/jwk/key_base.rb

@@ -11,6 +11,7 @@ module JWT
       end
 
       def self.inherited(klass)
+        super
         ::JWT::JWK.classes << klass
       end
     end

data/lib/jwt/jwk/rsa.rb

@@ -4,12 +4,13 @@ module JWT
   module JWK
     class RSA < KeyBase
       BINARY = 2
-      KTY    = 'RSA'.freeze
+      KTY    = 'RSA'
       KTYS   = [KTY, OpenSSL::PKey::RSA].freeze
       RSA_KEY_ELEMENTS = %i[n e d p q dp dq qi].freeze
 
       def initialize(keypair, kid = nil)
         raise ArgumentError, 'keypair must be of type OpenSSL::PKey::RSA' unless keypair.is_a?(OpenSSL::PKey::RSA)
+
         super(keypair, kid || generate_kid(keypair.public_key))
       end
 
@@ -54,7 +55,7 @@ module JWT
       end
 
       def encode_open_ssl_bn(key_part)
-        ::JWT::Base64.url_encode(key_part.to_s(BINARY))
+        Base64.urlsafe_encode64(key_part.to_s(BINARY), padding: false)
       end
 
       class << self
@@ -63,7 +64,7 @@ module JWT
             decode_open_ssl_bn(value)
           end
           kid = jwk_attributes(jwk_data, :kid)[:kid]
-          self.new(rsa_pkey(pkey_params), kid)
+          new(rsa_pkey(pkey_params), kid)
         end
 
         private
@@ -107,7 +108,7 @@ module JWT
         def decode_open_ssl_bn(jwk_data)
           return nil unless jwk_data
 
-          OpenSSL::BN.new(::JWT::Base64.url_decode(jwk_data), BINARY)
+          OpenSSL::BN.new(Base64.urlsafe_decode64(jwk_data), BINARY)
         end
       end
     end

data/lib/jwt/jwk.rb

@@ -36,6 +36,7 @@ module JWT
       def generate_mappings
         classes.each_with_object({}) do |klass, hash|
           next unless klass.const_defined?('KTYS')
+
           Array(klass::KTYS).each do |kty|
             hash[kty] = klass
           end

data/lib/jwt/security_utils.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JWT
   # Collection of security methods
   #