aws_advanced_ruby_driver_wrapper 1.0.1 → 1.1.0

data/lib/aws_advanced_ruby_driver_wrapper/plugins/federated_auth/federated_auth_plugin.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require 'cgi/escape'
+require 'uri'
+require_relative 'base_saml_auth_plugin'
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module FederatedAuth
+      # Federated authentication against Active Directory Federation Services
+      # (AD FS). Scrapes the IdP-initiated sign-on page for its form, posts the
+      # federated credentials, and extracts the SAML assertion from the response.
+      # Everything else (STS exchange, token minting, caching, retry) is handled by
+      # BaseSamlAuthPlugin.
+      class FederatedAuthPlugin < BaseSamlAuthPlugin
+        TELEMETRY_PREFIX = 'federated'
+        TELEMETRY_FETCH_SAML = 'Fetch ADFS SAML Assertion'
+        INPUT_TAG_PATTERN = /<input([^<>]*)>/
+        FORM_ACTION_PATTERN = /<form[^<>]*?\baction="([^"]+)"/
+
+        # Fetches a SAML assertion from AD FS.
+        #
+        # @return [String] the base64 SAML assertion
+        def self.fetch_saml_assertion(idp_endpoint:, idp_port:, idp_username:, idp_password:,
+                                      rp_identifier:, ssl_insecure:, socket_timeout_sec:, connect_timeout_sec:, **_rest)
+          # One cookie jar shared by the sign-on GET and the credential POST, so cookies AD FS
+          # (or a load balancer in front of it) sets on the sign-on page are returned with the POST.
+          cookies = {}
+          http = lambda do |method, url, body: nil, headers: {}|
+            Utils::SamlUtils.http_request(
+              method:, url:, body:, headers:, ssl_insecure:, cookies:,
+              open_timeout_sec: connect_timeout_sec, read_timeout_sec: socket_timeout_sec
+            )
+          end
+
+          sign_in_url = "https://#{idp_endpoint}:#{idp_port}/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=#{rp_identifier}"
+          sign_in_body = require_body!(http.call(:get, sign_in_url), 'sign-on page')
+
+          action = form_action(sign_in_body)
+          post_url = action&.start_with?('/') ? "https://#{idp_endpoint}:#{idp_port}#{action}" : sign_in_url
+
+          params = form_parameters(sign_in_body, idp_username, idp_password)
+          response = http.call(:post, post_url,
+                               body: URI.encode_www_form(params),
+                               headers: { 'Content-Type' => 'application/x-www-form-urlencoded' })
+          content = require_body!(response, 'sign-on POST')
+
+          match = Utils::SamlUtils::SAML_RESPONSE_PATTERN.match(content)
+          unless match
+            # AD FS answers a rejected login with the sign-on page again (no SAMLResponse); the
+            # body is not included as it may contain sensitive markup.
+            raise Errors::SamlAuthError,
+                  'FederatedAuthPlugin: no SAML assertion in the AD FS response - check idp_username, ' \
+                  'idp_password, and idp_endpoint'
+          end
+
+          match[1]
+        end
+
+        def self.require_body!(response, what)
+          return response.body if response.is_a?(Net::HTTPSuccess)
+
+          raise Errors::SamlAuthError,
+                "FederatedAuthPlugin: AD FS #{what} request failed (#{response.code} #{response.message})"
+        end
+
+        def self.form_action(body)
+          match = FORM_ACTION_PATTERN.match(body)
+          match && unescape_html(match[1])
+        end
+
+        # Builds the POST parameters from the sign-on form's input tags, filling in
+        # the federated username/password and preserving every other hidden field.
+        def self.form_parameters(body, idp_username, idp_password)
+          params = []
+          seen = {}
+          body.scan(INPUT_TAG_PATTERN).flatten.each do |tag|
+            name = value_by_key(tag, 'name')
+            next if name.empty?
+
+            lower = name.downcase
+            next if seen[lower]
+
+            seen[lower] = true
+            value = value_by_key(tag, 'value')
+
+            if lower.include?('username')
+              params << [name, idp_username]
+            elsif lower.include?('authmethod')
+              params << [name, value] unless value.empty?
+            elsif lower.include?('password')
+              params << [name, idp_password]
+            else
+              params << [name, value]
+            end
+          end
+          params
+        end
+
+        def self.value_by_key(input, key)
+          match = /#{Regexp.quote(key)}\s*=\s*"(.*?)"/.match(input)
+          match ? unescape_html(match[1]) : ''
+        end
+
+        def self.unescape_html(html)
+          CGI.unescapeHTML(html)
+        end
+
+        private
+
+        def saml_fetch_options(saml_props, idp_username, idp_password)
+          super.merge(
+            idp_port: PropertyDefinition::IDP_PORT.get(saml_props),
+            rp_identifier: PropertyDefinition::RP_IDENTIFIER.get(saml_props)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/federated_auth/okta_auth_plugin.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License").
+#  You may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require 'cgi/escape'
+require 'json'
+require_relative 'base_saml_auth_plugin'
+
+module AwsAdvancedRubyDriverWrapper
+  module Plugins
+    module FederatedAuth
+      # Federated authentication against Okta. Authenticates to Okta's /authn API
+      # for a one-time session token, redeems it at the AWS app's SSO SAML endpoint
+      # for a SAML assertion, and then defers to BaseSamlAuthPlugin for the STS
+      # exchange, token minting, caching, and retry. Okta differs from AD FS only in
+      # configuration (it uses app_id, the AWS app configured on Okta) and in the
+      # shape of the IdP HTTP flow.
+      class OktaAuthPlugin < AwsAdvancedRubyDriverWrapper::Plugins::FederatedAuth::BaseSamlAuthPlugin
+        TELEMETRY_PREFIX = 'okta'
+        TELEMETRY_FETCH_SAML = 'Fetch OKTA SAML Assertion'
+        OKTA_AWS_APP_NAME = 'amazon_aws'
+        # Extracts the value attribute of the hidden SAMLResponse input regardless
+        # of attribute order.
+        SAML_INPUT_PATTERN = /<input[^>]*\bname="SAMLResponse"[^>]*>/i
+        VALUE_ATTR_PATTERN = /\bvalue="([^"]+)"/i
+
+        # Fetches a SAML assertion from Okta.
+        #
+        # @return [String] the base64 SAML assertion
+        def self.fetch_saml_assertion(idp_endpoint:, app_id:, idp_username:, idp_password:,
+                                      ssl_insecure:, socket_timeout_sec:, connect_timeout_sec:, **_rest)
+          http = lambda do |method, url, body: nil, headers: {}|
+            Utils::SamlUtils.http_request(
+              method:, url:, body:, headers:, ssl_insecure:,
+              open_timeout_sec: connect_timeout_sec, read_timeout_sec: socket_timeout_sec
+            )
+          end
+
+          session_token = session_token(http, idp_endpoint, idp_username, idp_password)
+          saml_url = "https://#{idp_endpoint}/app/#{OKTA_AWS_APP_NAME}/#{CGI.escape(app_id)}/sso/saml" \
+                     "?onetimetoken=#{CGI.escape(session_token)}"
+          response = http.call(:get, saml_url)
+          unless response.is_a?(Net::HTTPSuccess)
+            raise Errors::SamlAuthError,
+                  "OktaAuthPlugin: SAML request failed (#{response.code} #{response.message})"
+          end
+
+          tag = SAML_INPUT_PATTERN.match(response.body)
+          value = tag && VALUE_ATTR_PATTERN.match(tag[0])
+          raise Errors::SamlAuthError, 'OktaAuthPlugin: invalid SAML response from Okta' unless value
+
+          # The value attribute is HTML-entity-encoded (Okta encodes base64's trailing
+          # "=" padding, and "+" if present, as e.g. &#x3d; / &#x2b;); decode before
+          # handing the assertion to STS, matching FederatedAuthPlugin's AD FS flow.
+          CGI.unescapeHTML(value[1])
+        end
+
+        # Authenticates to Okta's /authn API and returns the one-time session token.
+        def self.session_token(http, idp_endpoint, idp_username, idp_password)
+          response = http.call(
+            :post, "https://#{idp_endpoint}/api/v1/authn",
+            body: JSON.generate(username: idp_username, password: idp_password),
+            headers: { 'Accept' => 'application/json', 'Content-Type' => 'application/json' }
+          )
+          unless response.is_a?(Net::HTTPSuccess)
+            raise Errors::SamlAuthError,
+                  "OktaAuthPlugin: Okta session token request failed (#{response.code} #{response.message})"
+          end
+
+          parsed = begin
+            JSON.parse(response.body)
+          rescue JSON::ParserError
+            nil
+          end
+          parsed = nil unless parsed.is_a?(Hash)
+          token = parsed && parsed['sessionToken']
+          if token.nil? || token.empty?
+            # Okta's `status` is a non-sensitive auth-state enum (e.g. MFA_REQUIRED,
+            # PASSWORD_EXPIRED, LOCKED_OUT); surface it for clarity. It never carries
+            # credentials or the session token itself.
+            status = parsed && parsed['status']
+            detail = status.is_a?(String) && !status.empty? ? " (status: #{status})" : ''
+            raise Errors::SamlAuthError, "OktaAuthPlugin: Okta did not return a session token#{detail}"
+          end
+
+          token
+        end
+
+        private
+
+        def required_identity(saml_props)
+          super + [['app_id', PropertyDefinition::APP_ID.get(saml_props)]]
+        end
+
+        def saml_fetch_options(saml_props, idp_username, idp_password)
+          super.merge(app_id: PropertyDefinition::APP_ID.get(saml_props))
+        end
+      end
+    end
+  end
+end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/gdb/gdb_failover_plugin.rb

