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.

Remember Me:

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

In the authentication filter:

id, time = @verifier.verify(cookies[:remember_me])
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')

Confining messages to a specific purpose

By default any message can be used throughout your app. But they can also be confined to a specific :purpose.

token = @verifier.generate("this is the chair", purpose: :login)

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

@verifier.verified(token, purpose: :login)    # => "this is the chair"
@verifier.verified(token, purpose: :shipping) # => nil
@verifier.verified(token)                     # => nil

@verifier.verify(token, purpose: :login)      # => "this is the chair"
@verifier.verify(token, purpose: :shipping)   # => ActiveSupport::MessageVerifier::InvalidSignature
@verifier.verify(token)                       # => ActiveSupport::MessageVerifier::InvalidSignature

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

token = @verifier.generate("the conversation is lively")
@verifier.verified(token, purpose: :scare_tactics) # => nil
@verifier.verified(token)                          # => "the conversation is lively"

@verifier.verify(token, purpose: :scare_tactics)   # => ActiveSupport::MessageVerifier::InvalidSignature
@verifier.verify(token)                            # => "the conversation is lively"

Making messages expire

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("parcel", expires_in: 1.month)
@verifier.generate("doowad", expires_at: Time.now.end_of_year)

Then the messages can be verified and returned up to the expire time. Thereafter, the verified method returns nil while verify raises ActiveSupport::MessageVerifier::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

Constants

SEPARATOR_LENGTH = SEPARATOR.length # :nodoc:

SEPARATOR = "--"

Attributes

Show files where this class is defined (1 file)
Register or log in to add new notes.
March 29, 2010
0 thanks

Wrong example

In the authentication filter example above, the time condition should be reversed: we only want to find the user if time is still in the future (because it’s the valid-until time).

So the example should look like this:

id, time = @verifier.verify(cookies[:remember_me])
if time > Time.now
  self.current_user = User.find(id)
end
August 14, 2011
0 thanks

Security issue

One thing to note about the code above is that it could have a security issue. If the user changes his/her password, the authentication token should expire. Hence, in a production scenario you should put in the password salt or something to allow the token to become invalidated.

May 4, 2014
0 thanks

Security

In regards to @aamer’s comment on including the password salt this is a bad idea. `ActiveSupport::MessageVerifier` is NOT encrypted so:

verifier = ActiveSupport::MessageVerifier.new('secret')
id = 'id'
salt = 'salt'
verifier.generate("#{id}-#{salt}") # "BAhJIgxpZC1zYWx0BjoGRVQ=--c880254708d18ce4a686bcd96a25cf0d2117e1e0"

Base64.decode64(token.split("--").first) # "...id-salt..."

Note how the salt and id are both exposed! Instead a different token (reset_passowrd_token) should be used.