1 files changed, 62 insertions, 6 deletions

diff --git a/activesupport/lib/active_support/message_verifier.rb b/activesupport/lib/active_support/message_verifier.rb
index a8a8de5672..d16c1c629b 100644
--- a/activesupport/lib/active_support/message_verifier.rb
+++ b/activesupport/lib/active_support/message_verifier.rb
@@ -34,22 +34,78 @@ module ActiveSupport
       @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.blank?
 
       data, digest = signed_message.split("--")
-      if data.present? && digest.present? && ActiveSupport::SecurityUtils.secure_compare(digest, generate_digest(data))
+      data.present? && digest.present? && ActiveSupport::SecurityUtils.secure_compare(digest, generate_digest(data))
+    end
+
+    # 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("--")[0]
           @serializer.load(decode(data))
         rescue ArgumentError => argument_error
-          raise InvalidSignature if argument_error.message =~ %r{invalid base64}
+          return if argument_error.message =~ %r{invalid base64}
           raise
         end
-      else
-        raise InvalidSignature
       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.verified(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 = encode(@serializer.dump(value))
       "#{data}--#{generate_digest(data)}"