@@ -38,6 +38,8 @@ module AwsAdvancedRubyDriverWrapper
       # when that endpoint carries a region. When +accessible_regions+ is set, hosts outside those
       # regions are never selected.
       class GdbFailoverPlugin < FailoverPlugin
+        TELEMETRY_FAILOVER = 'global database failover'
+
         def initialize(service_container, props = ::Concurrent::Map.new)
           super
 
@@ -176,6 +178,10 @@ module AwsAdvancedRubyDriverWrapper
             return
           end
 
+          with_failover_telemetry(TELEMETRY_FAILOVER) { failover_with_plan }
+        end
+
+        def failover_with_plan
           failover_start = Time.now
           failover_deadline = failover_start + @failover_timeout
           @regionless_hosts.clear
@@ -189,6 +195,25 @@ module AwsAdvancedRubyDriverWrapper
               "failover_timeout_sec=#{@failover_timeout}"
           end
 
+          writer_candidate, writer_region, mode = failover_plan
+          log_failover_plan(writer_candidate, writer_region, mode)
+          if mode == GdbFailoverMode::STRICT_WRITER
+            count_failover(@writer_failover_counters) { failover_to_writer(writer_candidate, writer_region, failover_deadline) }
+          else
+            count_failover(@reader_failover_counters) { failover_to_allowed_host(mode, failover_deadline) }
+          end
+        ensure
+          duration_ms = ((Time.now - failover_start) * 1000).round if failover_start
+          logger.debug { "Failover duration: #{duration_ms}ms" } if duration_ms
+        end
+
+        # Finds the writer the topology settled on, and the failover mode that applies to its region.
+        #
+        # When this fails, failover cannot start, and so it is not known whether it would have been a
+        # writer or a reader failover. It is counted as a failed writer failover.
+        #
+        # @return [Array(Host::HostInfo, String, Symbol)] the writer, its region, and the mode
+        def failover_plan
           # This is expected to return once the topology has stabilized, i.e. once the cluster
           # control plane has already chosen a new writer.
           unless host_service.force_refresh_host_list?(verify_writer: true, timeout_sec: @failover_timeout)
@@ -210,15 +235,11 @@ module AwsAdvancedRubyDriverWrapper
             mode = current_failover_mode(writer_region)
           end
 
-          log_failover_plan(writer_candidate, writer_region, mode)
-          if mode == GdbFailoverMode::STRICT_WRITER
-            failover_to_writer(writer_candidate, writer_region, failover_deadline)
-          else
-            failover_to_allowed_host(mode, failover_deadline)
-          end
-        ensure
-          duration_ms = ((Time.now - failover_start) * 1000).round if failover_start
-          logger.debug { "Failover duration: #{duration_ms}ms" } if duration_ms
+          [writer_candidate, writer_region, mode]
+        rescue StandardError
+          @writer_failover_counters.triggered.inc
+          @writer_failover_counters.failed.inc
+          raise
         end
 
         # Explains which mode was chosen, and what the plugin will do with it.

data/lib/aws_advanced_ruby_driver_wrapper/plugins/iam_auth_plugin.rb

@@ -41,6 +41,17 @@ module AwsAdvancedRubyDriverWrapper
         PropertyDefinition::IAM_EXPIRATION_SEC.validate!(expiration)
         service_container.storage_service.register(IAM_TOKEN_CACHE_NAME, ttl: expiration)
         @subscribed_methods = SUBSCRIBED_METHODS
