sandal 0.2.0 → 0.3.0

data/lib/sandal/enc/agcm.rb

@@ -6,6 +6,7 @@ module Sandal
 
     # Base implementation of the AES/GCM family of encryption algorithms.
     class AGCM
+      extend Sandal::Util
 
       # The JWA name of the encryption.
       attr_reader :name
@@ -22,28 +23,33 @@ module Sandal
 
       def encrypt(header, payload)
         cipher = OpenSSL::Cipher.new(@cipher_name).encrypt
-        content_master_key = @alg.respond_to?(:cmk) ? @alg.cmk : cipher.random_key
-        encrypted_key = @alg.encrypt_cmk(content_master_key)
+        cmk = @alg.respond_to?(:cmk) ? @alg.cmk : cipher.random_key
+        encrypted_key = @alg.encrypt_cmk(cmk)
 
-        cipher.key = content_master_key
+        cipher.key = cmk
         iv = cipher.random_iv
 
         auth_parts = [MultiJson.dump(header), encrypted_key, iv]
-        auth_data = auth_parts.map { |part| Sandal::Util.base64_encode(part) }.join('.')
+        auth_data = auth_parts.map { |part| jwt_base64_encode(part) }.join('.')
         cipher.auth_data  = auth_data
 
         ciphertext = cipher.update(payload) + cipher.final
-        remainder = [ciphertext, cipher.auth_tag].map { |part| Sandal::Util.base64_encode(part) }.join('.')
-        [auth_data, remainder].join('.')
+        remaining_parts = [ciphertext, cipher.auth_tag]
+        remaining_parts.map! { |part| jwt_base64_encode(part) }
+        [auth_data, *remaining_parts].join('.')
       end
 
       def decrypt(parts, decoded_parts)
         cipher = OpenSSL::Cipher.new(@cipher_name).decrypt
-        cipher.key = @alg.decrypt_cmk(decoded_parts[1])
-        cipher.iv = decoded_parts[2]
-        cipher.auth_tag = decoded_parts[4]
-        cipher.auth_data = parts.take(3).join('.')
-        cipher.update(decoded_parts[3]) + cipher.final
+        begin
+          cipher.key = @alg.decrypt_cmk(decoded_parts[1])
+          cipher.iv = decoded_parts[2]
+          cipher.auth_tag = decoded_parts[4]
+          cipher.auth_data = parts.take(3).join('.')
+          cipher.update(decoded_parts[3]) + cipher.final
+        rescue OpenSSL::Cipher::CipherError
+          raise Sandal::TokenError, 'Invalid token.'
+        end
       end
 
     end

data/lib/sandal/enc/alg/direct.rb

@@ -4,7 +4,8 @@ module Sandal
   module Enc
     module Alg
 
-      # The direct ("dir") key encryption mechanism, which uses a pre-shared content master key.
+      # The direct ("dir") key encryption mechanism, which uses a pre-shared 
+      # content master key.
       class Direct
 
         # @return [String] The JWA name of the algorithm.
@@ -21,7 +22,8 @@ module Sandal
           @cmk = cmk
         end
 
-        # Returns an empty string as the content master key is not included in the JWE token.
+        # Returns an empty string as the content master key is not included in 
+        # the JWE token.
         #
         # @param cmk [String] This parameter is ignored.
         # @return [String] An empty string.
@@ -36,7 +38,7 @@ module Sandal
         # @raise [Sandal::TokenError] encrypted_cmk is not nil or empty.
         def decrypt_cmk(encrypted_cmk)
           unless encrypted_cmk.nil? || encrypted_cmk.empty?
-            raise Sandal::TokenError, 'The token should not include an encrypted content master key.' 
+            raise Sandal::TokenError, 'Token must not include encrypted CMK.' 
           end
           @cmk
         end

data/lib/sandal/enc/alg/rsa1_5.rb

@@ -12,10 +12,13 @@ module Sandal
 
         # Creates a new instance.
         #
