5117da2b65
Before: ```ruby ActiveSupport::MessageVerifier.new(secret).inspect "#<ActiveSupport::MessageVerifier:0x0000000104888038 ... @secret=\"\\xAF\\bFh]LV}q\\nl\\xB2U\\xB3 ... >" ActiveSupport::KeyGenerator.new(secret).inspect "#<ActiveSupport::KeyGenerator:0x0000000104888038 ... @secret=\"\\xAF\\bFh]LV}q\\nl\\xB2U\\xB3 ... >" ``` After: ```ruby ActiveSupport::MessageVerifier::Aes256Gcm(secret).inspect "#<ActiveSupport::MessageVerifier:0x0000000104888038>" ActiveSupport::KeyGenerator::Aes256Gcm(secret).inspect "#<ActiveSupport::KeyGenerator:0x0000000104888038>" ```
357 lines
15 KiB
Ruby
357 lines
15 KiB
Ruby
# frozen_string_literal: true
|
|
|
|
require "openssl"
|
|
require "base64"
|
|
require "active_support/core_ext/object/blank"
|
|
require "active_support/security_utils"
|
|
require "active_support/messages/codec"
|
|
require "active_support/messages/rotator"
|
|
|
|
module ActiveSupport
|
|
# = Active Support Message Verifier
|
|
#
|
|
# +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}[link:classes/Rails/Application.html#method-i-message_verifier].
|
|
#
|
|
# 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
|
|
# +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)
|
|
class MessageVerifier < Messages::Codec
|
|
prepend Messages::Rotator
|
|
|
|
class InvalidSignature < StandardError; end
|
|
|
|
SEPARATOR = "--" # :nodoc:
|
|
SEPARATOR_LENGTH = SEPARATOR.length # :nodoc:
|
|
|
|
# Initialize a new MessageVerifier with a secret for the signature.
|
|
#
|
|
# ==== Options
|
|
#
|
|
# [+:digest+]
|
|
# Digest used for signing. The default is <tt>"SHA1"</tt>. See
|
|
# +OpenSSL::Digest+ for alternatives.
|
|
#
|
|
# [+:serializer+]
|
|
# The serializer used to serialize message data. You can specify any
|
|
# object that responds to +dump+ and +load+, or you can choose from
|
|
# several preconfigured serializers: +:marshal+, +:json_allow_marshal+,
|
|
# +:json+, +:message_pack_allow_marshal+, +:message_pack+.
|
|
#
|
|
# The preconfigured serializers include a fallback mechanism to support
|
|
# multiple deserialization formats. For example, the +:marshal+ serializer
|
|
# will serialize using +Marshal+, but can deserialize using +Marshal+,
|
|
# ActiveSupport::JSON, or ActiveSupport::MessagePack. This makes it easy
|
|
# to migrate between serializers.
|
|
#
|
|
# The +:marshal+, +:json_allow_marshal+, and +:message_pack_allow_marshal+
|
|
# serializers support deserializing using +Marshal+, but the others do
|
|
# not. Beware that +Marshal+ is a potential vector for deserialization
|
|
# attacks in cases where a message signing secret has been leaked. <em>If
|
|
# possible, choose a serializer that does not support +Marshal+.</em>
|
|
#
|
|
# The +:message_pack+ and +:message_pack_allow_marshal+ serializers use
|
|
# ActiveSupport::MessagePack, which can roundtrip some Ruby types that are
|
|
# not supported by JSON, and may provide improved performance. However,
|
|
# these require the +msgpack+ gem.
|
|
#
|
|
# When using \Rails, the default depends on +config.active_support.message_serializer+.
|
|
# Otherwise, the default is +:marshal+.
|
|
#
|
|
# [+:url_safe+]
|
|
# By default, MessageVerifier generates RFC 4648 compliant strings which are
|
|
# not URL-safe. In other words, they can contain "+" and "/". If you want to
|
|
# generate URL-safe strings (in compliance with "Base 64 Encoding with URL
|
|
# and Filename Safe Alphabet" in RFC 4648), you can pass +true+.
|
|
#
|
|
# [+:force_legacy_metadata_serializer+]
|
|
# Whether to use the legacy metadata serializer, which serializes the
|
|
# message first, then wraps it in an envelope which is also serialized. This
|
|
# was the default in \Rails 7.0 and below.
|
|
#
|
|
# If you don't pass a truthy value, the default is set using
|
|
# +config.active_support.use_message_serializer_for_metadata+.
|
|
def initialize(secret, **options)
|
|
raise ArgumentError, "Secret should not be nil." unless secret
|
|
super(**options)
|
|
@secret = secret
|
|
@digest = options[:digest]&.to_s || "SHA1"
|
|
end
|
|
|
|
# Checks if a signed message could have been generated by signing an object
|
|
# with the +MessageVerifier+'s secret.
|
|
#
|
|
# verifier = ActiveSupport::MessageVerifier.new("secret")
|
|
# signed_message = verifier.generate("signed 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?(message)
|
|
!!catch_and_ignore(:invalid_message_format) { extract_encoded(message) }
|
|
end
|
|
|
|
# Decodes the signed message using the +MessageVerifier+'s secret.
|
|
#
|
|
# verifier = ActiveSupport::MessageVerifier.new("secret")
|
|
#
|
|
# signed_message = verifier.generate("signed message")
|
|
# verifier.verified(signed_message) # => "signed message"
|
|
#
|
|
# Returns +nil+ if the message was not signed with the same secret.
|
|
#
|
|
# other_verifier = ActiveSupport::MessageVerifier.new("different_secret")
|
|
# 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
|
|
#
|
|
# ==== Options
|
|
#
|
|
# [+:purpose+]
|
|
# The purpose that the message was generated with. If the purpose does not
|
|
# match, +verified+ will return +nil+.
|
|
#
|
|
# message = verifier.generate("hello", purpose: "greeting")
|
|
# verifier.verified(message, purpose: "greeting") # => "hello"
|
|
# verifier.verified(message, purpose: "chatting") # => nil
|
|
# verifier.verified(message) # => nil
|
|
#
|
|
# message = verifier.generate("bye")
|
|
# verifier.verified(message) # => "bye"
|
|
# verifier.verified(message, purpose: "greeting") # => nil
|
|
#
|
|
def verified(message, **options)
|
|
catch_and_ignore :invalid_message_format do
|
|
catch_and_raise :invalid_message_serialization do
|
|
catch_and_ignore :invalid_message_content do
|
|
read_message(message, **options)
|
|
end
|
|
end
|
|
end
|
|
end
|
|
|
|
# Decodes the signed message using the +MessageVerifier+'s secret.
|
|
#
|
|
# verifier = ActiveSupport::MessageVerifier.new("secret")
|
|
# signed_message = verifier.generate("signed message")
|
|
#
|
|
# verifier.verify(signed_message) # => "signed message"
|
|
#
|
|
# Raises +InvalidSignature+ if the message was not signed with the same
|
|
# secret or was not Base64-encoded.
|
|
#
|
|
# other_verifier = ActiveSupport::MessageVerifier.new("different_secret")
|
|
# other_verifier.verify(signed_message) # => ActiveSupport::MessageVerifier::InvalidSignature
|
|
#
|
|
# ==== Options
|
|
#
|
|
# [+:purpose+]
|
|
# The purpose that the message was generated with. If the purpose does not
|
|
# match, +verify+ will raise ActiveSupport::MessageVerifier::InvalidSignature.
|
|
#
|
|
# message = verifier.generate("hello", purpose: "greeting")
|
|
# verifier.verify(message, purpose: "greeting") # => "hello"
|
|
# verifier.verify(message, purpose: "chatting") # => raises InvalidSignature
|
|
# verifier.verify(message) # => raises InvalidSignature
|
|
#
|
|
# message = verifier.generate("bye")
|
|
# verifier.verify(message) # => "bye"
|
|
# verifier.verify(message, purpose: "greeting") # => raises InvalidSignature
|
|
#
|
|
def verify(message, **options)
|
|
catch_and_raise :invalid_message_format, as: InvalidSignature do
|
|
catch_and_raise :invalid_message_serialization do
|
|
catch_and_raise :invalid_message_content, as: InvalidSignature do
|
|
read_message(message, **options)
|
|
end
|
|
end
|
|
end
|
|
end
|
|
|
|
# Generates a signed message for the provided value.
|
|
#
|
|
# The message is signed with the +MessageVerifier+'s secret.
|
|
# Returns Base64-encoded message joined with the generated signature.
|
|
#
|
|
# verifier = ActiveSupport::MessageVerifier.new("secret")
|
|
# verifier.generate("signed message") # => "BAhJIhNzaWduZWQgbWVzc2FnZQY6BkVU--f67d5f27c3ee0b8483cebf2103757455e947493b"
|
|
#
|
|
# ==== Options
|
|
#
|
|
# [+:expires_at+]
|
|
# The datetime at which the message expires. After this datetime,
|
|
# verification of the message will fail.
|
|
#
|
|
# message = verifier.generate("hello", expires_at: Time.now.tomorrow)
|
|
# verifier.verified(message) # => "hello"
|
|
# # 24 hours later...
|
|
# verifier.verified(message) # => nil
|
|
# verifier.verify(message) # => raises ActiveSupport::MessageVerifier::InvalidSignature
|
|
#
|
|
# [+:expires_in+]
|
|
# The duration for which the message is valid. After this duration has
|
|
# elapsed, verification of the message will fail.
|
|
#
|
|
# message = verifier.generate("hello", expires_in: 24.hours)
|
|
# verifier.verified(message) # => "hello"
|
|
# # 24 hours later...
|
|
# verifier.verified(message) # => nil
|
|
# verifier.verify(message) # => raises ActiveSupport::MessageVerifier::InvalidSignature
|
|
#
|
|
# [+:purpose+]
|
|
# The purpose of the message. If specified, the same purpose must be
|
|
# specified when verifying the message; otherwise, verification will fail.
|
|
# (See #verified and #verify.)
|
|
def generate(value, **options)
|
|
create_message(value, **options)
|
|
end
|
|
|
|
def create_message(value, **options) # :nodoc:
|
|
sign_encoded(encode(serialize_with_metadata(value, **options)))
|
|
end
|
|
|
|
def read_message(message, **options) # :nodoc:
|
|
deserialize_with_metadata(decode(extract_encoded(message)), **options)
|
|
end
|
|
|
|
def inspect # :nodoc:
|
|
"#<#{self.class.name}:#{'%#016x' % (object_id << 1)}>"
|
|
end
|
|
|
|
private
|
|
def sign_encoded(encoded)
|
|
digest = generate_digest(encoded)
|
|
encoded << SEPARATOR << digest
|
|
end
|
|
|
|
def extract_encoded(signed)
|
|
if signed.nil? || !signed.valid_encoding?
|
|
throw :invalid_message_format, "invalid message string"
|
|
end
|
|
|
|
if separator_index = separator_index_for(signed)
|
|
encoded = signed[0, separator_index]
|
|
digest = signed[separator_index + SEPARATOR_LENGTH, digest_length_in_hex]
|
|
end
|
|
|
|
unless digest_matches_data?(digest, encoded)
|
|
throw :invalid_message_format, "mismatched digest"
|
|
end
|
|
|
|
encoded
|
|
end
|
|
|
|
def generate_digest(data)
|
|
OpenSSL::HMAC.hexdigest(@digest, @secret, data)
|
|
end
|
|
|
|
def digest_length_in_hex
|
|
# In hexadecimal (AKA base16) it takes 4 bits to represent a character,
|
|
# hence we multiply the digest's length (in bytes) by 8 to get it in
|
|
# bits and divide by 4 to get its number of characters it hex. Well, 8
|
|
# divided by 4 is 2.
|
|
@digest_length_in_hex ||= OpenSSL::Digest.new(@digest).digest_length * 2
|
|
end
|
|
|
|
def separator_at?(signed_message, index)
|
|
signed_message[index, SEPARATOR_LENGTH] == SEPARATOR
|
|
end
|
|
|
|
def separator_index_for(signed_message)
|
|
index = signed_message.length - digest_length_in_hex - SEPARATOR_LENGTH
|
|
index unless index.negative? || !separator_at?(signed_message, index)
|
|
end
|
|
|
|
def digest_matches_data?(digest, data)
|
|
data.present? && digest.present? && ActiveSupport::SecurityUtils.secure_compare(digest, generate_digest(data))
|
|
end
|
|
end
|
|
end
|