json_web_token 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 21a6837b18ab16118d156cf6c60a4755d7b77a5f
-  data.tar.gz: 1fb7a084e74974042be3e5727028952ae3a8cb05
+  metadata.gz: 973c4dc365edec01a991491309d0332b3898dd57
+  data.tar.gz: 05d71d73011230c2b2f074eed6d2ea86bf0be1cf
 SHA512:
-  metadata.gz: b2d05859095e77ca73ef8c82d827716ff3d9ee0466567b0118ec929e2078ed852dca96fa95f5157a7e98b613e76359b0815c52b3e04fe8bfc232e26a94d1a2f1
-  data.tar.gz: a0ff00b0e9dc1a9ae7f18fa104d0630eda6798aea6450d1af497e2dd13f7e9f6f812186ae05105eaa07e2685e9e51c026ea9a12fa994a1b1f34f392d319a04c0
+  metadata.gz: 640c8738d52377295275bc4c5498b02a7fd427ffdf2b8d14b5765acc90fd8868c401799f0ccbb0535d37143ee90138ff5f80621edee6c902344106a5f1727786
+  data.tar.gz: fa2e818be12da6b351eb202b4ca2de9ab0efdd48f789d1e61e2e3683ae7fa9f50026e716d69578eb2c850266f72b5cc6bac4c94d570148cd4194d06ceb67b49f

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Changelog
 
+### v0.1.2 (2015-08-02)
+
+* enhancements
+  * Jws#verify returns false (rather than 'Invalid') unless the signature is verified
+
 ### v0.1.1 (2015-07-13)
 
 * bug fix

data/Gemfile

@@ -4,3 +4,4 @@ gemspec
 
 gem 'pry-byebug', '~> 3.1', require: false
 gem 'simplecov', '~> 0.10', require: false
+gem 'yard', '~> 0.8', require: false

data/README.md

@@ -1,4 +1,4 @@
-# JSON Web Token [![travis][ci_img]][travis] [![code_climate][cc_img]][code_climate]
+# JSON Web Token [![travis][ci_img]][travis] [![yard docs][yd_img]][yard_docs] [![code climate][cc_img]][code_climate]
 
 ## A JSON Web Token implementation for Ruby
 
@@ -36,7 +36,7 @@ Returns a JSON Web Token string
 
 `claims` (required) string or hash
 
-`options` (optional) hash
+`options` (required) hash
 
 * **alg** (optional, default: `HS256`)
 * **key** (required unless alg is 'none')
@@ -70,7 +70,7 @@ Returns either:
 
 `jwt` (required) is a JSON web token string
 
-`options` (optional) hash
+`options` (required) hash
 
 * **alg** (optional, default: `HS256`)
 * **key** (required unless alg is 'none')
@@ -141,5 +141,7 @@ Future implementation may include these features:
 
 [travis]: https://travis-ci.org/garyf/json_web_token
 [ci_img]: https://travis-ci.org/garyf/json_web_token.svg?branch=master
+[yard_docs]: http://www.rubydoc.info/gems/json_web_token
+[yd_img]: http://img.shields.io/badge/yard-docs-blue.svg
 [code_climate]: https://codeclimate.com/github/garyf/json_web_token
 [cc_img]: https://codeclimate.com/github/garyf/json_web_token/badges/gpa.svg

data/json_web_token.gemspec

@@ -16,6 +16,6 @@ Gem::Specification.new do |s|
   # optional
   s.add_runtime_dependency 'json', '~> 1.8', '>= 1.8.3'
   s.add_development_dependency 'rspec', '~> 3.3'
-  s.description = 'Ruby implementation of the JSON Web Token Standard Track RFC 4627'
+  s.description = 'Ruby implementation of the JSON Web Token standard, RFC 7519'
   s.required_ruby_version = '>= 2.0.0'
 end

data/lib/json_web_token.rb

@@ -5,10 +5,10 @@ module JsonWebToken
   module_function
 
   def create(claims, options = {})
-    Jwt.create(claims, options)
+    Jwt.sign(claims, options)
   end
 
   def validate(jwt, options = {})
-    Jwt.validate(jwt, options)
+    Jwt.verify(jwt, options)
   end
 end

data/lib/json_web_token/algorithm/ecdsa.rb

@@ -3,6 +3,8 @@ require 'json_web_token/format/asn1'
 
 module JsonWebToken
   module Algorithm
+    # Sign or verify a JSON Web Signature (JWS) structure using EDCSA
+    # @see http://tools.ietf.org/html/rfc7518#section-3.4
     module Ecdsa
 
       extend JsonWebToken::Algorithm::Common