-        # @param key [OpenSSL::PKey::RSA] The RSA public key used to protect the content master key.
+        # @param key [OpenSSL::PKey::RSA or String] The key to use for CMK 
+        # encryption (public) or decryption (private). If the value is a String 
+        # then it will be passed to the constructor of the RSA class. This must 
+        # be at least 2048 bits to be compliant with the JWA specification.
         def initialize(key)
           @name = 'RSA1_5'
-          @key = key
+          @key = key.is_a?(String) ? OpenSSL::PKey::RSA.new(key) : key
         end
 
         # Encrypts the content master key.
@@ -30,11 +33,11 @@ module Sandal
         #
         # @param encrypted_cmk [String] The encrypted content master key.
         # @return [String] The pre-shared content master key.
-        # @raise [Sandal::TokenError] The content master key cannot be decrypted.
+        # @raise [Sandal::TokenError] The content master key can't be decrypted.
         def decrypt_cmk(encrypted_cmk)
           @key.private_decrypt(encrypted_cmk)
         rescue
-          raise Sandal::TokenError, 'Failed to decrypt the content master key.'
+          raise Sandal::TokenError, 'Cannot decrypt content master key.'
         end
 
       end

data/lib/sandal/enc/alg/rsa_oaep.rb

@@ -12,10 +12,13 @@ module Sandal
 
         # Creates a new instance.
         #
-        # @param key [OpenSSL::PKey::RSA] The RSA public key used to protect the content master key.
+        # @param key [OpenSSL::PKey::RSA or String] The key to use for CMK 
+        # encryption (public) or decryption (private). If the value is a String 
+        # then it will be passed to the constructor of the RSA class. This must 
+        # be at least 2048 bits to be compliant with the JWA specification.
         def initialize(key)
           @name = 'RSA-OAEP'
-          @key = key
+          @key = key.is_a?(String) ? OpenSSL::PKey::RSA.new(key) : key
           @padding = OpenSSL::PKey::RSA::PKCS1_OAEP_PADDING
         end
 
@@ -31,11 +34,11 @@ module Sandal
         #
         # @param encrypted_cmk [String] The encrypted content master key.
         # @return [String] The pre-shared content master key.
-        # @raise [Sandal::TokenError] The content master key cannot be decrypted.
+        # @raise [Sandal::TokenError] The content master key can't be decrypted.
         def decrypt_cmk(encrypted_cmk)
           @key.private_decrypt(encrypted_cmk, @padding)
         rescue
-          raise Sandal::TokenError, 'Failed to decrypt the content master key.'
+          raise Sandal::TokenError, 'Cannot decrypt content master key.'
         end
 
       end

data/lib/sandal/sig.rb

@@ -28,13 +28,16 @@ module Sandal
       #
       # @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.
+      # @return [Boolean] true if the signature is nil/empty; otherwise false.
       def valid?(signature, payload)
         signature.nil? || signature.empty?
       end
 
     end
 
+    # The singleton instance of the Sandal::Sig::None signature method.
+    NONE = Sandal::Sig::None.instance
+
   end
 end
 

data/lib/sandal/sig/es.rb

@@ -9,11 +9,13 @@ module Sandal
       # @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.
+      # 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).
+      # @param key [OpenSSL::PKey::EC] The key to use for signing (private) or 
+      #   validation (public).
       def initialize(sha_size, prime_size, key)
         @name = "ES#{sha_size}"
         @digest = OpenSSL::Digest.new("sha#{sha_size}")
@@ -87,16 +89,20 @@ module Sandal
         n_to_s.call(r) + n_to_s.call(s)
       end
 
-      protected
+      private
 
-      # Ensures that a key has a specified curve name.
+      # Makes an EC key and ensures that it has the right curve name.
       #
