echspec 0.0.1

data/lib/echspec/spec/7.1-11.rb

@@ -0,0 +1,93 @@
+module EchSpec
+  module Spec
+    class Spec7_1_11 < WithSocket
+      # Upon determining the ClientHelloInner, the client-facing server
+      # checks that the message includes a well-formed
+      # "encrypted_client_hello" extension of type inner and that it does not
+      # offer TLS 1.2 or below. If either of these checks fails, the client-
+      # facing server MUST abort with an "illegal_parameter" alert.
+      #
+      # https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-22#section-7.1-11
+
+      # @return [SpecGroup]
+      def self.spec_group
+        SpecGroup.new(
+          '7.1-11',
+          [
+            SpecCase.new(
+              'MUST abort with an "illegal_parameter" alert, if ClientHelloInner offers TLS 1.2 or below.',
+              method(:validate_ech_with_tls12)
+            )
+          ]
+        )
+      end
+
+      # @param hostname [String]
+      # @param port [Integer]
+      # @param ech_config [ECHConfig]
+      #
+      # @return [EchSpec::Ok | Err]
+      def self.validate_ech_with_tls12(hostname, port, ech_config)
+        Spec7_1_11.new.do_validate_ech_with_tls12(hostname, port, ech_config)
+      end
+
+      # @param hostname [String]
+      # @param port [Integer]
+      # @param ech_config [ECHConfig]
+      #
+      # @return [EchSpec::Ok | Err]
+      def do_validate_ech_with_tls12(hostname, port, ech_config)
+        with_socket(hostname, port) do |socket|
+          recv = send_ch_ech_with_tls12(socket, hostname, ech_config)
+          return Err.new('did not send expected alert: illegal_parameter', message_stack) \
+            unless Spec.expect_alert(recv, :illegal_parameter)
+
+          Ok.new(nil)
+        end
+      end
+
+      # rubocop: disable Metrics/MethodLength
+      def send_ch_ech_with_tls12(socket, hostname, ech_config)
+        conn = TLS13Client::Connection.new(socket, :client)
+        inner_ech = TTTLS13::Message::Extension::ECHClientHello.new_inner
+        exs, = TLS13Client.gen_ch_extensions(hostname)
+        # supported_versions: only TLS 1.2
+        versions = TTTLS13::Message::Extension::SupportedVersions.new(
+          msg_type: TTTLS13::Message::HandshakeType::CLIENT_HELLO,
+          versions: [TTTLS13::Message::ProtocolVersion::TLS_1_2]
+        )
+        exs[TTTLS13::Message::ExtensionType::SUPPORTED_VERSIONS] = versions
+        inner = TTTLS13::Message::ClientHello.new(
+          cipher_suites: TTTLS13::CipherSuites.new(
+            [
+              TTTLS13::CipherSuite::TLS_AES_256_GCM_SHA384,
+              TTTLS13::CipherSuite::TLS_CHACHA20_POLY1305_SHA256,
+              TTTLS13::CipherSuite::TLS_AES_128_GCM_SHA256
+            ]
+          ),
+          extensions: exs.merge(
+            TTTLS13::Message::ExtensionType::ENCRYPTED_CLIENT_HELLO => inner_ech
+          )
+        )
+
+        selector = proc { |x| TLS13Client.select_ech_hpke_cipher_suite(x) }
+        ch, inner, = TTTLS13::Ech.offer_ech(inner, ech_config, selector)
+        conn.send_record(
+          TTTLS13::Message::Record.new(
+            type: TTTLS13::Message::ContentType::HANDSHAKE,
+            messages: [ch],
+            cipher: TTTLS13::Cryptograph::Passer.new
+          )
+        )
+        @stack << inner
+        @stack << ch
+
+        recv, = conn.recv_message(TTTLS13::Cryptograph::Passer.new)
+        @stack << recv
+
+        recv
+      end
+      # rubocop: enable Metrics/MethodLength
+    end
+  end
+end

data/lib/echspec/spec/7.1-14.2.1.rb