@@ -16,30 +18,43 @@ module JsonWebToken
 
       module_function
 
-      def signed(sha_bits, private_key, data)
+      # @param sha_bits [String] desired security level in bits of the signature scheme
+      # @param private_key [OpenSSL::PKey::EC] key used to sign a digital signature, or mac
+      # @param signing_input [String] input payload for a mac computation
+      # @return [BinaryString] a digital signature, or mac
+      # @example
+      #   Ecdsa.sign('256', private_key, 'signing_input').bytes
+      #   # => [90, 34, 44, 252, 147, 130, 167, 173, 86, 191, 247, 93, 94, 12, 200, 30, 173, 115, 248, 89, 246, 222, 4, 213, 119, 74, 70, 20, 231, 194, 104, 103]
+      def sign(sha_bits, private_key, signing_input)
         validate_key(private_key, sha_bits)
-        der = private_key.dsa_sign_asn1(ssl_digest_hash sha_bits, data)
+        der = private_key.dsa_sign_asn1(ssl_digest_hash sha_bits, signing_input)
         der_to_signature(der, sha_bits)
       end
 
-      def verified?(signature, sha_bits, key, data)
-        validate_key(key, sha_bits)
-        validate_signature_size(signature, sha_bits)
-        der = signature_to_der(signature, sha_bits)
-        key.dsa_verify_asn1(ssl_digest_hash(sha_bits, data), der)
+      # @param mac [BinaryString] a digital signature, or mac
+      # @param sha_bits [String] desired security level in bits of the signature scheme
+      # @param public_key [OpenSSL::PKey::EC] key used to verify a digital signature, or mac
+      # @param signing_input [String] input payload for a mac computation
+      # @return [Boolean] a predicate to verify the signing_input for a given +mac+
+      # @example
+      #   Ecdsa.verify?(< binary_string >, '256', < public_key >, 'signing_input')
+      #   # => true
+      def verify?(mac, sha_bits, public_key, signing_input)
+        validate_key(public_key, sha_bits)
+        validate_signature_size(mac, sha_bits)
+        der = signature_to_der(mac, sha_bits)
+        public_key.dsa_verify_asn1(ssl_digest_hash(sha_bits, signing_input), der)
       end
 
-      # private
-
       def validate_key_size(_key, _sha_bits); end
 
-      def ssl_digest_hash(sha_bits, data)
-        digest_new(sha_bits).digest(data)
+      def ssl_digest_hash(sha_bits, signing_input)
+        digest_new(sha_bits).digest(signing_input)
       end
 
-      def validate_signature_size(signature, sha_bits)
+      def validate_signature_size(mac, sha_bits)
         n = MAC_BYTE_COUNT[sha_bits]
-        fail('Invalid signature') unless signature && signature.bytesize == n
+        fail('Invalid signature') unless mac && mac.bytesize == n
       end
 
       private_class_method :validate_key_size,

data/lib/json_web_token/algorithm/hmac.rb

@@ -3,27 +3,43 @@ require 'json_web_token/util'
 
 module JsonWebToken
   module Algorithm
+    # Sign or verify a JSON Web Signature (JWS) structure using HMAC with SHA-2 algorithms
+    # @see http://tools.ietf.org/html/rfc7518#section-3.2
     module Hmac
 
       extend JsonWebToken::Algorithm::Common
 
       module_function
 
-      def signed(sha_bits, key, data)
-        validate_key(key, sha_bits)
-        OpenSSL::HMAC.digest(digest_new(sha_bits), key, data)
+      # @param sha_bits [String] size of the hash output
+      # @param shared_key [String] secret key used to sign and verify a digital signature, or mac
+      # @param signing_input [String] input payload for a mac computation
+      # @return [BinaryString] a digital signature, or mac
+      # @example
+      #   shared_key = "gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C"
+      #   Hmac.sign('256', shared_key, 'signing_input').bytes
+      #   # => [90, 34, 44, 252, 147, 130, 167, 173, 86, 191, 247, 93, 94, 12, 200, 30, 173, 115, 248, 89, 246, 222, 4, 213, 119, 74, 70, 20, 231, 194, 104, 103]
+      def sign(sha_bits, shared_key, signing_input)
+        validate_key(shared_key, sha_bits)
+        OpenSSL::HMAC.digest(digest_new(sha_bits), shared_key, signing_input)
       end
 
