sandal 0.1.0 → 0.1.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    N2E4NjhhOTY5Y2JkNGU1MmU1YjE2MmIzYTY4NzUwMTg5ZTc3NTk0OA==
+  data.tar.gz: !binary |-
+    YjA1YTA1MzExMDg2YmMwNDllNWQyYTgxZjNmMmQ0MjJhNWNiNTM0Mw==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    YTBlODVkNGFiNWQwNGQzZWE2YjFkY2JmNTg4MDliMDlkN2YyYjA0NzBmYWYw
+    OTk5MjMzMjViYjNiODBjOGU0YmQ5MjlmMzUxODI2MzU4NzU5ZTI3ODQ1ZTk5
+    YmI1OThiMDFkZDNjNzRlMmViZTUxYjU5MWU0M2MwMGE4NDcxMDg=
+  data.tar.gz: !binary |-
+    ZWFhNjNlNzc4NDgwNmI5OTAwMmNhNTFlNDE1NjhjY2ViM2E2N2FlMjQ5NjM3
+    MDkxZDk5MmFiMzY2NGM4YTlkMjY0MzI5NDI1YTRlYWIzOWY1ZTA2MzE2NzMw
+    NTIwMjA1ZjQxMTQ1ZWU3Y2I2YjA3YmI5NDA3OTgxODZhMGRkMjA=

data/.gitignore

@@ -2,19 +2,18 @@
 *.rbc
 .bundle
 .config
-.DS_Store
 coverage
+doc
+.DS_Store
 Gemfile.lock
 InstalledFiles
 lib/bundler/man
 pkg
+.rbx
 rdoc
 spec/reports
 test/tmp
 test/version_tmp
 tmp
-
-# YARD artifacts
 .yardoc
 _yardoc
-doc/

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.1.1 (01 April 2013)
+
+Features:
+
+- Changed from json to multi_json gem for improved compatibility.
+- New Claims module can add claims validation functionality to Hash-like objects.
+- New ClaimError type for claim validation errors.
+
+Bug fixes:
+
+- Base64 decoding now ensures there is no padding before decoding.
+
 ## 0.1.0 (30 March 2013)
 
 The first version worth using.

data/README.md

@@ -1,8 +1,8 @@
 **NOTE: This library is pretty new and still has a lot of things that aren't finished or could be improved. Expect bugs and interface changes. Pull requests or feedback very much appreciated.**
 
-# 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)
+# 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)
 
-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) drfat-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.
 
 ## Installation
 

data/lib/sandal/claims.rb

@@ -0,0 +1,82 @@
+module Sandal
+  # A module that can be mixed into Hash-like objects to provide claims-related functionality.
+  module Claims
+
+    # Validates the set of claims.
+    #
+    # @param options [Hash] The validation options (see {Sandal::DEFAULT_OPTIONS} for details).
+    # @return [Hash] A reference to self.
+    # @raise [Sandal::ClaimError] One or more claims is invalid.
+    def validate_claims(options)
+      validate_exp(options[:max_clock_skew]) if options[:validate_exp]
+      validate_nbf(options[:max_clock_skew]) if options[:validate_nbf]
+      validate_iss(options[:valid_iss])
+      validate_aud(options[:valid_aud])
+      self
+    end
+
+    # Validates the expires claim.
+    #
+    # @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 expired.
+    def validate_exp(max_clock_skew)
+      exp = time_claim('exp')
+      if exp && exp <= (Time.now - max_clock_skew)
+        raise Sandal::ClaimError, 'The token has expired.' 
+      end
+      nil
+    end
+
+    # Validates the not-before claim.
+    #
+    # @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 not valid yet.
+    def validate_nbf(max_clock_skew)
+      nbf = time_claim('nbf')
+      if nbf && nbf > (Time.now + max_clock_skew)
+        raise Sandal::ClaimError, 'The token is not valid yet.'
+      end
+    end
+
+    # Validates the issuer claim.
+    #
+    # @param valid_iss [Array] The valid issuers.
+    # @return [void].
+    # @raise [Sandal::ClaimError] The 'iss' claim value is not a valid issuer.
+    def validate_iss(valid_iss)
+      if valid_iss && valid_iss.length > 0
+        raise Sandal::ClaimError, 'The issuer is invalid.' unless valid_iss.include?(self['iss'])
+      end
+    end
+
+    # Validates the audience claim.
+    #
+    # @param valid_aud [Array] The valid audiences.
+    # @return [void].
+    # @raise [Sandal::ClaimError] The 'aud' claim value does not contain a valid audience.
+    def validate_aud(valid_aud)
+      if valid_aud && valid_aud.length > 0
+        aud = self['aud']
+        aud = [aud] unless aud.is_a?(Array)
+        raise Sandal::ClaimError, 'The audence is invalid.' unless (aud & valid_aud).length > 0
+      end
+    end
+
+    private
+
+    # Gets the value of a claim as a Time.
+    def time_claim(name)
+      claim = self[name]
+      if claim
+        begin
+          Time.at(claim)
+        rescue
+          raise ClaimError, "The '#{name}' claim is invalid."
+        end
+      end
+    end
+
+  end
+end

data/lib/sandal/enc/aescbc.rb

@@ -35,7 +35,7 @@ module Sandal
         ciphertext = cipher.update(payload) + cipher.final
         encoded_ciphertext = Sandal::Util.base64_encode(ciphertext)
 