@@ -0,0 +1,133 @@
+module EchSpec
+  module Spec
+    class Spec7_1_14_2_1 < WithSocket
+      # Otherwise, if all candidate ECHConfig values fail to decrypt the
+      # extension, the client-facing server MUST ignore the extension and
+      # proceed with the connection using ClientHelloOuter, with the
+      # following modifications:
+      #
+      # * If the server is configured with any ECHConfigs, it MUST include
+      #   the "encrypted_client_hello" extension in its EncryptedExtensions
+      #   with the "retry_configs" field set to one or more ECHConfig
+      #   structures with up-to-date keys. Servers MAY supply multiple
+      #   ECHConfig values of different versions. This allows a server to
+      #   support multiple versions at once.
+      #
+      # https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-22#section-7.1-14.2.1
+
+      # @return [EchSpec::SpecGroup]
+      def self.spec_group
+        SpecGroup.new(
+          '7.1-14.2.1',
+          [
+            SpecCase.new(
+              'MUST include the "encrypted_client_hello" extension in its EncryptedExtensions with the "retry_configs" field set to one or more ECHConfig.',
+              method(:validate_ee_retry_configs)
+            )
+          ]
+        )
+      end
+
+      # @param hostname [String]
+      # @param port [Integer]
+      # @param _ [ECHConfig]
+      #
+      # @return [EchSpec::Ok | Err]
+      def self.validate_ee_retry_configs(hostname, port, _)
+        Spec7_1_14_2_1.new.do_validate_ee_retry_configs(hostname, port)
+      end
+
+      # @param hostname [String]
+      # @param port [Integer]
+      #
+      # @return [EchSpec::Ok | Err]
+      def do_validate_ee_retry_configs(hostname, port)
+        with_socket(hostname, port) do |socket|
+          recv = send_ch_with_greased_ech(socket, hostname)
+          ex = recv.extensions[TTTLS13::Message::ExtensionType::ENCRYPTED_CLIENT_HELLO]
+          return Err.new('did not send expected alert: encrypted_client_hello', message_stack) \
+            unless ex.is_a?(TTTLS13::Message::Extension::ECHEncryptedExtensions)
+          return Err.new('ECHConfigs did not have "retry_configs"', message_stack) \
+            if ex.retry_configs.nil? || ex.retry_configs.empty?
+
+          Ok.new(nil)
+        end
+      end
+
+      # rubocop: disable Metrics/AbcSize
+      # rubocop: disable Metrics/MethodLength
+      def send_ch_with_greased_ech(socket, hostname)
+        # send ClientHello
+        conn = TLS13Client::Connection.new(socket, :client)
+        inner_ech = TTTLS13::Message::Extension::ECHClientHello.new_inner
+        exs, priv_keys = TLS13Client.gen_ch_extensions(hostname)
+        inner = TTTLS13::Message::ClientHello.new(
+          cipher_suites: TTTLS13::CipherSuites.new(
+            [
+              TTTLS13::CipherSuite::TLS_AES_256_GCM_SHA384,
+              TTTLS13::CipherSuite::TLS_CHACHA20_POLY1305_SHA256,
+              TTTLS13::CipherSuite::TLS_AES_128_GCM_SHA256
+            ]
+          ),
+          extensions: exs.merge(
+            TTTLS13::Message::ExtensionType::ENCRYPTED_CLIENT_HELLO => inner_ech
+          )
+        )
+        @stack << inner
+
+        ch = TTTLS13::Ech.new_greased_ch(inner, TTTLS13::Ech.new_grease_ech)
+        conn.send_record(
+          TTTLS13::Message::Record.new(
+            type: TTTLS13::Message::ContentType::HANDSHAKE,
+            messages: [ch],
+            cipher: TTTLS13::Cryptograph::Passer.new
+          )
+        )
+        @stack << ch
+
+        # receive ServerHello
+        recv, = conn.recv_message(TTTLS13::Cryptograph::Passer.new)
+        @stack << recv
+        raise Error::BeforeTargetSituationError, 'not received ServerHello' \
+          unless recv.is_a?(TTTLS13::Message::ServerHello) && !recv.hrr?
+
+        # receive EncryptedExtensions
+        transcript = TTTLS13::Transcript.new
+        transcript[TTTLS13::CH] = [ch, ch.serialize]
+        sh = recv
+        transcript[TTTLS13::SH] = [sh, sh.serialize]
+        kse = sh.extensions[TTTLS13::Message::ExtensionType::KEY_SHARE]
+                .key_share_entry.first
+        shared_secret = TTTLS13::Endpoint.gen_shared_secret(
+          kse.key_exchange,
+          priv_keys[kse.group],
+          kse.group
+        )
+        key_schedule = TTTLS13::KeySchedule.new(
+          psk: nil,
+          shared_secret:,
+          cipher_suite: sh.cipher_suite,
+          transcript:
+        )
+        hs_rcipher = TTTLS13::Endpoint.gen_cipher(
+          sh.cipher_suite,
+          key_schedule.server_handshake_write_key,
+          key_schedule.server_handshake_write_iv
+        )
+        recv, = conn.recv_message(hs_rcipher)
+        @stack << recv
+        if recv.is_a?(TTTLS13::Message::ChangeCipherSpec)
+          recv, = conn.recv_message(hs_rcipher)
+          @stack << recv
+        end
+
+        raise Error::BeforeTargetSituationError, 'not received EncryptedExtensions' \
+          unless recv.is_a?(TTTLS13::Message::EncryptedExtensions)
+
+        recv
+      end
+      # rubocop: enable Metrics/AbcSize
+      # rubocop: enable Metrics/MethodLength
+    end
+  end
+end

