activesupport 3.1.0 → 5.0.0

data/lib/active_support/message_verifier.rb

@@ -1,12 +1,13 @@
-require 'active_support/base64'
+require 'base64'
 require 'active_support/core_ext/object/blank'
+require 'active_support/security_utils'
 
 module ActiveSupport
-  # +MessageVerifier+ makes it easy to generate and verify messages which are signed
-  # to prevent tampering.
+  # +MessageVerifier+ makes it easy to generate and verify messages which are
+  # signed to prevent tampering.
   #
-  # This is useful for cases like remember-me tokens and auto-unsubscribe links where the
-  # session store isn't suitable or available.
+  # This is useful for cases like remember-me tokens and auto-unsubscribe links
+  # where the session store isn't suitable or available.
   #
   # Remember Me:
   #   cookies[:remember_me] = @verifier.generate([@user.id, 2.weeks.from_now])
@@ -14,44 +15,115 @@ module ActiveSupport
   # In the authentication filter:
   #
   #   id, time = @verifier.verify(cookies[:remember_me])
-  #   if time < Time.now
+  #   if Time.now < time
   #     self.current_user = User.find(id)
   #   end
   #
+  # By default it uses Marshal to serialize the message. If you want to use
+  # another serialization method, you can set the serializer in the options
+  # hash upon initialization:
+  #
+  #   @verifier = ActiveSupport::MessageVerifier.new('s3Krit', serializer: YAML)
+  #
+  # +MessageVerifier+ creates HMAC signatures using SHA1 hash algorithm by default.
+  # If you want to use a different hash algorithm, you can change it by providing
+  # `:digest` key as an option while initializing the verifier:
+  #
+  #   @verifier = ActiveSupport::MessageVerifier.new('s3Krit', digest: 'SHA256')
   class MessageVerifier
     class InvalidSignature < StandardError; end
 
-    def initialize(secret, digest = 'SHA1')
+    def initialize(secret, options = {})
+      raise ArgumentError, 'Secret should not be nil.' unless secret
       @secret = secret
-      @digest = digest
+      @digest = options[:digest] || 'SHA1'
+      @serializer = options[:serializer] || Marshal
     end
 
-    def verify(signed_message)
-      raise InvalidSignature if signed_message.blank?
+    # Checks if a signed message could have been generated by signing an object
+    # with the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #   signed_message = verifier.generate 'a private message'
+    #   verifier.valid_message?(signed_message) # => true
+    #
+    #   tampered_message = signed_message.chop # editing the message invalidates the signature
+    #   verifier.valid_message?(tampered_message) # => false
+    def valid_message?(signed_message)
+      return if signed_message.nil? || !signed_message.valid_encoding? || signed_message.blank?
+
+      data, digest = signed_message.split("--".freeze)
+      data.present? && digest.present? && ActiveSupport::SecurityUtils.secure_compare(digest, generate_digest(data))
+    end
 
-      data, digest = signed_message.split("--")
-      if data.present? && digest.present? && secure_compare(digest, generate_digest(data))
-        Marshal.load(ActiveSupport::Base64.decode64(data))
-      else
-        raise InvalidSignature
+    # Decodes the signed message using the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #
+    #   signed_message = verifier.generate 'a private message'
+    #   verifier.verified(signed_message) # => 'a private message'
+    #
+    # Returns +nil+ if the message was not signed with the same secret.
+    #
+    #   other_verifier = ActiveSupport::MessageVerifier.new 'd1ff3r3nt-s3Krit'
+    #   other_verifier.verified(signed_message) # => nil
+    #
+    # Returns +nil+ if the message is not Base64-encoded.
+    #
+    #   invalid_message = "f--46a0120593880c733a53b6dad75b42ddc1c8996d"
+    #   verifier.verified(invalid_message) # => nil
+    #
+    # Raises any error raised while decoding the signed message.
+    #
+    #   incompatible_message = "test--dad7b06c94abba8d46a15fafaef56c327665d5ff"
+    #   verifier.verified(incompatible_message) # => TypeError: incompatible marshal file format
+    def verified(signed_message)
+      if valid_message?(signed_message)
+        begin
+          data = signed_message.split("--".freeze)[0]
+          @serializer.load(decode(data))
+        rescue ArgumentError => argument_error
+          return if argument_error.message =~ %r{invalid base64}
+          raise
+        end
       end
     end
 
+    # Decodes the signed message using the +MessageVerifier+'s secret.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #   signed_message = verifier.generate 'a private message'
+    #
+    #   verifier.verify(signed_message) # => 'a private message'
+    #
+    # Raises +InvalidSignature+ if the message was not signed with the same
+    # secret or was not Base64-encoded.
+    #
+    #   other_verifier = ActiveSupport::MessageVerifier.new 'd1ff3r3nt-s3Krit'
+    #   other_verifier.verify(signed_message) # => ActiveSupport::MessageVerifier::InvalidSignature
+    def verify(signed_message)
+      verified(signed_message) || raise(InvalidSignature)
+    end
+
+    # Generates a signed message for the provided value.
+    #
+    # The message is signed with the +MessageVerifier+'s secret. Without knowing
+    # the secret, the original value cannot be extracted from the message.
+    #
+    #   verifier = ActiveSupport::MessageVerifier.new 's3Krit'
+    #   verifier.generate 'a private message' # => "BAhJIhRwcml2YXRlLW1lc3NhZ2UGOgZFVA==--e2d724331ebdee96a10fb99b089508d1c72bd772"
     def generate(value)
-      data = ActiveSupport::Base64.encode64s(Marshal.dump(value))
+      data = encode(@serializer.dump(value))
       "#{data}--#{generate_digest(data)}"
     end
 
     private
-      # constant-time comparison algorithm to prevent timing attacks
-      def secure_compare(a, b)
-        return false unless a.bytesize == b.bytesize
-
-        l = a.unpack "C#{a.bytesize}"
+      def encode(data)
+        ::Base64.strict_encode64(data)
+      end
 
-        res = 0
-        b.each_byte { |byte| res |= byte ^ l.shift }
-        res == 0
+      def decode(data)
+        ::Base64.strict_decode64(data)
       end
 
       def generate_digest(data)