-      # @param key [OpenSSL::PKey::EC] The key.
+      # @param key [OpenSSL::PKey::EC or String] 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
+      # @return [OpenSSL::PKey::EC] The key.
+      # @raise [ArgumentError] The key has the wrong curve name.
+      def make_key(key, curve_name)
+        key = OpenSSL::PKey::EC.new(key) if key.is_a?(String)
+        unless key.group.curve_name == curve_name
+          raise ArgumentError, "The key must be in the #{curve_name} group."
+        end
+        key
       end
 
     end
@@ -105,11 +111,12 @@ module Sandal
     class ES256 < Sandal::Sig::ES
       # Creates a new instance.
       #
-      # @param key [OpenSSL::PKey::EC] The key to use for signing (private) or validation (public). 
+      # @param key [OpenSSL::PKey::EC or String] The key to use for signing 
+      #   (private) or validation (public). If the value is a String then it 
+      #   will be passed to the constructor of the EC class.
       # @raise [ArgumentError] The key is not in the "prime256v1" group.
       def initialize(key)
-        ensure_curve(key, 'prime256v1')
-        super(256, 256, key)
+        super(256, 256, make_key(key, 'prime256v1'))
       end
     end
 
@@ -117,11 +124,12 @@ module Sandal
     class ES384 < Sandal::Sig::ES
       # Creates a new instance.
       #
-      # @param key [OpenSSL::PKey::EC] The key to use for signing (private) or validation (public). 
+      # @param key [OpenSSL::PKey::EC or String] The key to use for signing 
+      #   (private) or validation (public). If the value is a String then it 
+      #   will be passed to the constructor of the EC class.
       # @raise [ArgumentError] The key is not in the "secp384r1" group.
       def initialize(key)
-        ensure_curve(key, 'secp384r1')
-        super(384, 384, key)
+        super(384, 384, make_key(key, 'secp384r1'))
       end
     end
 
@@ -129,11 +137,12 @@ module Sandal
     class ES512 < Sandal::Sig::ES
       # Creates a new instance.
       #
-      # @param key [OpenSSL::PKey::EC] The key to use for signing (private) or validation (public). 
+      # @param key [OpenSSL::PKey::EC or String] The key to use for signing 
+      #   (private) or validation (public). If the value is a String then it 
+      #   will be passed to the constructor of the EC class.
       # @raise [ArgumentError] The key is not in the "secp521r1" group.
       def initialize(key)
-        ensure_curve(key, 'secp521r1')
-        super(512, 521, key)
+        super(512, 521, make_key(key, 'secp521r1'))
       end
     end
 

data/lib/sandal/sig/hs.rb

@@ -5,11 +5,13 @@ module Sandal
 
     # Base implementation of the HMAC-SHA family of signature algorithms.
     class HS
+      extend Sandal::Util
 
       # @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.
+      # 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.
@@ -33,7 +35,7 @@ module Sandal
       # @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)
+        jwt_strings_equal?(sign(payload), signature)
       end
 
     end

data/lib/sandal/sig/rs.rb

@@ -9,11 +9,13 @@ module Sandal
       # @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.
+      # 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.
+      # @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)
         @name = "RS#{sha_size}"
         @digest = OpenSSL::Digest.new("sha#{sha_size}")
@@ -37,16 +39,28 @@ module Sandal
         @key.verify(@digest, signature, payload)
       end
 
+      private
+
+      # Makes an RSA key.
+      #
+      # @param key [OpenSSL::PKey::RSA or String] The key.
+      # @return [OpenSSL::PKey::RSA] The key.
+      def make_key(key)
+        key.is_a?(String) ? OpenSSL::PKey::RSA.new(key) : key
+      end
+
     end
 
     # The RSA-SHA256 signing algorithm.
     class RS256 < Sandal::Sig::RS
       # 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.
+      # @param key [OpenSSL::PKey::RSA or String] The key to use for signing 
+      #   (private) or validation (public). If the value is a String then it 
+      #   will be passed to the constructor of the RSA class. This must be at 
+      #   least 2048 bits to be compliant with the JWA specification.
       def initialize(key)
