sandal 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 03610644805fbd043ba5d03d61a1d5926b45d37f
-  data.tar.gz: 9622863e1097e93f74740cd112ae2dd4d98a8fd7
+  metadata.gz: 5ea79b1b4960ee68f883439155f86e455f840297
+  data.tar.gz: 88fe766c7e0dd6f42ffe8cc9e362bd4f9d4dcf1c
 SHA512:
-  metadata.gz: ff2c734b2f07a064bad1701e26d976db390d9ebe2e666c41f066d80948486f7b16dca0ff189ba6772826dae589da2390195695fe3fa187e03b11cfc398325094
-  data.tar.gz: 77ea15a46b9170678cc34382f690e283ee0b1ec448b7e1caa29edfdfe053e5b41ee9615278687dd711c90bfd4828b0922714a6acd1ecce5e98ee27dd518c41a8
+  metadata.gz: 8caf814bd10d413690942fde42d319a9b1d65afcef90c3ebf19f27f35b731e2d48c4d4225fb0700a60c9841c98ea46a6e34c610b40d93cf5584c605b6144621a
+  data.tar.gz: 978832491980e5e85b83bdac17e4c615cddc01594600785db0e7b7a621d459b7955003ab0352dac65ba803ded8890780cb609895528a6f35f60e107938dc8be6

data/.travis.yml

@@ -2,6 +2,5 @@ language: ruby
 rvm:
   - rbx-19mode
   - jruby-19mode
-  - 1.9.2
   - 1.9.3
   - 2.0.0

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 0.5.0 (07 June 2013)
+
+Features:
+
+- Updated to JWT draft-08 specification, and corresponding JWE, JWS and JWA drafts.
+- Added a KeyError class for when invalid keys are given to the library.
+- Added an ExpiredTokenError class to make handling the common case of expired tokens easier.
+- Added a NAME constant to all classes with a JWA name to save user having to hard-code the name string.
+
+Breaking changes:
+
+- Tokens are not backwards compatible with previous versions of the library due to changes in the specification.
+- Dropped support for Ruby 1.9.2; supported platforms are now 1.9.3, 2.0.0, JRuby (head) and Rubinius (head).
+
 ## 0.4.0 (30 April 2013)
 
 Features:

data/README.md

@@ -1,6 +1,6 @@
 # Sandal [![Build Status](https://travis-ci.org/gregbeech/sandal.png?branch=master)](https://travis-ci.org/gregbeech/sandal) [![Coverage Status](https://coveralls.io/repos/gregbeech/sandal/badge.png?branch=master)](https://coveralls.io/r/gregbeech/sandal) [![Code Climate](https://codeclimate.com/github/gregbeech/sandal.png)](https://codeclimate.com/github/gregbeech/sandal) [![Dependency Status](https://gemnasium.com/gregbeech/sandal.png)](https://gemnasium.com/gregbeech/sandal)
 
-A Ruby library for creating and reading [JSON Web Tokens (JWT) draft-06](http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-06), supporting [JSON Web Signatures (JWS) draft-08](http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-08) and [JSON Web Encryption (JWE) draft-08](http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-08). See the [CHANGELOG](CHANGELOG.md) for version history.
+A Ruby library for creating and reading [JSON Web Tokens (JWT) draft-08](http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-08), supporting [JSON Web Signatures (JWS) draft-11](http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-11) and [JSON Web Encryption (JWE) draft-11](http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-11). See the [CHANGELOG](CHANGELOG.md) for version history.
 
 ## Installation
 

data/lib/sandal.rb

@@ -1,48 +1,60 @@
-require 'multi_json'
-require 'openssl'
-require 'zlib'
-require 'sandal/version'
-require 'sandal/claims'
-require 'sandal/enc'
-require 'sandal/sig'
-require 'sandal/util'
-
-
-# A library for creating and reading JSON Web Tokens (JWT), supporting JSON Web 
-# Signatures (JWS) and JSON Web Encryption (JWE).
+require "multi_json"
+require "openssl"
+require "zlib"
+require "sandal/version"
+require "sandal/claims"
+require "sandal/enc"
+require "sandal/sig"
+require "sandal/util"
+
+
+# A library for creating and reading JSON Web Tokens (JWT), supporting JSON Web Signatures (JWS) and JSON Web Encryption
+# (JWE).
 #