data/lib/echspec/spec/7.1.1-2.rb

@@ -0,0 +1,142 @@
+module EchSpec
+  module Spec
+    class Spec7_1_1_2 < WithSocket
+      # If the client-facing server accepted ECH, it checks the second
+      # ClientHelloOuter also contains the "encrypted_client_hello"
+      # extension. If not, it MUST abort the handshake with a
+      # "missing_extension" alert. Otherwise, it checks that
+      # ECHClientHello.cipher_suite and ECHClientHello.config_id are
+      # unchanged, and that ECHClientHello.enc is empty. If not, it MUST
+      # abort the handshake with an "illegal_parameter" alert.
+      #
+      # https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-22#section-7.1.1-2
+
+      # @return [EchSpec::SpecGroup]
+      def self.spec_group
+        SpecGroup.new(
+          '7.1.1-2',
+          [
+            SpecCase.new(
+              'MUST abort with a "missing_extension" alert, if 2nd ClientHelloOuter does not contains the "encrypted_client_hello" extension.',
+              method(:validate_2nd_ch_missing_ech)
+            ),
+            SpecCase.new(
+              'MUST abort with an "illegal_parameter" alert, if 2nd ClientHelloOuter "encrypted_client_hello" enc is empty.',
+              method(:validate_2nd_ch_unchanged_ech)
+            )
+          ]
+        )
+      end
+
+      # @param hostname [String]
+      # @param port [Integer]
+      # @param ech_config [ECHConfig]
+      #
+      # @return [EchSpec::Ok | Err]
+      def self.validate_2nd_ch_missing_ech(hostname, port, ech_config)
+        Spec7_1_1_2.new.do_validate_2nd_ch_missing_ech(hostname, port, ech_config)
+      end
+
+      # @param hostname [String]
+      # @param port [Integer]
+      # @param ech_config [ECHConfig]
+      #
+      # @return [EchSpec::Ok | Err]
+      def do_validate_2nd_ch_missing_ech(hostname, port, ech_config)
+        with_socket(hostname, port) do |socket|
+          recv = send_2nd_ch_missing_ech(socket, hostname, ech_config)
+          return Err.new('did not send expected alert: missing_extension', message_stack) \
+            unless Spec.expect_alert(recv, :missing_extension)
+
+          Ok.new(nil)
+        end
+      end
+
+      # @param hostname [String]
+      # @param port [Integer]
+      # @param ech_config [ECHConfig]
+      #
+      # @return [EchSpec::Ok | Err]
+      def self.validate_2nd_ch_unchanged_ech(hostname, port, ech_config)
+        Spec7_1_1_2.new.do_validate_2nd_ch_unchanged_ech(hostname, port, ech_config)
+      end
+
+      # @param hostname [String]
+      # @param port [Integer]
+      # @param ech_config [ECHConfig]
+      #
+      # @return [EchSpec::Ok | Err]
+      def do_validate_2nd_ch_unchanged_ech(hostname, port, ech_config)
+        with_socket(hostname, port) do |socket|
+          recv = send_2nd_ch_unchanged_ech(socket, hostname, ech_config)
+          return Err.new('did not send expected alert: illegal_parameter', message_stack) \
+            unless Spec.expect_alert(recv, :illegal_parameter)
+
+          Ok.new(nil)
+        end
+      end
+
+      def send_2nd_ch_missing_ech(socket, hostname, ech_config)
+        conn, _inner1, ch1, hrr, = TLS13Client.recv_hrr(socket, hostname, ech_config, @stack)
+        # send 2nd ClientHello without ech
+        new_exs = TLS13Client.gen_newch_extensions(ch1, hrr)
+        new_exs.delete(TTTLS13::Message::ExtensionType::ENCRYPTED_CLIENT_HELLO)
+        ch = TTTLS13::Message::ClientHello.new(
+          legacy_version: ch1.legacy_version,
+          random: ch1.random,
+          legacy_session_id: ch1.legacy_session_id,
+          cipher_suites: ch1.cipher_suites,
+          legacy_compression_methods: ch1.legacy_compression_methods,
+          extensions: new_exs
+        )
+        conn.send_record(
+          TTTLS13::Message::Record.new(
+            type: TTTLS13::Message::ContentType::HANDSHAKE,
+            messages: [ch],
+            cipher: TTTLS13::Cryptograph::Passer.new
+          )
+        )
+        @stack << ch
+
+        recv, = conn.recv_message(TTTLS13::Cryptograph::Passer.new)
+        @stack << recv
+
+        recv, = conn.recv_message(TTTLS13::Cryptograph::Passer.new) \
+          if recv.is_a?(TTTLS13::Message::ChangeCipherSpec)
+        recv
+      end
+
+      def send_2nd_ch_unchanged_ech(socket, hostname, ech_config)
+        conn, inner1, ch1, hrr, = TLS13Client.recv_hrr(socket, hostname, ech_config, @stack)
+        # send 2nd ClientHello with unchanged ech
+        new_exs = TLS13Client.gen_newch_extensions(ch1, hrr)
+        new_exs[TTTLS13::Message::ExtensionType::ENCRYPTED_CLIENT_HELLO] =
+          ch1.extensions[TTTLS13::Message::ExtensionType::ENCRYPTED_CLIENT_HELLO]
+        ch = TTTLS13::Message::ClientHello.new(
+          legacy_version: ch1.legacy_version,
+          random: ch1.random,
+          legacy_session_id: ch1.legacy_session_id,
+          cipher_suites: ch1.cipher_suites,
+          legacy_compression_methods: ch1.legacy_compression_methods,
+          extensions: new_exs
+        )
+        conn.send_record(
+          TTTLS13::Message::Record.new(
+            type: TTTLS13::Message::ContentType::HANDSHAKE,
+            messages: [ch],
+            cipher: TTTLS13::Cryptograph::Passer.new
+          )
+        )
+        @stack << inner1
+        @stack << ch
+
+        recv, = conn.recv_message(TTTLS13::Cryptograph::Passer.new)
+        @stack << recv
+
+        recv, = conn.recv_message(TTTLS13::Cryptograph::Passer.new) \
+          if recv.is_a?(TTTLS13::Message::ChangeCipherSpec)
+        recv
+      end
+    end
+  end
+end

