json_web_token 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 973c4dc365edec01a991491309d0332b3898dd57
-  data.tar.gz: 05d71d73011230c2b2f074eed6d2ea86bf0be1cf
+  metadata.gz: a1bab6670404e2a3185dabc1944f130891cb6de6
+  data.tar.gz: 142fb6257f61b6c906e29519af046289ba085508
 SHA512:
-  metadata.gz: 640c8738d52377295275bc4c5498b02a7fd427ffdf2b8d14b5765acc90fd8868c401799f0ccbb0535d37143ee90138ff5f80621edee6c902344106a5f1727786
-  data.tar.gz: fa2e818be12da6b351eb202b4ca2de9ab0efdd48f789d1e61e2e3683ae7fa9f50026e716d69578eb2c850266f72b5cc6bac4c94d570148cd4194d06ceb67b49f
+  metadata.gz: 263eb8d5f5855937117026134f7dce4f76c37c48a3c0ef955d4c21d47e41395793cc3c55bea20de613f56c1808cc6ae55af919d16bfae214a81b1a8ec9f1d840
+  data.tar.gz: 29073ba554234ce1581d0608e29e17e12885c962ecbda6f402564c7bc85aa18669c9a47039bd817ce09e42e6def463623fd97f554bccff2b76049f610af85bd5

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Changelog
 
+### v0.2.0 (2015-08-02)
+
+* backward incompatible changes
+  * Top level API now #sign and #verify
+
 ### v0.1.2 (2015-08-02)
 
 * enhancements

data/README.md

@@ -1,9 +1,9 @@
 # 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
+## A JSON Web Token (JWT) implementation for Ruby
 
 ### Description
-A Ruby implementation of the JSON Web Token (JWT) Standards Track [RFC 7519][rfc7519]
+A Ruby implementation of the JSON Web Token standard [RFC 7519][rfc7519]
 
 ## Installation
     gem install json_web_token