-      def verified?(mac, sha_bits, key, data)
-        validate_key(key, sha_bits)
-        Util.constant_time_compare(mac, signed(sha_bits, key, data))
+      # @param mac [BinaryString] a digital signature, or mac
+      # @param (see #sign)
+      # @return [Boolean] a predicate to verify the signing_input by comparing a given +mac+
+      #   to the +mac+ for a newly signed message; comparison done in a constant-time manner
+      #   to thwart timing attacks
+      # @example
+      #   shared_key = "gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C"
+      #   Hmac.verify?(< binary_string >, '256', shared_key, 'signing_input')
+      #   # => true
+      def verify?(mac, sha_bits, shared_key, signing_input)
+        validate_key(shared_key, sha_bits)
+        Util.constant_time_compare?(mac, sign(sha_bits, shared_key, signing_input))
       end
 
-      # private
-
-      # http://tools.ietf.org/html/rfc7518#section-3.2
       def validate_key_size(key, sha_bits)
-        fail('Invalid key') unless key && key.bytesize * 8 >= sha_bits.to_i
+        fail('Invalid shared key') unless key && key.bytesize * 8 >= sha_bits.to_i
       end
 
       private_class_method :validate_key_size

data/lib/json_web_token/algorithm/rsa.rb

@@ -2,6 +2,8 @@ require 'json_web_token/algorithm/common'
 
 module JsonWebToken
   module Algorithm
+    # Sign or verify a JSON Web Signature (JWS) structure using RSASSA-PKCS-v1_5
+    # @see http://tools.ietf.org/html/rfc7518#section-3.3
     module Rsa
 
       extend JsonWebToken::Algorithm::Common
@@ -10,19 +12,29 @@ module JsonWebToken
 
       module_function
 
-      def signed(sha_bits, key, data)
-        validate_key(key, sha_bits)
-        key.sign(digest_new(sha_bits), data)
+      # @param sha_bits [String] desired security level in bits of the signature scheme
+      # @param private_key [OpenSSL::PKey::RSA] key used to sign a digital signature, or mac
+      # @param signing_input [String] input payload for a mac computation
+      # @return [BinaryString] a digital signature, or mac
+      # @example
+      #   Rsa.sign('256', < private_key >, 'signing_input').bytes.length
+      #   # => 256
+      def sign(sha_bits, private_key, signing_input)
+        validate_key(private_key, sha_bits)
+        private_key.sign(digest_new(sha_bits), signing_input)
       end
 
-      def verified?(signature, sha_bits, key, data)
-        validate_key(key, sha_bits)
-        key.verify(digest_new(sha_bits), signature, data)
+      # @param mac [BinaryString] a digital signature, or mac
+      # @param public_key [OpenSSL::PKey::RSA] key used to verify a digital signature, or mac
+      # @return [Boolean] a predicate to verify the signing_input for a given +mac+
+      # @example
+      #   Rsa.verify?(< binary_string >, '256', < public_key >, 'signing_input')
+      #   # => true
+      def verify?(mac, sha_bits, public_key, signing_input)
+        validate_key(public_key, sha_bits)
+        public_key.verify(digest_new(sha_bits), mac, signing_input)
       end
 
-      # private
-
-      # http://tools.ietf.org/html/rfc7518#section-3.3
       # https://github.com/ruby/openssl/issues/5
       def validate_key_size(key, sha_bits)
         fail('Invalid private key') unless key && key.n.num_bits >= KEY_BITS_MIN

data/lib/json_web_token/format/base64_url.rb

@@ -2,44 +2,43 @@ require 'base64'
 
 module JsonWebToken
   module Format
+    # Provide base64url encoding and decoding functions without padding, based upon standard
+    # base64 encoding and decoding functions that do use padding
+    # @see http://tools.ietf.org/html/rfc7515#appendix-C
     module Base64Url
-
       module_function
 
+      # @param str [String]
+      # @return [String] a urlsafe_encode64 string with all trailing '=' padding removed
+      # @example
+      #   Base64Url.encode('foo')
+      #   # => 'Zm9v'
       def encode(str)
-        url_safe_encode(str)
+        base64_padding_removed(Base64.urlsafe_encode64(str))
       end
 
+      # @param str [String] encoded as url_encode64
+      # @return [String] with trailing '=' padding added before decoding
+      # @example
+      #   Base64Url.decode("YmFy")
+      #   # => 'bar'
       def decode(str)
-        url_safe_decode(str)
-      end
-
-      # private
-
-      # http://tools.ietf.org/html/rfc7515#appendix-C
-      def url_safe_encode(str)
-        remove_base64_padding(Base64.urlsafe_encode64 str)
-      end
-
-      def url_safe_decode(str)
-        Base64.urlsafe_decode64(add_base64_padding str)
+        Base64.urlsafe_decode64(base64_padding_added(str))
       end
 