-        encoded_header = Sandal::Util.base64_encode(JSON.generate(header))
+        encoded_header = Sandal::Util.base64_encode(MultiJson.dump(header))
         secured_input = [encoded_header, encoded_encrypted_key, encoded_iv, encoded_ciphertext].join('.')
         content_integrity_key = derive_content_key('Integrity', content_master_key, @sha_size)
         integrity_value = OpenSSL::HMAC.digest(@digest, content_integrity_key, secured_input)

data/lib/sandal/sig/es.rb

@@ -5,11 +5,16 @@ module Sandal
 
     # Base implementation of the ECDSA-SHA family of signature algorithms.
     class ES
-      include Sandal::Sig
 
-      # Creates a new instance with the size of the SHA algorithm and an OpenSSL ES PKey.
+      # @return [String] The JWA name of the algorithm.
+      attr_reader :name
+
+      # Creates a new instance; it's probably easier to use one of the subclass constructors.
+      #
+      # @param sha_size [Integer] The size of the SHA algorithm.
+      # @param prime_size [Integer] The size of the ECDSA primes.
+      # @param key [OpenSSL::PKey::EC] The key to use for signing (private) or validation (public).
       def initialize(sha_size, prime_size, key)
-        raise ArgumentError, 'A key is required.' unless key
         @name = "ES#{sha_size}"
         @digest = OpenSSL::Digest.new("sha#{sha_size}")
         @prime_size = prime_size
@@ -17,6 +22,9 @@ module Sandal
       end
 
       # Signs a payload and returns the signature.
+      #
+      # @param payload [String] The payload of the token to sign.
+      # @return [String] The signature.
       def sign(payload)
         hash = @digest.digest(payload)
         asn1_sig = @key.dsa_sign_asn1(hash)
@@ -24,64 +32,107 @@ module Sandal
         self.class.encode_jws_signature(r, s, @prime_size)
       end
 
-      # Verifies a payload signature and returns whether the signature matches.
-      def verify(signature, payload)
+      # Validates a payload signature and returns whether the signature matches.
+      #
+      # @param signature [String] The signature to verify.
+      # @param payload [String] The payload of the token.
+      # @return [Boolean] true if the signature is correct; otherwise false.
+      def valid?(signature, payload)
         hash = @digest.digest(payload)
         r, s = self.class.decode_jws_signature(signature)
         asn1_sig = self.class.encode_asn1_signature(r, s)
-        result = @key.dsa_verify_asn1(hash, asn1_sig)
+        @key.dsa_verify_asn1(hash, asn1_sig)
       end
 
-      # Decodes an ASN1 signature into a pair of BNs.
+      # Decodes an ASN.1 signature into a pair of BNs.
+      #
+      # @param signature [String] The ASN.1 signature.
+      # @return [OpenSSL::BN, OpenSSL::BN] A pair of BNs.
       def self.decode_asn1_signature(signature)
         asn_seq = OpenSSL::ASN1.decode(signature)
         return asn_seq.value[0].value, asn_seq.value[1].value
       end
 
-      # Encodes a pair of BNs into an ASN1 signature.
+      # Encodes a pair of BNs into an ASN.1 signature.
+      #
+      # @param r [OpenSSL::BN] The 'r' value.
+      # @param s [OpenSSL::BN] The 's' value.
+      # @return [String] The ASN.1 signature.
       def self.encode_asn1_signature(r, s)
         items = [OpenSSL::ASN1::Integer.new(r), OpenSSL::ASN1::Integer.new(s)]
         OpenSSL::ASN1::Sequence.new(items).to_der
       end
 
       # Decodes a JWS signature into a pair of BNs.
+      #
+      # @param signature [String] The ASN.1 signature.
+      # @return [OpenSSL::BN, OpenSSL::BN] A pair of BNs.
       def self.decode_jws_signature(signature)
         n_length = signature.length / 2
-        s_to_n = lambda { |s| OpenSSL::BN.new(s.unpack('H*')[0], 16) }
+        s_to_n = -> s { OpenSSL::BN.new(s.unpack('H*')[0], 16) }
         r = s_to_n.call(signature[0..(n_length - 1)])
         s = s_to_n.call(signature[n_length..-1])
         return r, s
       end
 
       # Encodes a pair of BNs into a JWS signature.
+      #
+      # @param r [OpenSSL::BN] The 'r' value.
+      # @param s [OpenSSL::BN] The 's' value.
+      # @param prime_size [Integer] The size of the ECDSA primes.
+      # @return [String] The ASN.1 signature.
       def self.encode_jws_signature(r, s, prime_size)
         byte_count = (prime_size / 8.0).ceil
-        n_to_s = lambda { |n| [n.to_s(16)].pack('H*').rjust(byte_count, "\0") }
+        n_to_s = -> n { [n.to_s(16)].pack('H*').rjust(byte_count, "\0") }
         n_to_s.call(r) + n_to_s.call(s)
       end
 
+      protected
+
+      # Ensures that a key has a specified curve name.
+      #
+      # @param key [OpenSSL::PKey::EC] The key.
+      # @param curve_name [String] The curve name.
+      # @return [void].
+      # @raise [ArgumentError] The key has a different curve name.
+      def ensure_curve(key, curve_name)
+        raise ArgumentError, "The key must be in the #{curve_name} group." unless key.group.curve_name == curve_name
+      end
+
     end
 
     # The ECDSA-SHA256 signing algorithm.
     class ES256 < Sandal::Sig::ES
