Class: ActiveSupport::MessageVerifier
- Defined in:
- lib/active_support/message_verifier.rb
Overview
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:
[:remember_me] = @verifier.generate([@user.id, 2.weeks.from_now])
In the authentication filter:
id, time = @verifier.verify([: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 to 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
Defined Under Namespace
Classes: InvalidSignature
Instance Method Summary collapse
-
#generate(value, expires_at: nil, expires_in: nil, purpose: nil) ⇒ Object
Generates a signed message for the provided value.
-
#initialize(secret, options = {}) ⇒ MessageVerifier
constructor
A new instance of MessageVerifier.
-
#valid_message?(signed_message) ⇒ Boolean
Checks if a signed message could have been generated by signing an object with the
MessageVerifier
‘s secret. -
#verified(signed_message, purpose: nil) ⇒ Object
Decodes the signed message using the
MessageVerifier
‘s secret. -
#verify(*args, **options) ⇒ Object
Decodes the signed message using the
MessageVerifier
‘s secret.
Methods included from ActiveSupport::Messages::Rotator
Constructor Details
#initialize(secret, options = {}) ⇒ MessageVerifier
Returns a new instance of MessageVerifier.
106 107 108 109 110 111 |
# File 'lib/active_support/message_verifier.rb', line 106 def initialize(secret, = {}) raise ArgumentError, "Secret should not be nil." unless secret @secret = secret @digest = [:digest] || "SHA1" @serializer = [:serializer] || Marshal end |
Instance Method Details
#generate(value, expires_at: nil, expires_in: nil, purpose: nil) ⇒ Object
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"
186 187 188 189 |
# File 'lib/active_support/message_verifier.rb', line 186 def generate(value, expires_at: nil, expires_in: nil, purpose: nil) data = encode(Messages::Metadata.wrap(@serializer.dump(value), expires_at: expires_at, expires_in: expires_in, purpose: purpose)) "#{data}--#{generate_digest(data)}" end |
#valid_message?(signed_message) ⇒ Boolean
Checks if a signed message could have been generated by signing an object with the MessageVerifier
‘s secret.
verifier = ActiveSupport::MessageVerifier.new 's3Krit'
= verifier.generate 'a private message'
verifier.() # => true
= .chop # editing the message invalidates the signature
verifier.() # => false
122 123 124 125 126 127 |
# File 'lib/active_support/message_verifier.rb', line 122 def () return if .nil? || !.valid_encoding? || .blank? data, digest = .split("--") data.present? && digest.present? && ActiveSupport::SecurityUtils.secure_compare(digest, generate_digest(data)) end |
#verified(signed_message, purpose: nil) ⇒ Object
Decodes the signed message using the MessageVerifier
‘s secret.
verifier = ActiveSupport::MessageVerifier.new 's3Krit'
= verifier.generate 'a private message'
verifier.verified() # => '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() # => nil
Returns nil
if the message is not Base64-encoded.
= "f--46a0120593880c733a53b6dad75b42ddc1c8996d"
verifier.verified() # => nil
Raises any error raised while decoding the signed message.
= "test--dad7b06c94abba8d46a15fafaef56c327665d5ff"
verifier.verified() # => TypeError: incompatible marshal file format
150 151 152 153 154 155 156 157 158 159 160 161 |
# File 'lib/active_support/message_verifier.rb', line 150 def verified(, purpose: nil, **) if () begin data = .split("--")[0] = Messages::Metadata.verify(decode(data), purpose) @serializer.load() if rescue ArgumentError => argument_error return if argument_error..include?("invalid base64") raise end end end |
#verify(*args, **options) ⇒ Object
Decodes the signed message using the MessageVerifier
‘s secret.
verifier = ActiveSupport::MessageVerifier.new 's3Krit'
= verifier.generate 'a private message'
verifier.verify() # => '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() # => ActiveSupport::MessageVerifier::InvalidSignature
175 176 177 |
# File 'lib/active_support/message_verifier.rb', line 175 def verify(*args, **) verified(*args, **) || raise(InvalidSignature) end |