data/lib/echspec/spec/7.1.1-5.rb

@@ -0,0 +1,83 @@
+module EchSpec
+  module Spec
+    class Spec7_1_1_5 < WithSocket
+      # ClientHelloOuterAAD is computed as described in Section 5.2, but
+      # using the second ClientHelloOuter. If decryption fails, the client-
+      # facing server MUST abort the handshake with a "decrypt_error" alert.
+      # Otherwise, it reconstructs the second ClientHelloInner from the new
+      # EncodedClientHelloInner as described in Section 5.1, using the
+      # second ClientHelloOuter for any referenced extensions.
+      #
+      # https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-22#section-7.1.1-5
+
+      # @return [EchSpec::SpecGroup]
+      def self.spec_group
+        SpecGroup.new(
+          '7.1.1-5',
+          [
+            SpecCase.new(
+              'MUST abort with a "decrypt_error" alert, if fails to decrypt 2nd ClientHelloOuter.',
+              method(:validate_undecryptable_2nd_ch_outer)
+            )
+          ]
+        )
+      end
+
+      # @param hostname [String]
+      # @param port [Integer]
+      # @param ech_config [ECHConfig]
+      #
+      # @return [EchSpec::Ok | Err]
+      def self.validate_undecryptable_2nd_ch_outer(hostname, port, ech_config)
+        Spec7_1_1_5.new.do_validate_undecryptable_2nd_ch_outer(hostname, port, ech_config)
+      end
+
+      # @param hostname [String]
+      # @param port [Integer]
+      # @param ech_config [ECHConfig]
+      #
+      # @return [EchSpec::Ok | Err]
+      def do_validate_undecryptable_2nd_ch_outer(hostname, port, ech_config)
+        with_socket(hostname, port) do |socket|
+          recv = send_2nd_ch_with_undecryptable_ech(socket, hostname, ech_config)
+          return Err.new('did not send expected alert: decrypt_error', message_stack) \
+            unless Spec.expect_alert(recv, :decrypt_error)
+
+          Ok.new(nil)
+        end
+      end
+
+      def send_2nd_ch_with_undecryptable_ech(socket, hostname, ech_config)
+        conn, _inner1, ch1, hrr, ech_state = TLS13Client.recv_hrr(socket, hostname, ech_config, @stack)
+        # send 2nd ClientHello with undecryptable ech
+        new_exs = TLS13Client.gen_newch_extensions(ch1, hrr)
+        inner = TTTLS13::Message::ClientHello.new(
+          legacy_version: ch1.legacy_version,
+          random: ch1.random,
+          legacy_session_id: ch1.legacy_session_id,
+          cipher_suites: ch1.cipher_suites,
+          legacy_compression_methods: ch1.legacy_compression_methods,
+          extensions: new_exs
+        )
+        ech_state.ctx.increment_seq # invalidly increment of the sequence number
+        ch, inner = TTTLS13::Ech.offer_new_ech(inner, ech_state)
+        conn.send_record(
+          TTTLS13::Message::Record.new(
+            type: TTTLS13::Message::ContentType::HANDSHAKE,
+            messages: [ch],
+            cipher: TTTLS13::Cryptograph::Passer.new
+          )
+        )
+        @stack << inner
+        @stack << ch
+
+        recv, = conn.recv_message(TTTLS13::Cryptograph::Passer.new)
+        @stack << recv
+
+        recv, = conn.recv_message(TTTLS13::Cryptograph::Passer.new) \
+          if recv.is_a?(TTTLS13::Message::ChangeCipherSpec)
+        recv
+      end
+    end
+  end
+end