@@ -30,7 +30,7 @@ Secure Cross-Origin Resource Sharing ([CORS][cors]) using the [rack-cors][rack-c
 
 ## Usage
 
-### JsonWebToken.create(claims, options)
+### JsonWebToken.sign(claims, options)
 
 Returns a JSON Web Token string
 
@@ -47,7 +47,7 @@ Example
 require 'json_web_token'
 
 # sign with default algorithm, HMAC SHA256
-jwt = JsonWebToken.create({foo: 'bar'}, key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C')
+jwt = JsonWebToken.sign({foo: 'bar'}, key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C')
 
 # sign with RSA SHA256 algorithm
 opts = {
@@ -55,14 +55,14 @@ opts = {
   key: < RSA private key >
 }
 
-jwt = JsonWebToken.create({foo: 'bar'}, opts)
+jwt = JsonWebToken.sign({foo: 'bar'}, opts)
 
 # unsecured token (algorithm is 'none')
-jwt = JsonWebToken.create({foo: 'bar'}, alg: 'none')
+jwt = JsonWebToken.sign({foo: 'bar'}, alg: 'none')
 
 ```
 
-### JsonWebToken.validate(jwt, options)
+### JsonWebToken.verify(jwt, options)
 
 Returns either:
 * a JWT claims set string or hash, if the Message Authentication Code (MAC), or signature, is verified
@@ -83,7 +83,7 @@ require 'json_web_token'
 secure_jwt_example = 'eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt.cGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
 
 # verify with default algorithm, HMAC SHA256
-claims = JsonWebToken.validate(secure_jwt_example, key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C')
+claims = JsonWebToken.verify(secure_jwt_example, key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C')
 
 # verify with RSA SHA256 algorithm
 opts = {
@@ -91,12 +91,12 @@ opts = {
   key: < RSA public key >
 }
 
-claims = JsonWebToken.validate(jwt, opts)
+claims = JsonWebToken.verify(jwt, opts)
 
 # unsecured token (algorithm is 'none')
 unsecured_jwt_example = 'eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt.'
 
-claims = JsonWebToken.validate(unsecured_jwt_example, alg: 'none')
+claims = JsonWebToken.verify(unsecured_jwt_example, alg: 'none')
 
 ```
 ### Supported encryption algorithms
@@ -115,7 +115,7 @@ ES512 | ECDSA using P-521 and SHA-512
 none | No digital signature or MAC performed (unsecured)
 
 ### Supported Ruby Versions
-Ruby 2.0 and up
+Ruby 2.0.0 and up
 
 ### Limitations
 Future implementation may include these features:
@@ -141,7 +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
+[yard_docs]: http://www.rubydoc.info/github/garyf/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, RFC 7519'
+  s.description = 'Ruby implementation of the JSON Web Token (JWT) standard, RFC 7519'
   s.required_ruby_version = '>= 2.0.0'
 end

data/lib/json_web_token.rb

@@ -1,14 +1,35 @@
 require 'json_web_token/jwt'
 
+# Top level interface, or API, to sign and verify a JSON Web Token (JWT)
+# @see http://tools.ietf.org/html/rfc7519
 module JsonWebToken
 
   module_function
 
-  def create(claims, options = {})
+  # @param claims [Hash] a collection of name/value pairs asserting information about a subject
+  # @param options [Hash] specify the desired signing algorithm and signing key
+  # @return [String] a JSON Web Token, representing digitally signed claims
+  # @example
+  #   claims = {iss: 'joe', exp: 1300819380, :'http://example.com/is_root' => true}
+  #   options = {alg: 'HS256', key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C'}
+  #   JsonWebToken.sign(claims, options)
+  #   # => 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'
+  def sign(claims, options)
     Jwt.sign(claims, options)
   end
-
-  def validate(jwt, options = {})
+  
+  # @param jwt [String] a JSON Web Token
+  # @param options [Hash] specify the desired verifying algorithm and verifying key
+  # @return [Hash] a JWT claims set if the jwt verifies, or +error: 'Invalid'+ otherwise
+  # @example
+  #   jwt = 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'
+  #   options = {alg: 'HS256', key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C'}
+  #   JsonWebToken.verify(jwt, options)
+  #   # => {iss: 'joe', exp: 1300819380, :'http://example.com/is_root' => true}
+  def verify(jwt, options)
     Jwt.verify(jwt, options)
   end
 end
+
+# alias
+JWT = JsonWebToken

data/lib/json_web_token/format/asn1.rb

@@ -2,6 +2,12 @@ require 'openssl'
 
 module JsonWebToken
   module Format
+    # ASN1 data structures are usually encoded using the Distinguished Encoding Rules (DER).
+    # The ASN1 module provides the necessary classes that allow generation of ASN1 data
+    # structures and the methods to encode them using a DER encoding. The decode method allows
+    # parsing arbitrary DER-encoded data to a Ruby object that can then be modified and
+    # re-encoded at will.
+    # @see http://docs.ruby-lang.org/en/2.1.0/OpenSSL/ASN1.html
     module Asn1
 
       KEY_BITS = {
@@ -12,12 +18,6 @@ module JsonWebToken
 
       module_function
 
-      # ASN1 data structures are usually encoded using the Distinguished Encoding Rules (DER).
-      # The ASN1 module provides the necessary classes that allow generation of ASN1 data
-      # structures and the methods to encode them using a DER encoding. The decode method allows
-      # parsing arbitrary DER-encoded data to a Ruby object that can then be modified and
-      # re-encoded at will. (see http://docs.ruby-lang.org/en/2.1.0/OpenSSL/ASN1.html)
-
       def der_to_signature(der, sha_bits)
         signature_pair = OpenSSL::ASN1.decode(der).value
         width = per_part_byte_count(sha_bits)
@@ -33,8 +33,6 @@ module JsonWebToken
         asn1_seq.to_der
       end
 
-      # private
-
       def per_part_byte_count(sha_bits)
         bits = KEY_BITS[sha_bits]
         bits ? (bits + 7) / 8 : fail('Invalid sha_bits')

data/lib/json_web_token/jwt.rb

@@ -4,6 +4,7 @@ module JsonWebToken
   # Encode claims for transmission as a JSON object that is used as the payload of a JSON Web
   # Signature (JWS) structure, enabling the claims to be integrity protected with a Message
   # Authentication Code (MAC), to be later verified
+  # @see http://tools.ietf.org/html/rfc7519
   module Jwt
 
     ALG_DEFAULT = 'HS256'
@@ -19,12 +20,12 @@ module JsonWebToken
     #   (e.g String for Hmac | OpenSSL::PKey::RSA | OpenSSL::PKey::EC)
     # @return [String] a JSON Web Token, representing digitally signed claims
     # @example
-    #   claims = {iss: 'joe', exp: 1300819380, 'http://example.com/is_root' => true}
+    #   claims = {iss: 'joe', exp: 1300819380, :'http://example.com/is_root' => true}
     #   options = {alg: 'HS256', key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C'}
     #   Jwt.sign(claims, options)
     #   # => 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'
     # @see http://tools.ietf.org/html/rfc7519#section-7.1
-    def sign(claims, options = {})
+    def sign(claims, options)
       message = validated_message(claims)
       header = config_header(options)
       return Jws.unsecured_message(header, message) if header[:alg] == 'none'
@@ -33,14 +34,14 @@ module JsonWebToken
 
     # @param jwt [String] a JSON Web Token
     # @param options [Hash] specify the desired verifying algorithm and verifying key
-    # @return [Hash] a JWT claims set if the jwt verifies, or +{error: 'Invalid'}+ otherwise
+    # @return [Hash] a JWT claims set if the jwt verifies, or +error: 'Invalid'+ otherwise
     # @example
     #   jwt = 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'
     #   options = {alg: 'HS256', key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C'}
     #   Jwt.verify(jwt, options)
-    #   # => {iss: 'joe', exp: 1300819380, 'http://example.com/is_root' => true}
+    #   # => {iss: 'joe', exp: 1300819380, :'http://example.com/is_root' => true}
     # @see see http://tools.ietf.org/html/rfc7519#section-7.2
-    def verify(jwt, options = {})
+    def verify(jwt, options)
       alg = options[:alg] || ALG_DEFAULT
       jws = Jws.verify(jwt, alg, options[:key])
       jws ? Util.symbolize_keys(decoded_message_json_to_hash jws) : {error: 'invalid'}

data/lib/json_web_token/util.rb

@@ -1,22 +1,34 @@
 module JsonWebToken
+  # Utility methods
   module Util
 
     module_function
 
-    # https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40#section-3.2
+    # @param a [String]
+    # @param b [String]
+    # @return [Boolean] a predicate that compares two strings for equality in constant-time
+    #   to avoid timing attacks
+    # @example
+    #   Util.constant_time_compare?("a", "A")
+    #   # => false
+    # @see https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40#section-3.2
+    # @see cf. rails activesupport/lib/active_support/security_utils.rb
     def constant_time_compare?(a, b)
       return false if a.nil? || b.nil? || a.empty? || b.empty?
       secure_compare(a, b)
     end
 
-    # cf. rails activesupport/lib/active_support/core_ext/hash/keys.rb
+    # @param hsh [Hash]
+    # @return [Hash] a new hash with all keys converted to symbols,
+    #   as long as they respond to to_sym
+    # @example
+    #   Util.symbolize_keys({'a' =>  0, 'b' => '2', c: '3'})
+    #   # => {a: 0, b: '2', c: '3'}
+    # @see cf. rails activesupport/lib/active_support/core_ext/hash/keys.rb
     def symbolize_keys(hsh)
       transform_keys(hsh) { |key| key.to_sym rescue key }
     end
 
-    # private
-
-    # cf. rails activesupport/lib/active_support/security_utils.rb
     def secure_compare(a, b)
       return false unless a.bytesize == b.bytesize
       l = a.unpack "C#{a.bytesize}"

data/lib/json_web_token/version.rb

@@ -1,3 +1,3 @@
 module JsonWebToken
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/spec/json_web_token/jwt_spec.rb

@@ -20,7 +20,7 @@ module JsonWebToken
       end
 
       context 'w claims' do
-        let(:claims) { { iss: 'joe', exp: 1300819380, 'http://example.com/is_root': true} }
+        let(:claims) { { iss: 'joe', exp: 1300819380, :'http://example.com/is_root' => true} }
         context 'w HS256 keys' do
           let(:signing_key) { 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C' }
           let(:verifying_key) { signing_key }
@@ -118,7 +118,7 @@ module JsonWebToken
             describe 'w default verify alg' do
               it 'raises' do
                 jwt = Jwt.sign(claims, sign_options)
-                expect { Jwt.verify(jwt) }
+                expect { Jwt.verify(jwt, {alg: nil}) }
                   .to raise_error(RuntimeError, "Algorithm not matching 'alg' header parameter")
               end
             end

data/spec/json_web_token_spec.rb

@@ -1,12 +1,12 @@
 require 'json_web_token'
 
 describe JsonWebToken do
-  context '#create' do
-    let(:claims) { {exp: 'tomorrow'} }
-    shared_examples_for 'w #validate' do
-      it 'is verified' do
-        jwt = JsonWebToken.create(claims, create_options)
-        expect(JsonWebToken.validate jwt, validate_options).to include(claims)
+  context '#sign' do
+    let(:claims) { { iss: 'joe', exp: 1300819380, :'http://example.com/is_root' => true} }
+    shared_examples_for 'w #verify' do
+      it 'w a claims set' do
+        jwt = JsonWebToken.sign(claims, sign_options)
+        expect(JsonWebToken.verify jwt, verify_options).to include(claims)
       end
     end
 
@@ -15,29 +15,38 @@ describe JsonWebToken do
       let(:verifying_key) { signing_key }
 
       describe 'default alg' do
-        let(:create_options) { {key: signing_key} }
-        let(:validate_options) { {key: verifying_key} }
-        it_behaves_like 'w #validate'
+        let(:sign_options) { {key: signing_key} }
+        let(:verify_options) { {key: verifying_key} }
+        it_behaves_like 'w #verify'
       end
 
       context "w 'alg' option" do
         describe 'HS256' do
-          let(:create_options) { {alg: 'HS256', key: signing_key} }
-          let(:validate_options) { {alg: 'HS256', key: verifying_key} }
-          it_behaves_like 'w #validate'
+          let(:sign_options) { {alg: 'HS256', key: signing_key} }
+          let(:verify_options) { {alg: 'HS256', key: verifying_key} }
+          it_behaves_like 'w #verify'
         end
 
         describe "w alg 'none'" do
-          let(:create_options) { {alg: 'none', key: signing_key} }
-          let(:validate_options) { {alg: 'none', key: verifying_key} }
-          it_behaves_like 'w #validate'
+          let(:sign_options) { {alg: 'none', key: signing_key} }
+          let(:verify_options) { {alg: 'none', key: verifying_key} }
+          it_behaves_like 'w #verify'
         end
       end
     end
 
     describe 'w/o key w default header alg' do
       it 'raises' do
-        expect { JsonWebToken.create(claims) }.to raise_error(RuntimeError, 'Invalid shared key')
+        expect { JsonWebToken.sign(claims, {}) }.to raise_error(RuntimeError, 'Invalid shared key')
+      end
+    end
+  end
+
+  context 'module alias JWT' do
+    describe '#sign' do
+      let(:claims) { { iss: 'joe', exp: 1300819380, :'http://example.com/is_root' => true} }
+      it 'recognized' do
+        expect(JsonWebToken.sign(claims, key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C')).to be
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json_web_token
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Gary Fleshman
@@ -14,45 +14,45 @@ dependencies:
   name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.8'
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 1.8.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.8'
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 1.8.3
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '3.3'
-description: Ruby implementation of the JSON Web Token standard, RFC 7519
+description: Ruby implementation of the JSON Web Token (JWT) standard, RFC 7519
 email: gfleshman@newforge-tech.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rspec"
-- ".travis.yml"
+- .gitignore
+- .rspec
+- .travis.yml
 - CHANGELOG.md
 - Gemfile
 - LICENSE
@@ -93,12 +93,12 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []