123456789_123456789_123456789_123456789_123456789_

Class: ActiveSupport::MessageVerifiers

Relationships & Source Files
Inherits: ActiveSupport::Messages::RotationCoordinator
  • ::Object
Defined in: activesupport/lib/active_support/message_verifiers.rb

Class Method Summary

Instance Method Summary

Constructor Details

.new(&secret_generator)

Initializes a new instance. secret_generator must accept a salt, and return a suitable secret (string). secret_generator may also accept arbitrary kwargs. If #rotate is called with any options matching those kwargs, those options will be passed to secret_generator instead of to the message verifier.

verifiers = ActiveSupport::MessageVerifiers.new do |salt, base:|
  MySecretGenerator.new(base).generate(salt)
end

verifiers.rotate(base: "...")
[ GitHub ]

  
# File 'activesupport/lib/active_support/message_verifiers.rb', line 31

rdoc_method :method: initialize

Instance Method Details

#[](salt)

Returns a MessageVerifier configured with a secret derived from the given salt, and options from #rotate. MessageVerifier instances will be memoized, so the same salt will return the same instance.

[ GitHub ]

  
# File 'activesupport/lib/active_support/message_verifiers.rb', line 47

rdoc_method :method: []

#[]=(salt, verifier)

Overrides a MessageVerifier instance associated with a given salt.

[ GitHub ]

  
# File 'activesupport/lib/active_support/message_verifiers.rb', line 55

rdoc_method :method: []=

#clear_rotations

Clears the list of option sets.

[ GitHub ]

  
# File 'activesupport/lib/active_support/message_verifiers.rb', line 113

rdoc_method :method: clear_rotations

#on_rotation(&callback)

Sets a callback to invoke when a message is verified using an option set other than the first.

For example, this callback could log each time it is called, and thus indicate whether old option sets are still in use or can be removed from rotation.

[ GitHub ]

  
# File 'activesupport/lib/active_support/message_verifiers.rb', line 119

rdoc_method :method: on_rotation

#rotate(**options)

Adds options to the list of option sets. Messages will be signed using the first set in the list. When verifying, however, each set will be tried, in order, until one succeeds.

Notably, the :secret_generator option can specify a different secret generator than the one initially specified. The secret generator must respond to call, accept a salt, and return a suitable secret (string). The secret generator may also accept arbitrary kwargs.

If any options match the kwargs of the operative secret generator, those options will be passed to the secret generator instead of to the message verifier.

For fine-grained per-salt rotations, a block form is supported. The block will receive the salt, and should return an appropriate options ::Hash. The block may also return nil to indicate that the rotation does not apply to the given salt. For example:

verifiers = ActiveSupport::MessageVerifiers.new { ... }

verifiers.rotate do |salt|
  case salt
  when :foo
    { serializer: JSON, url_safe: true }
  when :bar
    { serializer: Marshal, url_safe: true }
  end
end

verifiers.rotate(serializer: Marshal, url_safe: false)

# Uses `serializer: JSON, url_safe: true`.
# Falls back to `serializer: Marshal, url_safe: false`.
verifiers[:foo]

# Uses `serializer: Marshal, url_safe: true`.
# Falls back to `serializer: Marshal, url_safe: false`.
verifiers[:bar]

# Uses `serializer: Marshal, url_safe: false`.
verifiers[:baz]
[ GitHub ]

  
# File 'activesupport/lib/active_support/message_verifiers.rb', line 61

rdoc_method :method: rotate

#rotate_defaults

Invokes #rotate with the default options.

[ GitHub ]

  
# File 'activesupport/lib/active_support/message_verifiers.rb', line 107

rdoc_method :method: rotate_defaults