data/lib/echspec/spec/9.rb

@@ -0,0 +1,113 @@
+module EchSpec
+  module Spec
+    class Spec9
+      # In the absence of an application profile standard specifying
+      # otherwise, a compliant ECH application MUST implement the following
+      # HPKE cipher suite:
+      #
+      # * KEM: DHKEM(X25519, HKDF-SHA256) (see Section 7.1 of [HPKE])
+      # * KDF: HKDF-SHA256 (see Section 7.2 of [HPKE])
+      # * AEAD: AES-128-GCM (see Section 7.3 of [HPKE])
+      #
+      # https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-22#section-9
+      @section = '9'
+      @description = 'MUST implement the following HPKE cipher suite: KEM: DHKEM(X25519, HKDF-SHA256), KDF: HKDF-SHA256 and AEAD: AES-128-GCM.'
+      class << self
+        attr_reader :description, :section
+
+        # @param fpath [String | NilClass]
+        # @param hostname [String]
+        # @param force_compliant [Boolean]
+        #
+        # @return [EchSpec::Ok<ECHConfig> | Err]
+        def try_get_ech_config(fpath, hostname, force_compliant)
+          result = if fpath.nil?
+                     resolve_ech_configs(hostname)
+                   else
+                     parse_pem(File.open(fpath).read)
+                   end
+
+          ech_configs = case result
+                        in Ok(obj)
+                          obj
+                        in Err
+                          return result
+                        end
+
+          if force_compliant
+            validate_compliant_ech_configs(ech_configs)
+          else
+            Ok.new(ech_configs.first)
+          end
+        end
+
+        # @param ech_configs [Array of ECHConfig]
+        #
+        # @return [EchSpec::Ok<ECHConfig> | Err]
+        def validate_compliant_ech_configs(ech_configs)
+          ech_config = ech_configs.find do |c|
+            kconfig = c.echconfig_contents.key_config
+            valid_kem_id = kconfig.kem_id.uint16 == 0x0020
+            valid_cipher_suite = kconfig.cipher_suites.any? do |cs|
+              cs.kdf_id.uint16 == 0x0001 && cs.aead_id.uint16 == 0x0001
+            end
+
+            valid_kem_id && valid_cipher_suite
+          end
+          return Ok.new(ech_config) unless ech_config.nil?
+
+          Err.new('ECHConfigs does NOT include HPKE cipher suite: KEM: DHKEM(X25519, HKDF-SHA256), KDF: HKDF-SHA256 and AEAD: AES-128-GCM.', nil)
+        end
+
+        # @param hostname [String]
+        #
+        # @return [EchSpec::Ok<Array of ECHConfig> | Err]
+        def resolve_ech_configs(hostname)
+          begin
+            rr = Resolv::DNS.new.getresource(
+              hostname,
+              Resolv::DNS::Resource::IN::HTTPS
+            )
+          rescue Resolv::ResolvError => e
+            return Err.new(e.message, nil)
+          end
+
+          # https://datatracker.ietf.org/doc/html/draft-ietf-tls-svcb-ech-01#section-6
+          ech = 5
+          return Err.new("HTTPS resource record for #{hostname} does NOT have ech SvcParams.", nil) if rr.params[ech].nil?
+
+          octet = rr.params[ech].value
+          Err.new('Failed to parse ECHConfig on HTTPS resource record.', nil) \
+            unless octet.length == octet.slice(0, 2).unpack1('n') + 2
+
+          Ok.new(ECHConfig.decode_vectors(octet.slice(2..)))
+        end
+
+        # @param pem [String]
+        #
+        # @return [EchSpec::Ok<Array of ECHConfig> | Err]
+        def parse_pem(pem)
+          s = pem.scan(/-----BEGIN ECHCONFIG-----(.*)-----END ECHCONFIG-----/m)
+                 .first
+                 .first
+                 .gsub("\n", '')
+          b = Base64.decode64(s)
+          ech_configs = ECHConfig.decode_vectors(b.slice(2..))
+          Ok.new(ech_configs)
+        rescue StandardError
+          # https://datatracker.ietf.org/doc/html/draft-farrell-tls-pemesni-08#section-3
+          example = <<~PEM
+            -----BEGIN PRIVATE KEY-----
+            MC4CAQAwBQYDK2VuBCIEICjd4yGRdsoP9gU7YT7My8DHx1Tjme8GYDXrOMCi8v1V
+            -----END PRIVATE KEY-----
+            -----BEGIN ECHCONFIG-----
+            AD7+DQA65wAgACA8wVN2BtscOl3vQheUzHeIkVmKIiydUhDCliA4iyQRCwAEAAEA
+            AQALZXhhbXBsZS5jb20AAA==
+            -----END ECHCONFIG-----
+          PEM
+          Err.new("Failed to parse ECHConfig PEM file, expected ECHConfig PEM like following: \n\n#{example}", nil)
+        end
+      end
+    end
+  end
+end