-      def remove_base64_padding(encoded)
+      def base64_padding_removed(encoded)
         encoded.gsub(/[=]/, '')
       end
 
-      def add_base64_padding(str)
+      def base64_padding_added(str)
         mod = str.length % 4
         return str if mod == 0
         fail('Invalid base64 string') if mod == 1
         "#{str}#{'=' * (4 - mod)}"
       end
 
-      private_class_method :url_safe_encode,
-        :url_safe_decode,
-        :remove_base64_padding,
-        :add_base64_padding
+      private_class_method :base64_padding_removed,
+        :base64_padding_added
     end
   end
 end

data/lib/json_web_token/jwa.rb

@@ -3,6 +3,8 @@ require 'json_web_token/algorithm/hmac'
 require 'json_web_token/algorithm/rsa'
 
 module JsonWebToken
+  # Choose a cryptographic algorithm to be used for a JSON Web Signature (JWS)
+  # @see http://tools.ietf.org/html/rfc7518
   module Jwa
 
     ALGORITHMS = /(HS|RS|ES)(256|384|512)?/i
@@ -10,18 +12,34 @@ module JsonWebToken
 
     module_function
 
-    def signed(algorithm, key, data)
-      alg = validated_alg(algorithm)
-      alg[:constant].signed(alg[:sha_bits], key, data)
+    # @param algorithm [String] 'alg' header parameter value for JWS
+    # @param key [String | OpenSSL::PKey::RSA | OpenSSL::PKey::EC] secret key used to sign
+    #   a digital signature, or mac
+    # @param signing_input [String] input payload for a mac computation
+    # @return [BinaryString] a digital signature, or mac
+    # @example
+    #   key = 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C'
+    #   Jwa.sign('HS256', key, 'signing_input').bytes
+    #   # => [90, 34, 44, 252, 147, 130, 167, 173, 86, 191, 247, 93, 94, 12, 200, 30, 173, 115, 248, 89, 246, 222, 4, 213, 119, 74, 70, 20, 231, 194, 104, 103]
+    def sign(algorithm, key, signing_input)
+      alg_module, sha_bits = validated_alg(algorithm)
+      alg_module.sign(sha_bits, key, signing_input)
     end
 
-    def verified?(signature, algorithm, key, data)
-      alg = validated_alg(algorithm)
-      alg[:constant].verified?(signature, alg[:sha_bits], key, data)
+    # @param mac [BinaryString] a digital signature, or mac
+    # @param algorithm [String] 'alg' header parameter value for JWS
+    # @param key [String | OpenSSL::PKey::RSA | OpenSSL::PKey::EC] key used to verify
+    #   a digital signature, or mac
+    # @param signing_input [String] input payload for a mac computation
+    # @example
+    #   key = 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C'
+    #   Jwa.verify?(< binary_string >, 'HS256', key, 'signing_input')
+    #   # => true
+    def verify?(mac, algorithm, key, signing_input)
+      alg_module, sha_bits = validated_alg(algorithm)
+      alg_module.verify?(mac, sha_bits, key, signing_input)
     end
 
-    # private
-
     def validated_alg(algorithm)
       alg = destructured_alg(algorithm)
       alg ? alg : fail('Unrecognized algorithm')
@@ -30,10 +48,9 @@ module JsonWebToken
     def destructured_alg(algorithm)
       match = algorithm.match(ALGORITHMS)
       return unless match && match[0].length == ALG_LENGTH
-      {
-        constant: validated_constant(match[1].downcase),
-        sha_bits: match[2],
-      }
+      alg_module = validated_constant(match[1].downcase)
+      sha_bits = match[2]
+      [alg_module, sha_bits]
     end
 
     def validated_constant(str)
@@ -46,7 +63,7 @@ module JsonWebToken
     end
 
     private_class_method :validated_alg,
-      :destructured_alg
+      :destructured_alg,
       :validated_constant
   end
 end

data/lib/json_web_token/jws.rb

@@ -4,45 +4,72 @@ require 'json_web_token/jwa'
 require 'json_web_token/util'
 
 module JsonWebToken
+  # Represent content to be secured with digital signatures or Message Authentication Codes (MACs)
+  # @see http://tools.ietf.org/html/rfc7515
   module Jws
 
     MESSAGE_SIGNATURE_PARTS = 3
 
     module_function
 