-# Currently supports draft-06 of the JWT spec, and draft-08 of the JWS and JWE 
-# specs.
+# Currently supports draft-07 of the JWT spec, and draft-10 of the JWS and JWE specs.
 module Sandal
   extend Sandal::Util
 
+  # The base error for all errors raised by this library.
+  class Error < StandardError; end
+
+  # The error that is raised when a key provided for signing/encryption/etc. is invalid.
+  class KeyError < Error; end
+
+  # The error that is raised when there is a problem with a token.
+  class TokenError < Error; end
+
   # The error that is raised when a token is invalid.
-  class TokenError < StandardError; end
+  class InvalidTokenError < TokenError; end
 
   # The error that is raised when a claim within a token is invalid.
-  class ClaimError < TokenError; end
+  class ClaimError < InvalidTokenError; end
+
+  # The error that is raised when the token has expired.
+  class ExpiredTokenError < ClaimError; end
+
+  # The error that is raised when a token is unsupported (e.g. the algorithm used to encrypt the token is not supported 
+  # by this library or by the Ruby platform it is executing on).
+  class UnsupportedTokenError < TokenError; end
 
   # The default options for token handling.
   #
   # ignore_exp:: 
-  #   Whether to ignore the expiry date of the token. This setting is just to
-  #   help get things working and should always be false in real apps!
+  #   Whether to ignore the expiry date of the token. This setting is just to help get things working and should always
+  #   be false in real apps!
   # ignore_nbf:: 
-  #   Whether to ignore the not-before date of the token. This setting is just 
-  #   to help get things working and should always be false in real apps!
+  #   Whether to ignore the not-before date of the token. This setting is just to help get things working and should
+  #   always be false in real apps!
   # ignore_signature:: 
-  #   Whether to ignore the signature of signed (JWS) tokens.  This setting is 
-  #   just tohelp get things working and should always be false in real apps!
+  #   Whether to ignore the signature of signed (JWS) tokens.  This setting is just tohelp get things working and should
+  #   always be false in real apps!
   # max_clock_skew:: 
-  #   The maximum clock skew, in seconds, when validating times. If your server
-  #   time is out of sync with the token server then this can be increased to
-  #   take that into account. It probably shouldn't be more than about 300.
+  #   The maximum clock skew, in seconds, when validating times. If your server time is out of sync with the token
+  #   server then this can be increased to take that into account. It probably shouldn't be more than about 300.
   # valid_iss:: 
-  #   A list of valid token issuers, if validation of the issuer claim is 
-  #   required.
+  #   A list of valid token issuers, if validation of the issuer claim is required.
   # valid_aud:: 
