Merge pull request rails#44179 from jonathanhefner/add-message_verifiers-message_encryptors

Add `MessageVerifiers` and `MessageEncryptors` classes

Author: jonathanhefner

activesupport/CHANGELOG.md

@@ -1,3 +1,23 @@
+*   Add `Rails.application.message_verifiers` as a central point to configure
+    and create message verifiers for an application.
+
+    This allows applications to, for example, rotate old `secret_key_base`
+    values:
+
+    ```ruby
+    config.before_initialize do |app|
+      app.message_verifiers.rotate(secret_key_base: "old secret_key_base")
+    end
+    ```
+
+    And for libraries to create preconfigured message verifiers:
+
+    ```ruby
+    ActiveStorage.verifier = Rails.application.message_verifiers["ActiveStorage"]
+    ```
+
+    *Jonathan Hefner*
+
 *   Add `assert_error_reported` and `assert_no_error_reported`
 
     Allows to easily asserts an error happened but was handled

activesupport/lib/active_support.rb

@@ -69,7 +69,9 @@ module ActiveSupport
     autoload :JsonWithMarshalFallback
     autoload :KeyGenerator
     autoload :MessageEncryptor
+    autoload :MessageEncryptors
     autoload :MessageVerifier
+    autoload :MessageVerifiers
     autoload :Multibyte
     autoload :NumberHelper
     autoload :OptionMerger

activesupport/lib/active_support/message_encryptors.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "active_support/messages/rotation_coordinator"
+
+module ActiveSupport
+  class MessageEncryptors < Messages::RotationCoordinator
+    ##
+    # :method: initialize
+    # :call-seq: initialize(&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: "...")
+
+    ##
+    # :method: []
+    # :call-seq: [](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.
+
+    ##
+    # :method: []=
+    # :call-seq: []=(salt, encryptor)
+    #
+    # Overrides a MessageEncryptor instance associated with a given +salt+.
+
+    ##
+    # :method: rotate
+    # :call-seq: rotate(**options)
+    #
+    # 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.
+
+    ##
+    # :method: rotate_defaults
+    # :call-seq: rotate_defaults
+    #
+    # Invokes #rotate with the default options.
+
+    ##
+    # :method: clear_rotations
+    # :call-seq: clear_rotations
+    #
+    # Clears the list of option sets.
+
+    ##
+    # :method: on_rotation
+    # :call-seq: 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.
+
+    private
+      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
+  end
+end

activesupport/lib/active_support/message_verifiers.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "active_support/messages/rotation_coordinator"
+
+module ActiveSupport
+  class MessageVerifiers < Messages::RotationCoordinator
+    ##
+    # :method: initialize
+    # :call-seq: initialize(&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: "...")
+
+    ##
+    # :method: []
+    # :call-seq: [](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.
+
+    ##
+    # :method: []=
+    # :call-seq: []=(salt, verifier)
+    #
+    # Overrides a MessageVerifier instance associated with a given +salt+.
+
+    ##
+    # :method: rotate
+    # :call-seq: 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.
+
+    ##
+    # :method: rotate_defaults
+    # :call-seq: rotate_defaults
+    #
+    # Invokes #rotate with the default options.
+
+    ##
+    # :method: clear_rotations
+    # :call-seq: clear_rotations
+    #
+    # Clears the list of option sets.
+
+    ##
+    # :method: on_rotation
+    # :call-seq: 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.
+
+    private
+      def build(salt, secret_generator:, secret_generator_options:, **options)
+        MessageVerifier.new(secret_generator.call(salt, **secret_generator_options), **options)
+      end
+  end
+end

activesupport/lib/active_support/messages/rotation_coordinator.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/slice"
+
+module ActiveSupport
+  module Messages
+    class RotationCoordinator # :nodoc:
+      def initialize(&secret_generator)
+        raise ArgumentError, "A secret generator block is required" unless secret_generator
+        @secret_generator = secret_generator
+        @rotate_options = []
+        @codecs = {}
+      end
+
+      def [](salt)
+        @codecs[salt] ||= build_with_rotations(salt.to_s)
+      end
+
+      def []=(salt, codec)
+        @codecs[salt] = codec
+      end
+
+      def rotate(**options)
+        changing_configuration!
+
+        options[:secret_generator] ||= @secret_generator
+        secret_generator_kwargs = options[:secret_generator].parameters.
+          filter_map { |type, name| name if type == :key || type == :keyreq }
+        options[:secret_generator_options] = options.extract!(*secret_generator_kwargs)
+
+        @rotate_options << options
+
+        self
+      end
+
+      def rotate_defaults
+        rotate()
+      end
+
+      def clear_rotations
+        changing_configuration!
+        @rotate_options.clear
+        self
+      end
+
+      def on_rotation(&callback)
+        changing_configuration!
+        @on_rotation = callback
+      end
+
+      private
+        def changing_configuration!
+          if @codecs.any?
+            raise <<~MESSAGE
+              Cannot change #{self.class} configuration after it has already been applied.
+
+              The configuration has been applied with the following salts:
+              #{@codecs.keys.map { |salt| "- #{salt.inspect}" }.join("\n")}
+            MESSAGE
+          end
+        end
+
+        def build_with_rotations(salt)
+          raise "No options have been configured" if @rotate_options.empty?
+          @rotate_options.map { |options| build(salt, **options, on_rotation: @on_rotation) }.reduce(&:fall_back_to)
+        end
+
+        def build(salt, secret_generator:, secret_generator_options:, **options)
+          raise NotImplementedError
+        end
+    end
+  end
+end

