Class: ActiveSupport::MessageEncryptors
Relationships & Source Files | |
Inherits: |
ActiveSupport::Messages::RotationCoordinator
|
Defined in: | activesupport/lib/active_support/message_encryptors.rb |
Class Method Summary
-
.new(&secret_generator)
constructor
Initializes a new instance.
Instance Method Summary
-
#[](salt)
Returns a
MessageEncryptor
configured with a secret derived from the givensalt
, and options from #rotate. -
#[]=(salt, encryptor)
Overrides a
MessageEncryptor
instance associated with a givensalt
. -
#clear_rotations
Clears the list of option sets.
-
#on_rotation(&callback)
Sets a callback to invoke when a message is decrypted using an option set other than the first.
-
#rotate(**options)
Adds
options
to the list of option sets. -
#rotate_defaults
Invokes #rotate with the default options.
Constructor Details
.new(&secret_generator)
Initializes a new instance. secret_generator
must accept a salt and a secret_length
kwarg, and return a suitable secret (string) or secrets (array of strings). secret_generator
may also accept other 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 encryptor.
encryptors = ActiveSupport::MessageEncryptors.new do |salt, secret_length:, base:|
MySecretGenerator.new(base).generate(salt, secret_length)
end
encryptors.rotate(base: "...")
# File 'activesupport/lib/active_support/message_encryptors.rb', line 31
rdoc_method :method: initialize
Instance Method Details
#[](salt)
Returns a MessageEncryptor
configured with a secret derived from the given salt
, and options from #rotate. MessageEncryptor
instances will be memoized, so the same salt
will return the same instance.
# File 'activesupport/lib/active_support/message_encryptors.rb', line 48
rdoc_method :method: []
#[]=(salt, encryptor)
Overrides a MessageEncryptor
instance associated with a given salt
.
# File 'activesupport/lib/active_support/message_encryptors.rb', line 56
rdoc_method :method: []=
#clear_rotations
Clears the list of option sets.
# File 'activesupport/lib/active_support/message_encryptors.rb', line 117
rdoc_method :method: clear_rotations
#on_rotation(&callback)
Sets a callback to invoke when a message is decrypted 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.
# File 'activesupport/lib/active_support/message_encryptors.rb', line 123
rdoc_method :method: on_rotation
#rotate(**options)
#rotate(&block)
Adds options
to the list of option sets. Messages
will be encrypted using the first set in the list. When decrypting, 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 a secret_length
kwarg, and return a suitable secret (string) or secrets (array of strings). The secret generator may also accept other 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 encryptor.
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:
encryptors = ActiveSupport::MessageEncryptors.new { ... }
encryptors.rotate do |salt|
case salt
when :foo
{ serializer: JSON, url_safe: true }
when :
{ serializer: Marshal, url_safe: true }
end
end
encryptors.rotate(serializer: Marshal, url_safe: false)
# Uses `serializer: JSON, url_safe: true`.
# Falls back to `serializer: Marshal, url_safe: false`.
encryptors[:foo]
# Uses `serializer: Marshal, url_safe: true`.
# Falls back to `serializer: Marshal, url_safe: false`.
encryptors[: ]
# Uses `serializer: Marshal, url_safe: false`.
encryptors[:baz]
# File 'activesupport/lib/active_support/message_encryptors.rb', line 62
rdoc_method :method: rotate
#rotate_defaults
Invokes #rotate with the default options.
# File 'activesupport/lib/active_support/message_encryptors.rb', line 111
rdoc_method :method: rotate_defaults