edge badge

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 upto 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
Namespace
Methods
D
E
G
N
V
Class Public methods
new(secret, options = {})

Source: show | on GitHub 

# File activesupport/lib/active_support/message_verifier.rb, line 106
def initialize(secret, options = {})
  raise ArgumentError, "Secret should not be nil." unless secret
  @secret = secret
  @digest = options[:digest] || "SHA1"
  @serializer = options[:serializer] || Marshal
end
Instance Public methods
decode(data)

Source: show | on GitHub 

# File activesupport/lib/active_support/message_verifier.rb, line 196
def decode(data)
  ::Base64.strict_decode64(data)
end
encode(data)

Source: show | on GitHub 

# File activesupport/lib/active_support/message_verifier.rb, line 192
def encode(data)
  ::Base64.strict_encode64(data)
end
generate(value, expires_at: nil, expires_in: nil, purpose: nil)

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"

Source: show | on GitHub 

# File activesupport/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
generate_digest(data)

Source: show | on GitHub 

# File activesupport/lib/active_support/message_verifier.rb, line 200
def generate_digest(data)
  require "openssl" unless defined?(OpenSSL)
  OpenSSL::HMAC.hexdigest(OpenSSL::Digest.const_get(@digest).new, @secret, data)
end
valid_message?(signed_message)

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

Source: show | on GitHub 

# File activesupport/lib/active_support/message_verifier.rb, line 122
    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

    # 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, purpose: nil, **)
      if valid_message?(signed_message)
        begin
          data = signed_message.split("--".freeze)[0]
          message = Messages::Metadata.verify(decode(data), purpose)
          @serializer.load(message) if message
        rescue ArgumentError => argument_error
          return if argument_error.message.include?("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(*args)
      verified(*args) || 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, 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

    private
      def encode(data)
        ::Base64.strict_encode64(data)
      end

      def decode(data)
        ::Base64.strict_decode64(data)
      end

      def generate_digest(data)
        require "openssl" unless defined?(OpenSSL)
        OpenSSL::HMAC.hexdigest(OpenSSL::Digest.const_get(@digest).new, @secret, data)
      end
  end
end
verified(signed_message, purpose: nil, **)

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

Source: show | on GitHub 

# File activesupport/lib/active_support/message_verifier.rb, line 150
  def verified(signed_message, purpose: nil, **)
    if valid_message?(signed_message)
      begin
        data = signed_message.split("--".freeze)[0]
        message = Messages::Metadata.verify(decode(data), purpose)
        @serializer.load(message) if message
      rescue ArgumentError => argument_error
        return if argument_error.message.include?("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(*args)
    verified(*args) || 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, 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

  private
    def encode(data)
      ::Base64.strict_encode64(data)
    end

    def decode(data)
      ::Base64.strict_decode64(data)
    end

    def generate_digest(data)
      require "openssl" unless defined?(OpenSSL)
      OpenSSL::HMAC.hexdigest(OpenSSL::Digest.const_get(@digest).new, @secret, data)
    end
end
verify(*args)

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

Source: show | on GitHub 

# File activesupport/lib/active_support/message_verifier.rb, line 175
def verify(*args)
  verified(*args) || raise(InvalidSignature)
end