activesupport/lib/active_support/messages/rotator.rb

@@ -6,44 +6,44 @@ module Rotator # :nodoc:
       def initialize(*secrets, on_rotation: nil, **options)
         super(*secrets, **options)
 
-        @options   = options
+        @secrets = secrets
+        @options = options
         @rotations = []
         @on_rotation = on_rotation
       end
 
       def rotate(*secrets, **options)
-        @rotations << build_rotation(*secrets, @options.merge(options))
+        fall_back_to build_rotation(*secrets, **options)
       end
 
-      module Encryptor
+      def fall_back_to(fallback)
+        @rotations << fallback
+        self
+      end
+
+      module Encryptor # :nodoc:
         include Rotator
 
         def decrypt_and_verify(*args, on_rotation: @on_rotation, **options)
           super
         rescue MessageEncryptor::InvalidMessage, MessageVerifier::InvalidSignature
           run_rotations(on_rotation) { |encryptor| encryptor.decrypt_and_verify(*args, **options) } || raise
         end
-
-        private
-          def build_rotation(secret = @secret, sign_secret = @sign_secret, options)
-            self.class.new(secret, sign_secret, **options)
-          end
       end
 
-      module Verifier
+      module Verifier # :nodoc:
         include Rotator
 
         def verified(*args, on_rotation: @on_rotation, **options)
           super || run_rotations(on_rotation) { |verifier| verifier.verified(*args, **options) }
         end
-
-        private
-          def build_rotation(secret = @secret, options)
-            self.class.new(secret, **options)
-          end
       end
 
       private
+        def build_rotation(*secrets, **options)
+          self.class.new(*secrets, *@secrets.drop(secrets.length), **@options, **options)
+        end
+
         def run_rotations(on_rotation)
           @rotations.find do |rotation|
             if message = yield(rotation) rescue next

activesupport/lib/active_support/secure_compare_rotator.rb

@@ -44,7 +44,7 @@ def secure_compare!(other_value, on_rotation: @on_rotation)
     end
 
     private
-      def build_rotation(previous_value, _options)
+      def build_rotation(previous_value, **_options)
         self.class.new(previous_value)
       end
   end

activesupport/test/message_encryptors_test.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "rotation_coordinator_tests"
+
+class MessageEncryptorsTest < ActiveSupport::TestCase
+  include RotationCoordinatorTests
+
+  test "can override secret generator" do
+    secret_generator = ->(salt, secret_length:) { salt[0] * secret_length }
+    coordinator = make_coordinator.rotate(secret_generator: secret_generator)
+
+    assert_equal "message", roundtrip("message", coordinator["salt"])
+    assert_nil roundtrip("message", @coordinator["salt"], coordinator["salt"])
+  end
+
+  test "supports arbitrary secret generator kwargs" do
+    secret_generator = ->(salt, secret_length:, foo:, bar: nil) { foo[bar] * secret_length }
+    coordinator = ActiveSupport::MessageEncryptors.new(&secret_generator)
+    coordinator.rotate(foo: "foo", bar: 0)
+
+    assert_equal "message", roundtrip("message", coordinator["salt"])
+  end
+
+  test "supports separate secrets for encryption and signing" do
+    secret_generator = proc { |*args, **kwargs| [SECRET_GENERATOR.call(*args, **kwargs), "signing secret"] }
+    coordinator = ActiveSupport::MessageEncryptors.new(&secret_generator)
+    coordinator.rotate_defaults
+
+    assert_equal "message", roundtrip("message", coordinator["salt"])
+    assert_nil roundtrip("message", @coordinator["salt"], coordinator["salt"])
+  end
+
+  private
+    SECRET_GENERATOR = proc { |salt, secret_length:| "".ljust(secret_length, salt) }
+
+    def make_coordinator
+      ActiveSupport::MessageEncryptors.new(&SECRET_GENERATOR)
+    end
+
+    def roundtrip(message, encryptor, decryptor = encryptor)
+      decryptor.decrypt_and_verify(encryptor.encrypt_and_sign(message))
+    rescue ActiveSupport::MessageVerifier::InvalidSignature
+      nil
+    end
+end