-      # Creates a new instance with an OpenSSL ES PKey.
+      # Creates a new instance.
+      #
+      # @param key [OpenSSL::PKey::EC] The key to use for signing (private) or validation (public). 
+      # @raise [ArgumentError] The key is not in the "prime256v1" group.
       def initialize(key)
+        ensure_curve(key, 'prime256v1')
         super(256, 256, key)
       end
     end
 
     # The ECDSA-SHA384 signing algorithm.
     class ES384 < Sandal::Sig::ES
-      # Creates a new instance with an OpenSSL ES PKey.
+      # Creates a new instance.
+      #
+      # @param key [OpenSSL::PKey::EC] The key to use for signing (private) or validation (public). 
+      # @raise [ArgumentError] The key is not in the "secp384r1" group.
       def initialize(key)
+        ensure_curve(key, 'secp384r1')
         super(384, 384, key)
       end
     end
 
     # The ECDSA-SHA512 signing algorithm.
     class ES512 < Sandal::Sig::ES
-      # Creates a new instance with an OpenSSL ES PKey.
+      # Creates a new instance.
+      #
+      # @param key [OpenSSL::PKey::EC] The key to use for signing (private) or validation (public). 
+      # @raise [ArgumentError] The key is not in the "secp521r1" group.
       def initialize(key)
+        ensure_curve(key, 'secp521r1')
         super(512, 521, key)
       end
     end

data/lib/sandal/sig/hs.rb

@@ -5,23 +5,34 @@ module Sandal
 
     # Base implementation of the HMAC-SHA family of signature algorithms.
     class HS
-      include Sandal::Sig
 
-      # Creates a new instance with the size of the SHA algorithm and a string key.
+      # @return [String] The JWA name of the algorithm.
+      attr_reader :name
+
+      # Creates a new instance; it's probably easier to use one of the subclass constructors.
+      #
+      # @param sha_size [Integer] The size of the SHA algorithm.
+      # @param key [String] The key to use for signing or validation.
       def initialize(sha_size, key)
-        raise ArgumentError, 'A key is required.' unless key
         @name = "HS#{sha_size}"
         @digest = OpenSSL::Digest.new("sha#{sha_size}")
         @key = key
       end
 
       # Signs a payload and returns the signature.
+      #
+      # @param payload [String] The payload of the token to sign.
+      # @return [String] The signature.
       def sign(payload)
         OpenSSL::HMAC.digest(@digest, @key, payload)
       end
 
-      # Verifies a payload signature and returns whether the signature matches.
-      def verify(signature, payload)
+      # Validates a payload signature and returns whether the signature matches.
+      #
+      # @param signature [String] The signature to verify.
+      # @param payload [String] The payload of the token.
+      # @return [Boolean] true if the signature is correct; otherwise false.
+      def valid?(signature, payload)
         Sandal::Util.secure_equals(sign(payload), signature)
       end
 
@@ -29,7 +40,9 @@ module Sandal
 
     # The HMAC-SHA256 signing algorithm.
     class HS256 < Sandal::Sig::HS
-      # Creates a new instance with a string key.
+      # Creates a new instance.
+      #
+      # @param key [String] The key to use for signing or validation.
       def initialize(key)
         super(256, key)
       end
@@ -37,7 +50,9 @@ module Sandal
 
     # The HMAC-SHA384 signing algorithm.
     class HS384 < Sandal::Sig::HS
-      # Creates a new instance with a string key.
+      # Creates a new instance.
+      #
+      # @param key [String] The key to use for signing or validation.
       def initialize(key)
         super(384, key)
       end
@@ -45,7 +60,9 @@ module Sandal
 
     # The HMAC-SHA512 signing algorithm.
     class HS512 < Sandal::Sig::HS
-      # Creates a new instance with a string key.
+      # Creates a new instance.
+      #
+      # @param key [String] The key to use for signing or validation.
       def initialize(key)
         super(512, key)
       end

data/lib/sandal/sig/rs.rb

@@ -5,27 +5,35 @@ module Sandal
 
     # Base implementation of the RSA-SHA family of signature algorithms.
     class RS
-      include Sandal::Sig
 
-      # Creates a new instance with the size of the SHA algorithm and an OpenSSL RSA PKey. To sign
-      # a value this must contain a private key; to verify a signature a public key is sufficient.
-      # Note that the size of the RSA key must be at least 2048 bits to be compliant with the
-      # JWA specification.
+      # @return [String] The JWA name of the algorithm.
+      attr_reader :name
+
+      # Creates a new instance; it's probably easier to use one of the subclass constructors.
+      #
+      # @param sha_size [Integer] The size of the SHA algorithm.
+      # @param key [OpenSSL::PKey::RSA] The key to use for signing (private) or validation (public). This must
+      #   be at least 2048 bits to be compliant with the JWA specification.
       def initialize(sha_size, key)
-        raise ArgumentError, 'A key is required.' unless key
         @name = "RS#{sha_size}"
         @digest = OpenSSL::Digest.new("sha#{sha_size}")
         @key = key
       end
 
       # Signs a payload and returns the signature.
+      #
+      # @param payload [String] The payload of the token to sign.
+      # @return [String] The signature.
       def sign(payload)
-        raise ArgumentError, 'A private key is required to sign the payload.' unless @key.private?
         @key.sign(@digest, payload)
       end
 
-      # Verifies a payload signature and returns whether the signature matches.
-      def verify(signature, payload)
+      # Validates a payload signature and returns whether the signature matches.
+      #
+      # @param signature [String] The signature to verify.
+      # @param payload [String] The payload of the token.
+      # @return [Boolean] true if the signature is correct; otherwise false.
+      def valid?(signature, payload)
         @key.verify(@digest, signature, payload)
       end
 
@@ -33,7 +41,10 @@ module Sandal
 
     # The RSA-SHA256 signing algorithm.
     class RS256 < Sandal::Sig::RS
-      # Creates a new instance with an OpenSSL RSA PKey.
+      # Creates a new instance.
+      #
+      # @param key [OpenSSL::PKey::RSA] The key to use for signing (private) or validation (public). This must
+      #   be at least 2048 bits to be compliant with the JWA specification.
       def initialize(key)
         super(256, key)
       end
@@ -41,7 +52,10 @@ module Sandal
 
     # The RSA-SHA384 signing algorithm.
     class RS384 < Sandal::Sig::RS
-      # Creates a new instance with an OpenSSL RSA PKey.
+      # Creates a new instance.
+      #
+      # @param key [OpenSSL::PKey::RSA] The key to use for signing (private) or validation (public). This must
+      #   be at least 2048 bits to be compliant with the JWA specification.
       def initialize(key)
         super(384, key)
       end
@@ -49,7 +63,10 @@ module Sandal
 
     # The RSA-SHA512 signing algorithm.
     class RS512 < Sandal::Sig::RS
-      # Creates a new instance with an OpenSSL RSA PKey.
+      # Creates a new instance.
+      #
+      # @param key [OpenSSL::PKey::RSA] The key to use for signing (private) or validation (public). This must
+      #   be at least 2048 bits to be compliant with the JWA specification.
       def initialize(key)
         super(512, key)
       end

data/lib/sandal/sig.rb

@@ -1,34 +1,16 @@
 require 'singleton'
 
 module Sandal
-  # Common signature traits.
+  # Contains signature (JWS) functionality.
   module Sig
 
-    # @return [String] The JWA name of the algorithm.
-    attr_reader :name
-
-    # Signs a payload and returns the signature.
-    #
-    # @param payload [String] The payload of the token to sign.
-    # @return [String] The signature.
-    def sign(payload)
-      raise NotImplementedError, "#{@name}.sign is not implemented."
-    end
-
-    # Verifies a payload signature and returns whether the signature matches.
-    #
-    # @param signature [String] The signature to verify.
-    # @param payload [String] The payload of the token.
-    # @return [Boolean] true if the signature is correct; otherwise false.
-    def verify(signature, payload)
-      raise NotImplementedError, "#{@name}.verify is not implemented."
-    end
-
     # The 'none' JWA signature method.
     class None
-      include Sandal::Sig
       include Singleton
 
+      # @return [String] The JWA name of the algorithm.
+      attr_reader :name
+
       # Creates a new instance.
       def initialize
         @name = 'none'
@@ -42,13 +24,13 @@ module Sandal
         ''
       end
 
-      # Verifies that a signature is nil or empty.
+      # Validates that a signature is nil or empty.
       #
       # @param signature [String] The signature to verify.
       # @param payload [String] This parameter is ignored.
-      # @return [Boolean] `true` if the signature is nil or empty; otherwise `false`.
-      def verify(signature, payload)
-        signature.nil? || signature.length == 0
+      # @return [Boolean] true if the signature is nil or empty; otherwise false.
+      def valid?(signature, payload)
+        signature.nil? || signature.empty?
       end
 
     end

data/lib/sandal/util.rb

@@ -21,12 +21,20 @@ module Sandal
     end
 
     # Base64 encodes a string, in compliance with the JWT specification.
+    #
+    # @param s [String] The string to encode.
+    # @return [String] The encoded base64 string.
     def self.base64_encode(s)
       Base64.urlsafe_encode64(s).gsub(%r{=+$}, '')
     end
 
     # Base64 decodes a string, in compliance with the JWT specification.
+    #
+    # @param s [String] The base64 string to decode.
+    # @return [String] The decoded string.
+    # @raise [Sandal::TokenError] The base64 string contains padding.
     def self.base64_decode(s)
+      raise Sandal::TokenError, 'Base64 strings cannot contain padding.' if s.end_with?('=')
       padding_length = (4 - (s.length % 4)) % 4
       padding = '=' * padding_length
       Base64.urlsafe_decode64(s + padding)

data/lib/sandal/version.rb

@@ -1,4 +1,4 @@
 module Sandal
   # The semantic version of the library.
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/lib/sandal.rb

@@ -1,12 +1,11 @@
 $:.unshift('.')
 
 require 'base64'
-require 'json'
+require 'multi_json'
 require 'openssl'
-
+require 'sandal/claims'
+require 'sandal/util'
 require 'sandal/version'
-require 'sandal/sig'
-require 'sandal/enc'
 
 # A library for creating and reading JSON Web Tokens (JWT).
 module Sandal
@@ -14,6 +13,9 @@ module Sandal
   # The error that is raised when a token is invalid.
   class TokenError < StandardError; end
 
+  # The error that is raised when a claim within a token is invalid.
+  class ClaimError < TokenError; end
+
   # The default options for token handling.
   #
   # max_clock_skew:: The maximum clock skew, in seconds, when validating times.
@@ -43,23 +45,20 @@ module Sandal
 
   # Creates a signed JSON Web Token.
   #
-  # @param payload [String/Hash] The payload of the token. If a Hash then it will be encoded as JSON.
-  # @param signer [Sandal::Sig] The token signer, which may be nil for an unsigned token.
+  # @param payload [String/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)
-    if header_fields && header_fields['enc']
-      raise ArgumentError, 'The header cannot contain an "enc" parameter.'
-    end
     signer ||= Sandal::Sig::None.instance
 
     header = {}
     header['alg'] = signer.name if signer.name != Sandal::Sig::None.instance.name
     header = header_fields.merge(header) if header_fields
 
-    payload = JSON.generate(payload) if payload.kind_of?(Hash)
+    payload = MultiJson.dump(payload) unless payload.is_a?(String)
 
-    encoded_header = Sandal::Util.base64_encode(JSON.generate(header))
+    encoded_header = Sandal::Util.base64_encode(MultiJson.dump(header))
     encoded_payload = Sandal::Util.base64_encode(payload)
     secured_input = [encoded_header, encoded_payload].join('.')
 
@@ -86,47 +85,29 @@ module Sandal
   # Decodes and validates a JSON Web Token.
   #
   # The block is called with the token header as the first parameter, and should return the appropriate
-  # {Sandal::Sig} to verify the signature. It can optionally have a second options parameter which can
+  # {Sandal::Sig} to validate the signature. It can optionally have a second options parameter which can
   # be used to override the {DEFAULT_OPTIONS} on a per-token basis.
   #
   # @param token [String] The encoded JSON Web Token.
   # @yieldparam header [Hash] The JWT header values.
   # @yieldparam options [Hash] (Optional) A hash that can be used to override the default options.
-  # @yieldreturn [Sandal::Sig] The signature verifier.
+  # @yieldreturn [#valid?] The signature validator.
   # @return [Hash/String] The payload of the token as a Hash if it was JSON, otherwise as a String.
-  # @raise [ArgumentError] The token parameter is nil or empty, or the block has the wrong arity.
-  # @raise [TokenError] The token format is invalid, or validation of the token failed.
-  def self.decode_token(token, &block)
-    raise ArgumentError, 'A token is required.' unless token && token.length > 0
+  # @raise [Sandal::TokenError] The token format is invalid, or validation of the token failed.
+  def self.decode_token(token)
     parts = token.split('.')
-    raise TokenError, 'Invalid token format.' unless [2, 3].include?(parts.length)
-    begin
-      header = JSON.parse(Sandal::Util.base64_decode(parts[0]))
-      payload = Sandal::Util.base64_decode(parts[1])
-      signature = if parts.length > 2 then Sandal::Util.base64_decode(parts[2]) else '' end
-    rescue
-      raise TokenError, 'Invalid token encoding.'
-    end
+    header, payload, signature = decode_jws_parts(parts)
 
     options = DEFAULT_OPTIONS.clone
-    if block
-      case block.arity
-      when 1 then verifier = block.call(header)
-      when 2 then verifier = block.call(header, options)
-      else raise ArgumentError, 'Incorrect number of block parameters.'
-      end
-    end    
-    verifier ||= Sandal::Sig::None.instance
+    validator = yield header, options if block_given?
+    validator ||= Sandal::Sig::None.instance
 
     if options[:validate_signature]
       secured_input = parts.take(2).join('.')
-      raise TokenError, 'Invalid signature.' unless verifier.verify(signature, secured_input)
+      raise TokenError, 'Invalid signature.' unless validator.valid?(signature, secured_input)
     end
 
-    claims = JSON.parse(payload) rescue nil
-    validate_claims(claims, options) if claims
-
-    claims || payload
+    parse_and_validate(payload, header['cty'], options)
   end
 
   # Decrypts an encrypted JSON Web Token.
@@ -136,7 +117,7 @@ module Sandal
     parts = encrypted_token.split('.')
     raise ArgumentError, 'Invalid token format.' unless parts.length == 5
     begin
-      header = JSON.parse(Sandal::Util.base64_decode(parts[0]))
+      header = MultiJson.load(Sandal::Util.base64_decode(parts[0]))
       encrypted_key = Sandal::Util.base64_decode(parts[1])
       iv = Sandal::Util.base64_decode(parts[2])
       ciphertext = Sandal::Util.base64_decode(parts[3])
@@ -152,54 +133,30 @@ module Sandal
 
   private
 
-  # Validates token claims according to the options
-  def self.validate_claims(claims, options)
-    validate_expires(claims, options)
-    validate_not_before(claims, options)
-    validate_issuer(claims, options)
-    validate_audience(claims, options)
-  end
-
-  # Validates the 'exp' claim.
-  def self.validate_expires(claims, options)
-    if options[:validate_exp] && claims['exp']
-      begin
-        exp = Time.at(claims['exp'])
-      rescue
-        raise TokenError, 'The "exp" claim is invalid.'
-      end
-      raise TokenError, 'The token has expired.' unless exp > (Time.now - options[:max_clock_skew])
-    end
-  end
-
-  # Validates the 'nbf' claim
-  def self.validate_not_before(claims, options)
-    if options[:validate_nbf] && claims['nbf']
-      begin
-        nbf = Time.at(claims['nbf'])
-      rescue
-        raise TokenError, 'The "nbf" claim is invalid.'
-      end
-      raise TokenError, 'The token is not valid yet.' unless nbf < (Time.now + options[:max_clock_skew])
+  # Decodes the parts of a JWS token.
+  def self.decode_jws_parts(parts)
+    raise TokenError, 'Invalid token format.' unless [2, 3].include?(parts.length)
+    begin
+      header = MultiJson.load(Sandal::Util.base64_decode(parts[0]))
+      payload = Sandal::Util.base64_decode(parts[1])
+      signature = if parts.length > 2 then Sandal::Util.base64_decode(parts[2]) else '' end
+    rescue
+      raise TokenError, 'Invalid token encoding.'
     end
+    return header, payload, signature
   end
 
-  # Validates the 'iss' claim.
-  def self.validate_issuer(claims, options)
-    valid_iss = options[:valid_iss]
-    if valid_iss && valid_iss.length > 0
-      raise TokenError, 'The issuer is invalid.' unless valid_iss.include?(claims['iss'])
+  # Parses the content of a token and validates the claims if is a JSON claim set.
+  def self.parse_and_validate(payload, content_type, options)
+    claims = MultiJson.load(payload) rescue nil unless content_type == 'JWT'
+    if claims
+      claims.extend(Sandal::Claims).validate_claims(options)
+    else
+      payload
     end
   end
 
-  # Validates the 'aud' claim.
-  def self.validate_audience(claims, options)
-    valid_aud = options[:valid_aud]
-    if valid_aud && valid_aud.length > 0
-      aud = claims['aud']
-      aud = [aud] unless aud.kind_of?(Array)
-      raise TokenError, 'The audence is invalid.' unless (aud & valid_aud).length > 0
-    end
-  end
+end
 
-end
+require 'sandal/enc'
+require 'sandal/sig'

data/sandal.gemspec

@@ -17,16 +17,16 @@ Gem::Specification.new do |s|
   s.require_paths = ['lib']
   s.extra_rdoc_files = ['README.md', 'LICENSE.md']
 
-  s.add_runtime_dependency 'json', '~> 1.7'
+  s.add_runtime_dependency 'multi_json', '~> 1.7'
   s.add_runtime_dependency 'jruby-openssl', '~> 0.7', '>= 0.7.3' if RUBY_PLATFORM == 'java'
 
-  s.add_development_dependency 'bundler', '~> 1.3'
-  s.add_development_dependency 'rake', '~> 10.0'
-  s.add_development_dependency 'rspec', '~> 2.13'
-  s.add_development_dependency 'coveralls', '~> 0.6'
-  s.add_development_dependency 'yard', '~> 0.8'
-  s.add_development_dependency 'redcarpet', '~> 2.2' unless RUBY_PLATFORM == 'java' # for yard
-  s.add_development_dependency 'kramdown', '~> 1.0' if RUBY_PLATFORM == 'java'      # for yard
+  s.add_development_dependency 'bundler', '>= 1.3'
+  s.add_development_dependency 'rake', '>= 10.0'
+  s.add_development_dependency 'rspec', '>= 2.13'
+  s.add_development_dependency 'coveralls', '>= 0.6'
+  s.add_development_dependency 'yard', '>= 0.8'
+  s.add_development_dependency 'redcarpet', '>= 2.2' unless RUBY_PLATFORM == 'java' # for yard
+  s.add_development_dependency 'kramdown', '>= 1.0' if RUBY_PLATFORM == 'java'      # for yard
 
   s.requirements << 'openssl 1.0.1c for EC signature methods'
 end

data/spec/sandal/sig/es_spec.rb

@@ -55,8 +55,8 @@ describe Sandal::Sig::ES256 do
     signature = signer.sign(data)
     public_key = OpenSSL::PKey::EC.new(group)
     public_key.public_key = private_key.public_key
-    verifier = Sandal::Sig::ES256.new(public_key)
-    verifier.verify(signature, data).should == true
+    validator = Sandal::Sig::ES256.new(public_key)
+    validator.valid?(signature, data).should == true
   end
 
   it 'can verify the signature in JWS section A3.1' do
@@ -69,8 +69,8 @@ describe Sandal::Sig::ES256 do
     group = OpenSSL::PKey::EC::Group.new('prime256v1') 
     public_key = OpenSSL::PKey::EC.new(group)
     public_key.public_key = make_point(group, x, y)
-    verifier = Sandal::Sig::ES256.new(public_key)
-    verifier.verify(signature, data).should == true
+    validator = Sandal::Sig::ES256.new(public_key)
+    validator.valid?(signature, data).should == true
   end
 
   it 'fails to verify the signature in JWS section A3.1 when the data is changed' do
@@ -83,8 +83,14 @@ describe Sandal::Sig::ES256 do
     group = OpenSSL::PKey::EC::Group.new('prime256v1') 
     public_key = OpenSSL::PKey::EC.new(group)
     public_key.public_key = make_point(group, x, y)
-    verifier = Sandal::Sig::ES256.new(public_key)
-    verifier.verify(signature, data).should == false
+    validator = Sandal::Sig::ES256.new(public_key)
+    validator.valid?(signature, data).should == false
+  end
+
+  it 'raises an argument error if the key has the wrong curve' do
+    group = OpenSSL::PKey::EC::Group.new('secp384r1') 
+    private_key = OpenSSL::PKey::EC.new(group).generate_key
+    expect { Sandal::Sig::ES256.new(private_key) }.to raise_error ArgumentError
   end
 
 end