-    # http://tools.ietf.org/html/rfc7515#page-15
-    def message_signature(header, payload, key)
+    # @param header [Hash] the desired set of JWS header parameters
+    # @param payload [String] content to be used as the JWS payload
+    # @param key [String | OpenSSL::PKey::RSA | OpenSSL::PKey::EC] secret key used to sign
+    #   a digital signature, or mac
+    # @return [String] a JSON Web Signature, representing a digitally signed payload
+    # @example
+    #   header = {alg: 'HS256'}
+    #   key = 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C'
+    #   Jws.sign(header, 'payload', key)
+    #   # => 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'
+    # @see http://tools.ietf.org/html/rfc7515#page-15
+    def sign(header, payload, key)
       alg = alg_parameter(header)
-      data = signing_input(header, payload)
-      "#{data}.#{signature(alg, key, data)}"
+      signing_input = encode_input(header, payload)
+      "#{signing_input}.#{signature(alg, key, signing_input)}"
     end
 
-    # http://tools.ietf.org/html/rfc7515#page-16
-    def validate(jws, algorithm, key = nil)
-      compare_alg(jws, algorithm)
-      return jws if algorithm == 'none'
-      signature_valid?(jws, algorithm, key) ? jws : 'Invalid'
-    end
-
-    # http://tools.ietf.org/html/rfc7515#page-47
-    def unsecured_jws(header, payload)
+    # @param header [Hash] the desired set of JWS header parameters
+    # @param payload [String] content to be used as the JWS payload
+    # @return [String] a JWS that provides no integrity protection (i.e. lacks a signature)
+    # @example
+    #   header = {alg: 'none'}
+    #   Jws.sign(header, 'payload')
+    #   # => 'eyJhbGciOiJub25lIn0.cGF5bG9hZA.'
+    # @see http://tools.ietf.org/html/rfc7515#page-47
+    def unsecured_message(header, payload)
       fail("Invalid 'alg' header parameter") unless alg_parameter(header) == 'none'
-      "#{signing_input(header, payload)}." # note trailing '.'
+      "#{encode_input(header, payload)}." # note trailing '.'
     end
 
-    # private
+    # @param jws [String] a JSON Web Signature
+    # @param algorithm [String] 'alg' header parameter value for JWS
+    # @param key [String | OpenSSL::PKey::RSA | OpenSSL::PKey::EC] key used to verify
+    #   a digital signature, or mac
+    # @return [String | Boolean] a JWS if the mac verifies, or +false+ otherwise
+    # @example
+    #   jws = 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'
+    #   key = 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C'
+    #   Jws.verify(jws, 'HS256', key)
+    #   # => 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'
+    # @see http://tools.ietf.org/html/rfc7515#page-16
+    def verify(jws, algorithm, key = nil)
+      compare_alg(jws, algorithm)
+      return jws if algorithm == 'none'
+      signature_verify?(jws, algorithm, key) ? jws : false
+    end
 
     def alg_parameter(header)
       alg = Util.symbolize_keys(header)[:alg]
       alg && !alg.empty? ? alg : fail("Missing required 'alg' header parameter")
     end
 
-    def signing_input(header, payload)
-      "#{Format::Base64Url.encode header.to_json}.#{Format::Base64Url.encode payload}"
+    def encode_input(header, payload)
+      "#{Format::Base64Url.encode(header.to_json)}.#{Format::Base64Url.encode(payload)}"
     end
 
     def signature(algorithm, key, data)
-      Format::Base64Url.encode(Jwa.signed algorithm, key, data)
+      Format::Base64Url.encode(Jwa.sign(algorithm, key, data))
     end
 
     # http://tools.ietf.org/html/rfc7515#section-4.1.1
@@ -54,22 +81,22 @@ module JsonWebToken
     end
 
     def decoded_header_json_to_hash(jws)
-      JSON.parse(Format::Base64Url.decode jws.split('.')[0])
+      JSON.parse(Format::Base64Url.decode(jws.split('.')[0]))
     end
 
-    def signature_valid?(jws, algorithm, key)
+    def signature_verify?(jws, algorithm, key)
       ary = jws.split('.')
       return unless key && ary.length == MESSAGE_SIGNATURE_PARTS
       decoded_signature = Format::Base64Url.decode(ary[2])
       payload = "#{ary[0]}.#{ary[1]}"
-      Jwa.verified?(decoded_signature, algorithm, key, payload)
+      Jwa.verify?(decoded_signature, algorithm, key, payload)
     end
 
     private_class_method :alg_parameter,
-      :signing_input,
+      :encode_input,
       :signature,
       :compare_alg,
       :decoded_header_json_to_hash,
-      :signature_valid?
+      :signature_verify?
   end
 end