123456789_123456789_123456789_123456789_123456789_

Class: ActiveSupport::MessageEncryptors

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Messages::RotationCoordinator
Instance Chain:
self, Messages::RotationCoordinator
Inherits: ActiveSupport::Messages::RotationCoordinator
Defined in: activesupport/lib/active_support/message_encryptors.rb

Class Method Summary

Messages::RotationCoordinator - Inherited

.new

Instance Attribute Summary

Messages::RotationCoordinator - Inherited

#transitional

Instance Method Summary

Messages::RotationCoordinator - Inherited

#[], #[]=, #clear_rotations, #on_rotation, #rotate, #rotate_defaults, #build, #build_with_rotations, #changing_configuration!, #normalize_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: "...")
[ GitHub ] 

  


# 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.


  



  [ GitHub ]


  

  


# File 'activesupport/lib/active_support/message_encryptors.rb', line 48



rdoc_method :method: []


  








  

    #[]=(salt, encryptor)    



  

    

Overrides a MessageEncryptor instance associated with a given salt.


  



  [ GitHub ]


  

  


# File 'activesupport/lib/active_support/message_encryptors.rb', line 56



rdoc_method :method: []=


  








  

    #build(salt, secret_generator:, secret_generator_options:, **options)   (private)
  

  [ GitHub ]


  

  


# File 'activesupport/lib/active_support/message_encryptors.rb', line 135



def build(salt, secret_generator:, secret_generator_options:, **options)
  secret_length = MessageEncryptor.key_len(*options[:cipher])
  secret = secret_generator.call(salt, secret_length: secret_length, **secret_generator_options)
  MessageEncryptor.new(*Array(secret), **options)
end


  








  

    #clear_rotations    



  

    

Clears the list of option sets.


  



  [ GitHub ]


  

  


# 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.


  



  [ GitHub ]


  

  


# 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 :bar
    { 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[:bar]

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


  





  


  [ GitHub ]


  

  


# File 'activesupport/lib/active_support/message_encryptors.rb', line 62



rdoc_method :method: rotate


  








  

    #rotate_defaults    



  

    

Invokes #rotate with the default options.


  



  [ GitHub ]


  

  


# File 'activesupport/lib/active_support/message_encryptors.rb', line 111



rdoc_method :method: rotate_defaults