-  #   A list of valid audiences, if validation of the audience claim is
-  #   required.
+  #   A list of valid audiences, if validation of the audience claim is required.
   DEFAULT_OPTIONS = {
     ignore_exp: false,
     ignore_nbf: false,
@@ -54,8 +66,7 @@ module Sandal
 
   # Overrides the default options.
   #
-  # @param defaults [Hash] The options to override (see {DEFAULT_OPTIONS} for
-  #   details).
+  # @param defaults [Hash] The options to override (see {DEFAULT_OPTIONS} for details).
   # @return [Hash] The new default options.
   def self.default!(defaults)
     DEFAULT_OPTIONS.merge!(defaults)
@@ -67,7 +78,7 @@ module Sandal
   # @return [Boolean] true if the token is encrypted; otherwise false.
   def self.is_encrypted?(token)
     if token.is_a?(String)
-      token.count('.') == 4
+      token.count(".") == 4
     else
       token.count == 5
     end
@@ -79,7 +90,7 @@ module Sandal
   # @return [Boolean] true if the token is signed; otherwise false.
   def self.is_signed?(token)
     if token.is_a?(String)
-      !token.end_with?('.') && token.count('.') == 2
+      !token.end_with?(".") && token.count(".") == 2
     else
       token.count == 3 && !token[2].nil? && !token[2].empty?
     end
@@ -87,75 +98,65 @@ module Sandal
 
   # Creates a signed JSON Web Token.
   #
-  # @param payload [String or Hash] The payload of the token. Hashes will be 
-  #   encoded as JSON.
-  # @param signer [#name,#sign] The token signer, which may be nil for an 
-  #   unsigned token.
-  # @param header_fields [Hash] Header fields for the token (note: do not
-  #   include 'alg').
+  # @param payload [String or Hash] The payload of the token. Hashes will be encoded as JSON.
+  # @param signer [#name,#sign] The token signer, which may be nil for an unsigned token.
+  # @param header_fields [Hash] Header fields for the token (note: do not include "alg").
   # @return [String] A signed JSON Web Token.
   def self.encode_token(payload, signer, header_fields = nil)
     signer ||= Sandal::Sig::NONE
 
     header = {}
-    header['alg'] = signer.name
+    header["alg"] = signer.name
     header = header_fields.merge(header) if header_fields
     header = MultiJson.dump(header)
 
     payload = MultiJson.dump(payload) unless payload.is_a?(String)
 
-    sec_input = [header, payload].map { |p| jwt_base64_encode(p) }.join('.')
+    sec_input = [header, payload].map { |p| jwt_base64_encode(p) }.join(".")
     signature = signer.sign(sec_input)
-    [sec_input, jwt_base64_encode(signature)].join('.')
+    [sec_input, jwt_base64_encode(signature)].join(".")
   end
 
   # Creates an encrypted JSON Web Token.
   #
   # @param payload [String] The payload of the token.
   # @param encrypter [#name,#alg,#encrypt] The token encrypter.
-  # @param header_fields [Hash] Header fields for the token (note: do not
-  #   include 'alg' or 'enc').
+  # @param header_fields [Hash] Header fields for the token (note: do not include "alg" or "enc").
   # @return [String] An encrypted JSON Web Token.
   def self.encrypt_token(payload, encrypter, header_fields = nil)
     header = {}
-    header['enc'] = encrypter.name
-    header['alg'] = encrypter.alg.name
+    header["enc"] = encrypter.name
+    header["alg"] = encrypter.alg.name
     header = header_fields.merge(header) if header_fields
 
-    if header.has_key?('zip')
-      unless header['zip'] == 'DEF'
-        raise ArgumentError, 'Invalid zip algorithm.'
+    if header.has_key?("zip")
+      unless header["zip"] == "DEF"
+        raise ArgumentError, "Invalid zip algorithm."
       end
       payload = Zlib::Deflate.deflate(payload, Zlib::BEST_COMPRESSION)
     end 
 
-    encrypter.encrypt(header, payload)
+    encrypter.encrypt(MultiJson.dump(header), payload)
   end
 
-  # Decodes and validates a signed and/or encrypted JSON Web Token, recursing
-  # into any nested tokens, and returns the payload.
+  # Decodes and validates a signed and/or encrypted JSON Web Token, recursing into any nested tokens, and returns the 
+  # payload.
   #
-  # The block is called with the token header as the first parameter, and should
-  # return the appropriate signature or decryption method to either validate the
-  # signature or decrypt the token as applicable. When the tokens are nested, 
-  # this block will be called once per token. It can optionally have a second 
-  # options parameter which can be used to override the {DEFAULT_OPTIONS} on a 
-  # per-token basis; options are not persisted between yields.
+  # The block is called with the token header as the first parameter, and should return the appropriate signature or
+  # decryption method to either validate the signature or decrypt the token as applicable. When the tokens are nested, 
+  # this block will be called once per token. It can optionally have a second options parameter which can be used to
+  # override the {DEFAULT_OPTIONS} on a per-token basis; options are not persisted between yields.
   #
   # @param token [String] The encoded JSON Web Token.
   # @param depth [Integer] The maximum depth of token nesting to decode to.
   # @yieldparam header [Hash] The JWT header values.
-  # @yieldparam options [Hash] (Optional) A hash that can be used to override 
-  #   the default options.
-  # @yieldreturn [#valid? or #decrypt] The signature validator if the token is
-  #   signed, or the token decrypter if the token is encrypted.
-  # @return [Hash or String] The payload of the token as a Hash if it was JSON, 
-  #   otherwise as a String.
-  # @raise [Sandal::ClaimError] One or more claims in the token is invalid.
-  # @raise [Sandal::TokenError] The token format is invalid, or validation of 
-  #   the token failed.
+  # @yieldparam options [Hash] (Optional) A hash that can be used to override the default options.
+  # @yieldreturn [#valid? or #decrypt] The signature validator if the token is signed, or the token decrypter if the
+  #   token is encrypted.
+  # @return [Hash or String] The payload of the token as a Hash if it was JSON, otherwise as a String.
+  # @raise [Sandal::TokenError] The token is invalid or not supported.
   def self.decode_token(token, depth = 16)
-    parts = token.split('.')
+    parts = token.split(".")
     decoded_parts = decode_token_parts(parts)
     header = decoded_parts[0]
 
@@ -163,10 +164,10 @@ module Sandal
     decoder = yield header, options if block_given?
 
     if is_encrypted?(parts)
-      payload = decoder.decrypt(parts, decoded_parts)
-      if header.has_key?('zip')
-        unless header['zip'] == 'DEF'
-          raise Sandal::TokenError, 'Invalid zip algorithm.'
+      payload = decoder.decrypt(parts)
+      if header.has_key?("zip")
+        unless header["zip"] == "DEF"
+          raise Sandal::InvalidTokenError, "Invalid zip algorithm."
         end
         payload = Zlib::Inflate.inflate(payload)
       end
@@ -177,7 +178,7 @@ module Sandal
       end
     end
 
-    if header['cty'] == 'JWT'
+    if header["cty"] == "JWT"
       if depth > 0
         if block_given?
           decode_token(payload, depth - 1, &Proc.new)
@@ -197,9 +198,9 @@ module Sandal
   # Decodes and validates a signed JSON Web Token.
   def self.validate_signature(parts, signature, validator)
     validator ||= Sandal::Sig::NONE
-    secured_input = parts.take(2).join('.')
+    secured_input = parts.take(2).join(".")
     unless validator.valid?(signature, secured_input)
-      raise TokenError, 'Invalid signature.'
+      raise TokenError, "Invalid signature."
     end
   end
 
@@ -209,7 +210,7 @@ module Sandal
     parts[0] = MultiJson.load(parts[0])
     parts
   rescue
-    raise TokenError, 'Invalid token encoding.'
+    raise TokenError, "Invalid token encoding."
   end
 
   # Parses the content of a token and validates the claims if is JSON claims.

data/lib/sandal/claims.rb

@@ -21,14 +21,14 @@ module Sandal
     #
     # @param max_clock_skew [Numeric] The maximum clock skew, in seconds.
     # @return [void].
-    # @raise [Sandal::ClaimError] The 'exp' claim is invalid, or the token has 
+    # @raise [Sandal::ClaimError] The "exp" claim is invalid, or the token has 
     #   expired.
     def validate_exp(max_clock_skew = 0)
       max_clock_skew ||= 0
 
-      exp = time_claim('exp')
+      exp = time_claim("exp")
       if exp && exp <= (Time.now - max_clock_skew)
-        raise Sandal::ClaimError, 'The token has expired.' 
+        raise Sandal::ExpiredTokenError, "The token has expired." 
       end
     end
 
@@ -36,14 +36,14 @@ module Sandal
     #
     # @param max_clock_skew [Numeric] The maximum clock skew, in seconds.
     # @return [void].
-    # @raise [Sandal::ClaimError] The 'nbf' claim is invalid, or the token is 
+    # @raise [Sandal::ClaimError] The "nbf" claim is invalid, or the token is 
     #   not valid yet.
     def validate_nbf(max_clock_skew = 0)
       max_clock_skew ||= 0
 
-      nbf = time_claim('nbf')
+      nbf = time_claim("nbf")
       if nbf && nbf > (Time.now + max_clock_skew)
-        raise Sandal::ClaimError, 'The token is not valid yet.'
+        raise Sandal::ClaimError, "The token is not valid yet."
       end
     end
 
@@ -51,12 +51,12 @@ module Sandal
     #
     # @param valid_iss [Array] The valid issuers.
     # @return [void].
-    # @raise [Sandal::ClaimError] The 'iss' claim value is not a valid issuer.
+    # @raise [Sandal::ClaimError] The "iss" claim value is not a valid issuer.
     def validate_iss(valid_iss)
       return unless valid_iss && valid_iss.length > 0
 
-      unless valid_iss.include?(self['iss'])
-        raise Sandal::ClaimError, 'The issuer is invalid.'
+      unless valid_iss.include?(self["iss"])
+        raise Sandal::ClaimError, "The issuer is invalid."
       end
     end
 
@@ -64,15 +64,15 @@ module Sandal
     #
     # @param valid_aud [Array] The valid audiences.
     # @return [void].
-    # @raise [Sandal::ClaimError] The 'aud' claim value does not contain a valid
+    # @raise [Sandal::ClaimError] The "aud" claim value does not contain a valid
     #   audience.
     def validate_aud(valid_aud)
       return unless valid_aud && valid_aud.length > 0
 
-      aud = self['aud']
+      aud = self["aud"]
       aud = [aud] unless aud.is_a?(Array)
       unless (aud & valid_aud).length > 0
-        raise Sandal::ClaimError, 'The audence is invalid.'
+        raise Sandal::ClaimError, "The audence is invalid."
       end
     end
 
@@ -85,7 +85,7 @@ module Sandal
         begin
           Time.at(claim)
         rescue
-          raise Sandal::ClaimError, "The '#{name}' claim is invalid."
+          raise Sandal::ClaimError, "The "#{name}" claim is invalid."
         end
       end
     end

data/lib/sandal/enc.rb

@@ -1,60 +1,26 @@
-require 'openssl'
+require "openssl"
+require "sandal/util"
 
 module Sandal
   # Contains encryption (JWE) functionality.
   module Enc
 
-    # The Concat Key Derivation Function.
+    # Gets the decoded parts of a JWE token.
     #
-    # @param digest [OpenSSL::Digest or String] The digest for the algorithm.
-    # @param key [String] The key or shared secret.
-    # @param keydatalen [Integer] The desired output size in bits.
-    # @param algorithm_id [String] The name of the algorithm.
-    # @param party_u_info [String or 0] The partyUInfo.
-    # @param party_v_info [String or 0] The partyVInfo.
-    # @param supp_pub_info [String] Supplementary public info.
-    # @param supp_priv_info [String] Supplementary private info.
-    # @return [String] The derived keying material.
-    def self.concat_kdf(digest, key, keydatalen, algorithm_id, 
-                        party_u_info, party_v_info, 
-                        supp_pub_info = nil, supp_priv_info = nil)
-      digest = OpenSSL::Digest.new(digest) if digest.is_a?(String)
-      rounds = (keydatalen / (digest.digest_length * 8.0)).ceil
-
-      round_input = concat_kdf_round_input(key, keydatalen, algorithm_id,
-                                           party_u_info, party_v_info,
-                                           supp_pub_info, supp_priv_info)
-
-      (1..rounds).reduce('') do |output, round|
-        hash = digest.digest([round].pack('N') + round_input)
-        if round == rounds
-          round_bits = keydatalen % (digest.digest_length * 8)
-          hash = hash[0...(round_bits / 8)] unless round_bits == 0
-        end
-        output << hash
-      end
-    end
-
-    private
-
-    # The round input for the Concat KDF function (excluding round number).
-    def self.concat_kdf_round_input(key, keydatalen, algorithm_id, 
-                                    party_u_info, party_v_info, 
-                                    supp_pub_info, supp_priv_info)
-      input = ''.force_encoding('binary')
-      input << key.force_encoding('binary')
-      input << [keydatalen].pack('N')
-      input << algorithm_id.force_encoding('binary')
-      input << (party_u_info == 0 ? [0].pack('N') : party_u_info.force_encoding('binary'))
-      input << (party_v_info == 0 ? [0].pack('N') : party_v_info.force_encoding('binary'))
-      input << supp_pub_info.force_encoding('binary') if supp_pub_info
-      input << supp_priv_info.force_encoding('binary') if supp_priv_info
-      input
+    # @param token [String or Array] The token, or encoded token parts.
+    # @return [[Array, Array]] The encoded parts and the decoded parts.
+    def self.token_parts(token)
+      parts = token.is_a?(Array) ? token : token.split(".")
+      raise ArgumentError unless parts.length == 5
+      decoded_parts = parts.map { |part| jwt_base64_decode(part) }
+      return parts, decoded_parts
+    rescue ArgumentError
+      raise Sandal::InvalidTokenError, "Invalid token encoding."
     end
 
   end
 end
 
-require 'sandal/enc/acbc_hs'
-require 'sandal/enc/agcm' unless RUBY_VERSION < '2.0.0'
-require 'sandal/enc/alg'
+require "sandal/enc/acbc_hs"
+require "sandal/enc/agcm" unless RUBY_VERSION < "2.0.0"
+require "sandal/enc/alg"