-        super(256, key)
+        super(256, make_key(key))
       end
     end
 
@@ -54,10 +68,12 @@ module Sandal
     class RS384 < Sandal::Sig::RS
       # 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.
+      # @param key [OpenSSL::PKey::RSA or String] The key to use for signing 
+      #   (private) or validation (public). If the value is a String then it 
+      #   will be passed to the constructor of the RSA class. This must be at 
+      #   least 2048 bits to be compliant with the JWA specification.
       def initialize(key)
-        super(384, key)
+        super(384, make_key(key))
       end
     end
 
@@ -65,10 +81,12 @@ module Sandal
     class RS512 < Sandal::Sig::RS
       # 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.
+      # @param key [OpenSSL::PKey::RSA or String] The key to use for signing 
+      #   (private) or validation (public). If the value is a String then it 
+      #   will be passed to the constructor of the RSA class. This must be at 
+      #   least 2048 bits to be compliant with the JWA specification.
       def initialize(key)
-        super(512, key)
+        super(512, make_key(key))
       end
     end
 

data/lib/sandal/util.rb

@@ -1,43 +1,62 @@
 require 'base64'
 
 module Sandal
-  # Implements some JWT utility functions. Shouldn't be needed by most people but may
-  # be useful if you're developing an extension to the library.
+  # @private
+  # Implements some JWT utility functions. Shouldn't be needed by most people 
+  # but may be useful if you're developing an extension to the library.
   module Util
+
+    private
     
-    # A string equality function which doesn't short-circuit the equality check to help
-    # protect against timing attacks.
+    # A string equality function that compares Unicode codepoints, and also 
+    # doesn't short-circuit the equality check to help protect against timing 
+    # attacks.
     #--
-    # See http://rdist.root.org/2009/05/28/timing-attack-in-google-keyczar-library/
-    def self.secure_equals(a, b)
-      if a.nil? && b.nil?
-        true
-      elsif a.nil? || b.nil? || a.bytesize != b.bytesize
-        false
-      else
-        result = a.bytes.zip(b.bytes).reduce(0) { |memo, (b1, b2)| memo |= (b1 ^ b2) }
-        result == 0
-      end
+    # http://rdist.root.org/2009/05/28/timing-attack-in-google-keyczar-library/ 
+    # for more info about timing attacks.
+    #++
+    #
+    # @param a [String] The first string.
+    # @param b [String] The second string.
+    # @return [Boolean] true if the strings are equal; otherwise false.
+    def jwt_strings_equal?(a, b)
+      return true if a.object_id == b.object_id
+      return false if a.nil? || b.nil? || a.length != b.length
+      a.codepoints.zip(b.codepoints).reduce(0) { |r, (a, b)| r |= a ^ b } == 0
     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{=+$}, '')
+    def jwt_base64_encode(s)
+      Base64.urlsafe_encode64(s).gsub(/=+$/, '')
     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?('=')
+    # @raise [ArgumentError] The base64 string is invalid or contains padding.
+    def jwt_base64_decode(s)
+      if s.end_with?('=')
+        raise ArgumentError, 'Base64 strings must not contain padding.'
+      end
+
       padding_length = (4 - (s.length % 4)) % 4
       padding = '=' * padding_length
-      Base64.urlsafe_decode64(s + padding)
+      input = s + padding
+      result = Base64.urlsafe_decode64(input)
+
+      # this bit is primarily for jruby which does a 'best effort' decode of
+      # whatever data it can if the input is invalid rather than raising an
+      # ArgumentError - as that could be a security issue we'll check that the 
+      # result contains all the data that was in the input string
+      unless input.length == (((result.length - 1) / 3) * 4) + 4
+        raise ArgumentError, 'Invalid base64.'
+      end
+      
+      result
     end
 
   end

data/lib/sandal/version.rb

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