Class: ActiveSupport::MessageVerifier

MessageVerifier makes it easy to generate and verify messages which are signed to prevent tampering.

In a Rails application, you can use Rails.application.message_verifier to manage unique instances of verifiers for each use case. Learn more.

This is useful for cases like remember-me tokens and auto-unsubscribe links where the session store isn’t suitable or available.

First, generate a signed message:

cookies[:remember_me] = Rails.application.message_verifier(:remember_me).generate([@user.id, 2.weeks.from_now])

Later verify that message:

id, time = Rails.application.message_verifier(:remember_me).verify(cookies[:remember_me])
if time.future?
  self.current_user = User.find(id)
end

Confine messages to a specific purpose

It’s not recommended to use the same verifier for different purposes in your application. Doing so could allow a malicious actor to re-use a signed message to perform an unauthorized action. You can reduce this risk by confining signed messages to a specific :purpose.

token = @verifier.generate("signed message", purpose: :login)

Then that same purpose must be passed when verifying to get the data back out:

@verifier.verified(token, purpose: :login)    # => "signed message"
@verifier.verified(token, purpose: :shipping) # => nil
@verifier.verified(token)                     # => nil

@verifier.verify(token, purpose: :login)      # => "signed message"
@verifier.verify(token, purpose: :shipping)   # => raises ActiveSupport::MessageVerifier::InvalidSignature
@verifier.verify(token)                       # => raises ActiveSupport::MessageVerifier::InvalidSignature

Likewise, if a message has no purpose it won’t be returned when verifying with a specific purpose.

token = @verifier.generate("signed message")
@verifier.verified(token, purpose: :redirect) # => nil
@verifier.verified(token)                     # => "signed message"

@verifier.verify(token, purpose: :redirect)   # => raises ActiveSupport::MessageVerifier::InvalidSignature
@verifier.verify(token)                       # => "signed message"

Expiring messages

By default messages last forever and verifying one year from now will still return the original value. But messages can be set to expire at a given time with :expires_in or :expires_at.

@verifier.generate("signed message", expires_in: 1.month)
@verifier.generate("signed message", expires_at: Time.now.end_of_year)

Messages can then be verified and returned until expiry. Thereafter, the #verified method returns nil while #verify raises InvalidSignature.

Rotating keys

MessageVerifier also supports rotating out old configurations by falling back to a stack of verifiers. Call rotate to build and add a verifier so either #verified or #verify will also try verifying with the fallback.

By default any rotated verifiers use the values of the primary verifier unless specified otherwise.

You’d give your verifier the new defaults:

verifier = ActiveSupport::MessageVerifier.new(@secret, digest: "SHA512", serializer: JSON)

Then gradually rotate the old values out by adding them as fallbacks. Any message generated with the old values will then work until the rotation is removed.

verifier.rotate(old_secret)          # Fallback to an old secret instead of @secret.
verifier.rotate(digest: "SHA256")    # Fallback to an old digest instead of SHA512.
verifier.rotate(serializer: Marshal) # Fallback to an old serializer instead of JSON.

Though the above would most likely be combined into one rotation:

verifier.rotate(old_secret, digest: "SHA256", serializer: Marshal)