+
+        @telemetry_factory = service_container.telemetry_factory
+        @fetch_token_counter = @telemetry_factory.create_counter('iam.fetch_token.count')
+        @telemetry_factory.create_gauge('iam.token_cache.size', &self.class.token_cache_size(service_container.storage_service))
+      end
+
+      # The callback of a token cache size gauge. It is built here rather than in an instance, because
+      # a gauge is kept for the whole process and a block built in an instance would keep that
+      # instance, and the connection it belongs to, alive with it.
+      def self.token_cache_size(storage_service)
+        -> { storage_service.size(IAM_TOKEN_CACHE_NAME) }
       end
 
       def connect(host_info, driver_props, _is_initial_connection, pipeline_callable)
@@ -128,8 +139,11 @@ module AwsAdvancedRubyDriverWrapper
       # and, when there is a cache key, caches it. Without a snapshot the provider is passed as is,
       # and signing fails for lack of credentials.
       def fetch_and_cache_token(region, host, port, user, credentials, cache_key, expiration)
-        token = Aws::RDS::AuthTokenGenerator.new(credentials: credentials || @credentials_provider)
-                                            .auth_token(region:, endpoint: "#{host}:#{port}", user_name: user)
+        @fetch_token_counter.inc
+        token = Utils::IamAuthUtils.generate_token(
+          region:, hostname: host, port:, user:, credentials_provider: credentials || @credentials_provider,
+          telemetry_factory: @telemetry_factory
+        )
         if cache_key
           @service_container.storage_service.set(
             IAM_TOKEN_CACHE_NAME, cache_key, Utils::IamAuthUtils.build_token_entry(token, expiration)

data/lib/aws_advanced_ruby_driver_wrapper/plugins/initial_connection_strategy_plugin.rb

@@ -20,6 +20,7 @@ require_relative '../host/host_role'
 require_relative '../host/host_availability'
 require_relative '../logging'
 require_relative '../property_definition'
+require_relative '../services/host_service'
 require_relative '../utils/accessible_regions'
 require_relative '../utils/rds_utils'
 require_relative '../utils/rds_url_type'
@@ -53,6 +54,7 @@ module AwsAdvancedRubyDriverWrapper
         @retry_interval_sec = PropertyDefinition::INITIAL_CONNECTION_RETRY_INTERVAL_SEC.get_float(props)
         @wait_for_topology_sec = PropertyDefinition::INITIAL_CONNECTION_WAIT_FOR_TOPOLOGY_SEC.get_float(props)
         @host_selector_strategy = PropertyDefinition::INITIAL_CONNECTION_HOST_SELECTOR_STRATEGY.get(props)
+        Services::HostService.validate_strategy!(@host_selector_strategy)
         @accessible_regions = Utils::AccessibleRegions.parse(props)
         @subscribed_methods = SUBSCRIBED_METHODS
 
@@ -323,7 +325,8 @@ module AwsAdvancedRubyDriverWrapper
         end
 
         host_service.select_host(available_hosts, target_role, @host_selector_strategy)
-      rescue StandardError
+      rescue StandardError => e
+        logger.warn("Failed to select a host using the '#{@host_selector_strategy}' host selection strategy: #{e.message}")
         nil
       end
 

data/lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/key_management_utility.rb

@@ -14,7 +14,7 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-require_relative '../../driver_dialects/mysql_driver_dialect'
+require_relative '../../driver_dialects/mysql2_driver_dialect'
 require_relative '../../driver_dialects/pg_driver_dialect'
 require_relative '../../logging'
 require_relative '../../property_definition'
@@ -324,7 +324,10 @@ module AwsAdvancedRubyDriverWrapper
         def dialect_for_connection(connection)
           name = connection.class.name.to_s
           return DriverDialects::PgDriverDialect.new if name.start_with?('PG::') || name.end_with?('WrapperPgConnection')
-          return DriverDialects::MysqlDriverDialect.new if name.start_with?('Mysql2::') || name.end_with?('WrapperMysql2Client')
+          return DriverDialects::Mysql2DriverDialect.new if name.start_with?('Mysql2::') || name.end_with?('WrapperMysql2Client')
+          if name == 'Trilogy' || name.end_with?('WrapperTrilogyClient')
+            raise ArgumentError, 'KMS encryption does not support the trilogy driver'
+          end
 
           raise ArgumentError,
                 "Cannot infer the driver dialect from #{name.empty? ? connection.class : name}; " \
@@ -334,7 +337,7 @@ module AwsAdvancedRubyDriverWrapper
         def dialect_for_driver(driver)
           case driver.to_sym
           when :postgresql, :pg then DriverDialects::PgDriverDialect.new
-          when :mysql2, :mysql then DriverDialects::MysqlDriverDialect.new
+          when :mysql2, :mysql then DriverDialects::Mysql2DriverDialect.new
           else raise ArgumentError, "Unknown driver #{driver.inspect}; use :postgresql or :mysql2"
           end
         end

data/lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/key_manager.rb

@@ -14,7 +14,6 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-require 'base64'
 require 'digest'
 require 'securerandom'
 require_relative '../../logging'
@@ -105,7 +104,7 @@ module AwsAdvancedRubyDriverWrapper
 
           plaintext = with_retry('DECRYPT_DATA_KEY') do
             response = @kms_client.decrypt(
-              ciphertext_blob: Base64.strict_decode64(encrypted_data_key.to_s.delete("\n")),
+              ciphertext_blob: strict_decode64(encrypted_data_key.to_s.delete("\n")),
               **(master_key_arn ? { key_id: master_key_arn } : {})
             )
             response.plaintext.dup.b
@@ -130,7 +129,7 @@ module AwsAdvancedRubyDriverWrapper
             response = @kms_client.generate_data_key(key_id: master_key_arn, key_spec: KMS_KEY_SPEC)
             GeneratedDataKey.new(
               plaintext: response.plaintext.dup.b,
-              encrypted_data_key: Base64.strict_encode64(response.ciphertext_blob),
+              encrypted_data_key: strict_encode64(response.ciphertext_blob),
               hmac_key: SecureRandom.bytes(HMAC_KEY_LENGTH)
             )
           end
@@ -272,11 +271,21 @@ module AwsAdvancedRubyDriverWrapper
         # @param encrypted_data_key [String]
         # @return [String]
         def data_key_cache_key(encrypted_data_key)
-          "#{DATA_KEY_CACHE_PREFIX}#{Base64.strict_encode64(Digest::SHA256.digest(encrypted_data_key.to_s))}"
+          "#{DATA_KEY_CACHE_PREFIX}#{strict_encode64(Digest::SHA256.digest(encrypted_data_key.to_s))}"
         end
 
         private
 
+        # Strict base64 (RFC 4648: no line breaks, padding required), using the encoding built into
+        # Array#pack rather than the base64 gem. Decoding raises ArgumentError on invalid input.
+        def strict_encode64(bytes)
+          [bytes].pack('m0')
+        end
+
+        def strict_decode64(encoded)
+          encoded.unpack1('m0')
+        end
+
         def authorize_master_key!(master_key_arn)
           return if @config.master_key_allowed?(master_key_arn)
 

data/lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/kms_encryption_plugin.rb

@@ -15,6 +15,7 @@
 #  limitations under the License.
 
 require 'concurrent'
+require_relative '../../driver_dialects/trilogy_driver_dialect'
 require_relative '../../logging'
 require_relative '../../ruby_method'
 require_relative '../../utils/parser/encryption_annotation_parser'
@@ -205,6 +206,12 @@ module AwsAdvancedRubyDriverWrapper
       # @param encryption_utility [Encryption::KmsEncryptionUtility, nil] a utility to use instead
       #   of building one
       def initialize(service_container, props = ::Concurrent::Map.new, encryption_utility: nil)
+        # Trilogy has no prepared statements, so a parameter could only reach the server written into the
+        # SQL, in plaintext, before it could be encrypted.
+        if service_container.dialect_service.driver_dialect.is_a?(DriverDialects::TrilogyDriverDialect)
+          raise Errors::EncryptionPluginError, 'The kms_encryption plugin does not support the trilogy driver'
+        end
+
         @service_container = service_container
         @encryption_utility = encryption_utility || Encryption::KmsEncryptionUtility.new(service_container, props)
         # Built up front so that a parser dependency the application has not installed (pg_query, on
@@ -586,9 +593,10 @@ module AwsAdvancedRubyDriverWrapper
       # @raise [Errors::MetadataError] when the statement writes a column the plugin has confirmed is
       #   encrypted with a value it cannot encrypt (see {#check_write})
       def parameter_columns(sql)
-        annotations = Utils::Parser::EncryptionAnnotationParser.parse_annotations(sql)
+        version = executable_comment_version
+        annotations = Utils::Parser::EncryptionAnnotationParser.parse_annotations(sql, server_version: version)
         stripped = stripped_sql(sql)
-        analysis = analysis_of(stripped)
+        analysis = analysis_of(stripped, version)
         write = write_statement?(analysis, stripped)
         inferred = analysis.parameter_column_names
         return {} if !write && annotations.empty? && inferred.empty?
@@ -607,9 +615,10 @@ module AwsAdvancedRubyDriverWrapper
       # that writes nothing, so it is reported as nothing having been read rather than as nothing
       # being there to read.
       #
+      # @param version [Integer, nil] see {#executable_comment_version}
       # @return [Utils::Parser::SqlParser::SqlAnalysisResult]
-      def analysis_of(sql)
-        sql_parser.analyze_sql(sql)
+      def analysis_of(sql, version)
+        sql_parser.analyze_sql(sql, server_version: version)
       rescue StandardError => e
         logger.warn("The statement could not be analysed: #{e.message}")
         Utils::Parser::SqlParser::SqlAnalysisResult.new(
@@ -693,8 +702,9 @@ module AwsAdvancedRubyDriverWrapper
       def column_configs(sql)
         return {} unless ready_for_statement?(sql)
 
-        annotations = Utils::Parser::EncryptionAnnotationParser.parse_annotations(sql)
-        tables = statement_tables(analysis_of(stripped_sql(sql)), annotations)
+        version = executable_comment_version
+        annotations = Utils::Parser::EncryptionAnnotationParser.parse_annotations(sql, server_version: version)
+        tables = statement_tables(analysis_of(stripped_sql(sql), version), annotations)
         return {} if tables.empty?
 
         # When two of the statement's tables encrypt a column of the same name, the first of them
@@ -837,6 +847,19 @@ module AwsAdvancedRubyDriverWrapper
         Utils::Parser::EncryptionAnnotationParser.strip_annotations(sql)
       end
 
+      # The version of the MySQL server the statement is sent to, which decides whether a versioned
+      # /*!80023 ... */ comment is part of the statement, and so which column each placeholder after it
+      # belongs to (see DriverDialects::DriverDialect#executable_comment_version). It is read from the
+      # connection every time rather than kept, since a failover or a blue/green switchover can move
+      # the connection to a server of another version.
+      #
+      # @return [Integer, nil] nil on PostgreSQL, which has no executable comments, and when the
+      #   connection cannot say
+      def executable_comment_version
+        @service_container.dialect_service.driver_dialect
+                          .executable_comment_version(@service_container.connection_service.current_connection)
+      end
+
       # -- Lazily built collaborators --
 
       # Builds the parts of the plugin that need a database connection, the first time a statement

data/lib/aws_advanced_ruby_driver_wrapper/plugins/kms_encryption/sql/trigger_mysql.sql

@@ -0,0 +1,108 @@
+DELIMITER $$
+
+-- HMAC-SHA256 built from SHA2(), which MySQL has no native HMAC for.
+DROP FUNCTION IF EXISTS hmac_sha256$$
+CREATE FUNCTION hmac_sha256(
+    message VARBINARY(65535),
+    key_data VARBINARY(64)
+)
+RETURNS VARBINARY(32)
+DETERMINISTIC
+NO SQL
+BEGIN
+    DECLARE block_size INT DEFAULT 64;  -- SHA-256 block size
+    DECLARE key_padded VARBINARY(64);
+    DECLARE ipad VARBINARY(64);
+    DECLARE opad VARBINARY(64);
+    DECLARE i INT DEFAULT 1;
+    DECLARE key_byte INT;
+
+    -- Reduce an over-long key to its hash, then zero-pad the key to the block size.
+    IF LENGTH(key_data) > block_size THEN
+        SET key_padded = CONCAT(UNHEX(SHA2(key_data, 256)), REPEAT(X'00', block_size - 32));
+    ELSE
+        SET key_padded = CONCAT(key_data, REPEAT(X'00', block_size - LENGTH(key_data)));
+    END IF;
+
+    -- ipad = key XOR 0x36 per byte, opad = key XOR 0x5C per byte, one raw byte at a time.
+    SET ipad = X'';
+    SET opad = X'';
+    WHILE i <= block_size DO
+        SET key_byte = ASCII(SUBSTRING(key_padded, i, 1));
+        SET ipad = CONCAT(ipad, UNHEX(LPAD(HEX(key_byte ^ 0x36), 2, '0')));
+        SET opad = CONCAT(opad, UNHEX(LPAD(HEX(key_byte ^ 0x5C), 2, '0')));
+        SET i = i + 1;
+    END WHILE;
+
+    RETURN UNHEX(SHA2(CONCAT(opad, UNHEX(SHA2(CONCAT(ipad, message), 256))), 256));
+END$$
+
+-- Verifies that a stored value carries a valid HMAC for the given HMAC key.
+DROP FUNCTION IF EXISTS verify_encrypted_data_hmac$$
+CREATE FUNCTION verify_encrypted_data_hmac(
+    data VARBINARY(65535),
+    hmac_key VARBINARY(32)
+)
+RETURNS BOOLEAN
+DETERMINISTIC
+NO SQL
+BEGIN
+    -- Minimum payload: 32 (HMAC) + 4 (key id) + 1 (type) + 12 (IV) + 0 (ciphertext) + 16 (GCM tag) = 65.
+    IF data IS NULL OR LENGTH(data) < 65 THEN
+        RETURN FALSE;
+    END IF;
+
+    RETURN SUBSTRING(data, 1, 32) = hmac_sha256(SUBSTRING(data, 33), hmac_key);
+END$$
+
+-- Called from a BEFORE INSERT trigger (and by the BEFORE UPDATE procedure) to reject a value that is
+-- not a valid kms_encryption payload. Replace SCHEMA_NAME with encryption_metadata_schema.
+-- The COMMENT records which version of this SQL is installed. Check it with:
+--   SELECT ROUTINE_COMMENT FROM information_schema.ROUTINES
+--    WHERE ROUTINE_SCHEMA = DATABASE() AND ROUTINE_NAME = 'validate_encrypted_data_hmac_before_insert';
+DROP PROCEDURE IF EXISTS validate_encrypted_data_hmac_before_insert$$
+CREATE PROCEDURE validate_encrypted_data_hmac_before_insert(
+    IN p_table_name VARCHAR(64),
+    IN p_column_name VARCHAR(64),
+    IN column_value VARBINARY(65535)
+)
+COMMENT 'aws-advanced-ruby-driver-wrapper kms_encryption trigger v1'
+BEGIN
+    DECLARE v_hmac_key VARBINARY(32);
+
+    IF column_value IS NOT NULL THEN
+        SELECT ks.hmac_key INTO v_hmac_key
+        FROM SCHEMA_NAME.encryption_metadata em
+        JOIN SCHEMA_NAME.key_storage ks ON em.key_id = ks.id
+        WHERE em.table_name = p_table_name
+          AND em.column_name = p_column_name
+        LIMIT 1;
+
+        IF v_hmac_key IS NULL THEN
+            SIGNAL SQLSTATE '45000'
+            SET MESSAGE_TEXT = 'No HMAC key is configured for the encrypted column';
+        END IF;
+
+        IF NOT verify_encrypted_data_hmac(column_value, v_hmac_key) THEN
+            SIGNAL SQLSTATE '45000'
+            SET MESSAGE_TEXT = 'Column does not carry a valid HMAC tag (plaintext or tampered value)';
+        END IF;
+    END IF;
+END$$
+
+-- Called from a BEFORE UPDATE trigger. An UPDATE that leaves the value as it was is not
+-- re-checked; see "Updates after a key rotation".
+DROP PROCEDURE IF EXISTS validate_encrypted_data_hmac_before_update$$
+CREATE PROCEDURE validate_encrypted_data_hmac_before_update(
+    IN p_table_name VARCHAR(64),
+    IN p_column_name VARCHAR(64),
+    IN new_value VARBINARY(65535),
+    IN old_value VARBINARY(65535)
+)
+BEGIN
+    IF NOT (new_value <=> old_value) THEN
+        CALL validate_encrypted_data_hmac_before_insert(p_table_name, p_column_name, new_value);
+    END IF;
+END$$
+
+DELIMITER ;