@@ -99,8 +105,14 @@ describe Sandal::Sig::ES384 do
     signature = signer.sign(data)
     public_key = OpenSSL::PKey::EC.new(group)
     public_key.public_key = private_key.public_key
-    verifier = Sandal::Sig::ES384.new(public_key)
-    verifier.verify(signature, data).should == true
+    validator = Sandal::Sig::ES384.new(public_key)
+    validator.valid?(signature, data).should == true
+  end
+
+  it 'raises an argument error if the key has the wrong curve' do
+    group = OpenSSL::PKey::EC::Group.new('secp521r1') 
+    private_key = OpenSSL::PKey::EC.new(group).generate_key
+    expect { Sandal::Sig::ES384.new(private_key) }.to raise_error ArgumentError
   end
 
 end
@@ -115,8 +127,8 @@ describe Sandal::Sig::ES512 do
     signature = signer.sign(data)
     public_key = OpenSSL::PKey::EC.new(group)
     public_key.public_key = private_key.public_key
-    verifier = Sandal::Sig::ES512.new(public_key)
-    verifier.verify(signature, data).should == true
+    validator = Sandal::Sig::ES512.new(public_key)
+    validator.valid?(signature, data).should == true
   end
 
   it 'can verify the signature in JWS section A4.1' do
@@ -129,8 +141,8 @@ describe Sandal::Sig::ES512 do
     group = OpenSSL::PKey::EC::Group.new('secp521r1') 
     public_key = OpenSSL::PKey::EC.new(group)
     public_key.public_key = make_point(group, x, y)
-    verifier = Sandal::Sig::ES512.new(public_key)
-    verifier.verify(signature, data).should == true
+    validator = Sandal::Sig::ES512.new(public_key)
+    validator.valid?(signature, data).should == true
   end
 
   it 'fails to verify the signature in JWS section A4.1 when the data is changed' do
@@ -143,8 +155,14 @@ describe Sandal::Sig::ES512 do
     group = OpenSSL::PKey::EC::Group.new('secp521r1') 
     public_key = OpenSSL::PKey::EC.new(group)
     public_key.public_key = make_point(group, x, y)
-    verifier = Sandal::Sig::ES512.new(public_key)
-    verifier.verify(signature, data).should == false
+    validator = Sandal::Sig::ES512.new(public_key)
+    validator.valid?(signature, data).should == false
+  end
+
+  it 'raises an argument error if the key has the wrong curve' do
+    group = OpenSSL::PKey::EC::Group.new('prime256v1') 
+    private_key = OpenSSL::PKey::EC.new(group).generate_key
+    expect { Sandal::Sig::ES512.new(private_key) }.to raise_error ArgumentError
   end
 
 end

data/spec/sandal/sig/hs_spec.rb

@@ -7,7 +7,7 @@ describe Sandal::Sig::HS256 do
     key = 'A secret key'
     signer = Sandal::Sig::HS256.new(key)
     signature = signer.sign(data)
-    signer.verify(signature, data).should == true
+    signer.valid?(signature, data).should == true
   end
 end
 
@@ -17,7 +17,7 @@ describe Sandal::Sig::HS384 do
     key = 'Another secret key'
     signer = Sandal::Sig::HS384.new(key)
     signature = signer.sign(data)
-    signer.verify(signature, data).should == true
+    signer.valid?(signature, data).should == true
   end
 end
 
@@ -27,6 +27,6 @@ describe Sandal::Sig::HS512 do
     key = 'Yet another secret key'
     signer = Sandal::Sig::HS512.new(key)
     signature = signer.sign(data)
-    signer.verify(signature, data).should == true
+    signer.valid?(signature, data).should == true
   end
 end

data/spec/sandal/sig/rs_spec.rb

@@ -7,8 +7,8 @@ describe Sandal::Sig::RS256 do
     private_key = OpenSSL::PKey::RSA.generate(2048)
     signer = Sandal::Sig::RS256.new(private_key)
     signature = signer.sign(data)
-    verifier = Sandal::Sig::RS256.new(private_key.public_key)
-    verifier.verify(signature, data).should == true
+    validator = Sandal::Sig::RS256.new(private_key.public_key)
+    validator.valid?(signature, data).should == true
   end
 end
 
@@ -18,8 +18,8 @@ describe Sandal::Sig::RS384 do
     private_key = OpenSSL::PKey::RSA.generate(2048)
     signer = Sandal::Sig::RS384.new(private_key)
     signature = signer.sign(data)
-    verifier = Sandal::Sig::RS384.new(private_key.public_key)
-    verifier.verify(signature, data).should == true
+    validator = Sandal::Sig::RS384.new(private_key.public_key)
+    validator.valid?(signature, data).should == true
   end
 end
 
@@ -29,7 +29,7 @@ describe Sandal::Sig::RS512 do
     private_key = OpenSSL::PKey::RSA.generate(2048)
     signer = Sandal::Sig::RS512.new(private_key)
     signature = signer.sign(data)
-    verifier = Sandal::Sig::RS512.new(private_key.public_key)
-    verifier.verify(signature, data).should == true
+    validator = Sandal::Sig::RS512.new(private_key.public_key)
+    validator.valid?(signature, data).should == true
   end
 end

data/spec/sandal/util_spec.rb

@@ -11,6 +11,10 @@ describe Sandal::Util do
     val.should == src
   end
 
+  it 'raises a token error if base64 strings contain padding' do
+    expect { Sandal::Util.base64_decode('eyJpc3MiOiJq=') }.to raise_error Sandal::TokenError
+  end
+
   it 'compares nil strings as equal' do
     Sandal::Util.secure_equals(nil, nil).should == true
   end

data/spec/sandal_spec.rb

@@ -27,22 +27,22 @@ describe Sandal do
 
   it 'decodes non-JSON payloads to a String' do
     token = Sandal.encode_token('not valid json', nil)
-    Sandal.decode_token(token).class.should == String
+    Sandal.decode_token(token).class.should.kind_of? String
   end
 
   it 'decodes JSON payloads to a Hash' do
     token = Sandal.encode_token({ 'valid' => 'json' }, nil)
-    Sandal.decode_token(token).class.should == Hash
+    Sandal.decode_token(token).class.should.kind_of? Hash
   end
 
-  it 'raises a token error when the expiry date is far in the past' do
+  it 'raises a claim error when the expiry date is far in the past' do
     token = Sandal.encode_token({ 'exp' => (Time.now - 600).to_i }, nil)
-    expect { Sandal.decode_token(token) }.to raise_error Sandal::TokenError
+    expect { Sandal.decode_token(token) }.to raise_error Sandal::ClaimError
   end
 
-  it 'raises a token error when the expiry date is invalid' do
+  it 'raises a claim error when the expiry date is invalid' do
     token = Sandal.encode_token({ 'exp' => 'invalid value' }, nil)
-    expect { Sandal.decode_token(token) }.to raise_error Sandal::TokenError
+    expect { Sandal.decode_token(token) }.to raise_error Sandal::ClaimError
   end
 
   it 'does not raise an error when the expiry date is far in the past but validation is disabled' do
@@ -60,14 +60,14 @@ describe Sandal do
     Sandal.decode_token(token)
   end
 
-  it 'raises a token error when the not-before date is far in the future' do
+  it 'raises a claim error when the not-before date is far in the future' do
     token = Sandal.encode_token({ 'nbf' => (Time.now + 600).to_i }, nil)
-    expect { Sandal.decode_token(token) }.to raise_error Sandal::TokenError
+    expect { Sandal.decode_token(token) }.to raise_error Sandal::ClaimError
   end
 
-  it 'raises a token error when the not-before date is invalid' do
+  it 'raises a claim error when the not-before date is invalid' do
     token = Sandal.encode_token({ 'nbf' => 'invalid value' }, nil)
-    expect { Sandal.decode_token(token) }.to raise_error Sandal::TokenError
+    expect { Sandal.decode_token(token) }.to raise_error Sandal::ClaimError
   end
 
   it 'does not raise an error when the not-before date is far in the future but validation is disabled' do
@@ -85,12 +85,12 @@ describe Sandal do
     Sandal.decode_token(token)
   end
 
-  it 'raises a token error when the issuer is not valid' do
+  it 'raises a claim error when the issuer is not valid' do
     token = Sandal.encode_token({ 'iss' => 'example.org' }, nil)
     expect { Sandal.decode_token(token) do |header, options| 
       options[:valid_iss] = ['example.net'] 
       nil
-    end }.to raise_error Sandal::TokenError
+    end }.to raise_error Sandal::ClaimError
   end
 
   it 'does not raise an error when the issuer is valid' do
@@ -101,20 +101,20 @@ describe Sandal do
     end
   end
 
-  it 'raises a token error when the audience string is not valid' do
+  it 'raises a claim error when the audience string is not valid' do
     token = Sandal.encode_token({ 'aud' => 'example.com' }, nil)
     expect { Sandal.decode_token(token) do |header, options| 
       options[:valid_aud] = ['example.net'] 
       nil
-    end }.to raise_error Sandal::TokenError
+    end }.to raise_error Sandal::ClaimError
   end
 
-  it 'raises a token error when the audience array is not valid' do
+  it 'raises a claim error when the audience array is not valid' do
     token = Sandal.encode_token({ 'aud' => ['example.org', 'example.com'] }, nil)
     expect { Sandal.decode_token(token) do |header, options| 
       options[:valid_aud] = ['example.net'] 
       nil
-    end }.to raise_error Sandal::TokenError
+    end }.to raise_error Sandal::ClaimError
   end
 
   it 'does not raise an error when the audience string is valid' do

metadata

@@ -1,20 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: sandal
 version: !ruby/object:Gem::Version
-  version: 0.1.0
-  prerelease: 
+  version: 0.1.1
 platform: ruby
 authors:
 - Greg Beech
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-30 00:00:00.000000000 Z
+date: 2013-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: json
+  name: multi_json
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -22,7 +20,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -30,97 +27,85 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '2.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '2.13'
 - !ruby/object:Gem::Dependency
   name: coveralls
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0.6'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0.8'
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '2.2'
 description: A ruby library for creating and reading JSON Web Tokens (JWT), supporting
@@ -143,6 +128,7 @@ files:
 - README.md
 - Rakefile
 - lib/sandal.rb
+- lib/sandal/claims.rb
 - lib/sandal/enc.rb
 - lib/sandal/enc/aescbc.rb
 - lib/sandal/enc/aesgcm.rb
@@ -162,34 +148,27 @@ files:
 homepage: http://rubygems.org/gems/sandal
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -3672992457221215645
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -3672992457221215645
 requirements:
 - openssl 1.0.1c for EC signature methods
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: A JSON Web Token (JWT) library.
 test_files:
 - spec/helper.rb