echspec 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ff77e42c8a7e2d787372fe6f96f3c00619fb6bcb3feea8df89c5400a838aef6
-  data.tar.gz: d317448071982052658909b19a99f535ce99e1c9f063de65be9cecae1ab4179f
+  metadata.gz: bce9c266ff5ece6660c7adab52de934378be099778a00520e5f758acf3052aae
+  data.tar.gz: 5675044be1620e08f228fbb3b8067ababb0764522b462456d7c3534cf974c2a0
 SHA512:
-  metadata.gz: 7c4eea37fd0a7002bf6fd2a68b0a5c299bf84b43a71933053fb6cf2df59aedc17836e3299e809d1e5889130ccfcbd6ec19a276ffda556da8cf58b9e28042e211
-  data.tar.gz: c56a875c0547d3456958a5cbd9b8d3ec7d4e921033d176c2b2835b80657b59d9d207e9dc0342564506f89d9cee313168427e906e9d6249f6298a0e90d6a9a5cf
+  metadata.gz: 91cb45ce9eb4672aa3c8352f21969d1cc442cce7cf4ef924e9fd9c038a9b1e29e43880428a7b6539c16eb4a6eda4527ac1b3052b85e69466f710a24e0df1517b
+  data.tar.gz: 5fed5c9dc669ad9ea2766097e1f473cbb8bc834d0f8ce5be81cd81428f6b914d5b25b55b10744e77824f03b96c5fc4b0d0dd734148dcdb8fe03b732fa95c97bc

data/.ruby-version

@@ -1 +1 @@
-4.0.1
+4.0.2

data/README.md

@@ -13,7 +13,7 @@
 
 ## Installation
 
-The gem is available at [rubygems.org](https://rubygems.org/gems/echspec). You can install it the following:
+The gem is available at [rubygems.org](https://rubygems.org/gems/echspec). You can install it with the following:
 
 ```sh-session
 $ gem install echspec
@@ -24,7 +24,22 @@ $ gem install echspec
 
 ```sh-session
 $ echspec --help
-Usage: echspec [OPTIONS] <HOSTNAME>
+Usage: echspec {SUBCOMMAND}
+
+Available subcommands: run, gen_configs, version, help.
+```
+```sh-session
+$ echspec run --help
+Usage: echspec run [OPTIONS...] {HOSTNAME}
+
+Run ECH conformance tests for a server.
+
+Examples:
+
+  $ echspec run localhost
+  $ echspec run -f echconfigs.pem -p 4433 localhost
+
+Options:
     -f, --file FILE                  path to ECHConfigs PEM file       (default resolve ECHConfigs via DNS)
     -p, --port VALUE                 server port number                (default 443)
     -n, --not-force-compliant-hpke   not force compliant ECHConfig HPKE cipher suite
@@ -32,10 +47,10 @@ Usage: echspec [OPTIONS] <HOSTNAME>
     -s, --sections SECTIONS          sections to test; by the default, test all sections
 ```
 
-You can run it the following:
+Example output:
 
 ```sh-session
-$ echspec research.cloudflare.com
+$ echspec run research.cloudflare.com
 TLS Encrypted Client Hello Server
         ✔ MUST implement the following HPKE cipher suite: KEM: DHKEM(X25519, HKDF-SHA256), KDF: HKDF-SHA256 and AEAD: AES-128-GCM. [9]
         ✔ MUST abort with an "illegal_parameter" alert, if EncodedClientHelloInner is padded with non-zero values. [5.1-9]
@@ -60,13 +75,13 @@ Failures:
 1 failure
 ```
 
-By default, `echspec` retrieves ECHConfigs via HTTPS records. By using the `-f, --file FILE` option, you can specify an ECHConfig pem file. If you need to test the server on localhost, you can run it the following:
+By default, `echspec` retrieves ECHConfigs via DNS HTTPS records. You can specify a local PEM file using the `-f, --file FILE` option. To test a server on localhost:
 
 ```sh-session
-$ echspec -f fixtures/echconfigs.pem -p 4433 localhost
+$ echspec run -f fixtures/echconfigs.pem -p 4433 localhost
 ```
 
-By default, `echspec` uses the following HPKE cipher suite
+By default, `echspec` enforces the following mandatory HPKE cipher suite:
 
 - KEM
   - DHKEM(X25519, HKDF-SHA256)
@@ -75,16 +90,16 @@ By default, `echspec` uses the following HPKE cipher suite
 - AEAD
   - AES-128-GCM
 
-Using the `-n` or `--not-force-compliant-hpke`, you can not enforce the HPKE cipher suite.
+Use the `-n` or `--not-force-compliant-hpke` option to disable this enforcement and use the cipher suite provided in the ECHConfig.
 
 ```sh-session
-$ echspec -f fixtures/echconfigs.pem -p 4433 -n localhost
+$ echspec run -f fixtures/echconfigs.pem -p 4433 -n localhost
 ```
 
-If you specify the SECTIONS, you can run only SECTIONS the following:
+To run only specific test SECTIONS, use the `-s` option:
 
 ```sh-session
-$ echspec -f fixtures/echconfigs.pem -p 4433 -n -s 7.1.1-2,7.1.1-5 localhost
+$ echspec run -f fixtures/echconfigs.pem -p 4433 -n -s 7.1.1-2,7.1.1-5 localhost
 TLS Encrypted Client Hello Server
         ✔ MUST abort with a "missing_extension" alert, if 2nd ClientHelloOuter does not contains the "encrypted_client_hello" extension. [7.1.1-2]
         ✔ MUST abort with an "illegal_parameter" alert, if 2nd ClientHelloOuter "encrypted_client_hello" enc is empty. [7.1.1-2]
@@ -94,7 +109,7 @@ TLS Encrypted Client Hello Server
 Using the `-v` or `--verbose` option provides a message stack if an error occurs. The message stack is formatted as JSON.
 
 ```sh-session
-$ echspec -s 7-5 -v research.cloudflare.com 2>&1 > /dev/null | jq .
+$ echspec run -s 7-5 -v research.cloudflare.com 2>&1 > /dev/null | jq .
 ````
 
 <details>
@@ -267,6 +282,21 @@ $ echspec -s 7-5 -v research.cloudflare.com 2>&1 > /dev/null | jq .
 
 </details>
 
+You can generate an ECHConfig PEM file the following:
+
+```sh-session
+$ echspec gen_configs echconfigs.pem
+```
+```
+-----BEGIN PRIVATE KEY-----
+MC4CAQAwBQYDK2VuBCIEICjd4yGRdsoP9gU7YT7My8DHx1Tjme8GYDXrOMCi8v1V
+-----END PRIVATE KEY-----
+-----BEGIN ECHCONFIG-----
+AD7+DQA65wAgACA8wVN2BtscOl3vQheUzHeIkVmKIiydUhDCliA4iyQRCwAEAAEA
+AQALZXhhbXBsZS5jb20AAA==
+-----END ECHCONFIG-----
+```
+
 
 ## Note
 

data/Rakefile

@@ -1,49 +1,8 @@
 require 'bundler/gem_tasks'
-require 'ech_config'
-require 'hpke'
-require 'openssl'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 RSpec::Core::RakeTask.new(:spec)
 
-TMP_DIR    = "#{__dir__}/tmp".freeze
-ECHCONFIGS = "#{TMP_DIR}/echconfigs.pem".freeze
-
-directory TMP_DIR
-
-file ECHCONFIGS => TMP_DIR do
-  puts "generate #{ECHCONFIGS}..."
-
-  key = OpenSSL::PKey.generate_key('X25519')
-  echconfigs = ECHConfigList.new(
-    [
-      ECHConfig.new(
-        "\xfe\x0d".b,
-        ECHConfig::ECHConfigContents.new(
-          ECHConfig::ECHConfigContents::HpkeKeyConfig.new(
-            123,
-            ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeKemId.new(HPKE::DHKEM_X25519_HKDF_SHA256),
-            ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkePublicKey.new(key.raw_public_key),
-            [
-              ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeSymmetricCipherSuite.new(
-                ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeSymmetricCipherSuite::HpkeKdfId.new(HPKE::HKDF_SHA256),
-                ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeSymmetricCipherSuite::HpkeAeadId.new(HPKE::AES_128_GCM)
-              )
-            ]
-          ),
-          32,
-          'localhost'.b,
-          ECHConfig::ECHConfigContents::Extensions.new('')
-        )
-      )
-    ]
-  )
-  File.write(ECHCONFIGS, key.private_to_pem + echconfigs.to_pem)
-end
-
-desc 'generate echconfigs file'
-task gen_echconfigs: ECHCONFIGS
-
 task default: %i[rubocop spec]

data/exe/echspec

@@ -4,4 +4,4 @@ $LOAD_PATH << "#{__dir__}/../lib"
 
 require 'echspec'
 
-EchSpec::CLI.new.run
+EchSpec::CLI.new.execute

data/lib/echspec/cli/gen_configs.rb

@@ -0,0 +1,69 @@
+module EchSpec
+  class CLI
+    class GenConfigs
+      def execute(argv)
+        fpath = parse_options(argv)
+        write(fpath)
+      end
+
+      def parse_options(argv)
+        op = OptionParser.new
+
+        op.banner = <<~USAGE
+          Usage: echspec gen_configs {FILE}
+
+          Generate an ECHConfig PEM file.
+
+          Examples:
+
+            $ echspec gen_configs echconfigs.pem
+        USAGE
+
+        begin
+          args = op.parse(argv)
+        rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+          warn op
+          warn "** #{e.message}"
+          exit 1
+        end
+
+        if args.length != 1
+          warn op
+          warn '** {FILE} argument is not specified'
+          exit 1
+        end
+        args[0]
+      end
+
+      def write(fpath)
+        hostname = 'localhost'
+
+        key = OpenSSL::PKey.generate_key('X25519')
+        echconfigs = ECHConfigList.new(
+          [
+            ECHConfig.new(
+              "\xfe\x0d".b,
+              ECHConfig::ECHConfigContents.new(
+                ECHConfig::ECHConfigContents::HpkeKeyConfig.new(
+                  123,
+                  ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeKemId.new(HPKE::DHKEM_X25519_HKDF_SHA256),
+                  ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkePublicKey.new(key.raw_public_key),
+                  [
+                    ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeSymmetricCipherSuite.new(
+                      ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeSymmetricCipherSuite::HpkeKdfId.new(HPKE::HKDF_SHA256),
+                      ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeSymmetricCipherSuite::HpkeAeadId.new(HPKE::AES_128_GCM)
+                    )
+                  ]
+                ),
+                32,
+                hostname.b,
+                ECHConfig::ECHConfigContents::Extensions.new('')
+              )
+            )
+          ]
+        )
+        File.write(fpath, key.private_to_pem + echconfigs.to_pem)
+      end
+    end
+  end
+end

data/lib/echspec/cli/run.rb

@@ -0,0 +1,111 @@
+module EchSpec
+  class CLI
+    class Run
+      def execute(argv)
+        fpath, port, force_compliant, verbose, hostname, sections = parse_options(argv)
+
+        if sections.nil?
+          Spec.run(fpath, port, hostname, force_compliant, verbose)
+        else
+          Spec.run_only(fpath, port, hostname, sections, verbose)
+        end
+      end
+
+      # rubocop: disable Metrics/AbcSize
+      # rubocop: disable Metrics/MethodLength
+      def parse_options(argv)
+        op = OptionParser.new
+
+        # default value
+        fpath = nil
+        port = 443
+        force_compliant = true
+        verbose = false
+        sections = nil
+
+        op.on(
+          '-f',
+          '--file FILE',
+          'path to ECHConfigs PEM file       (default resolve ECHConfigs via DNS)'
+        ) do |v|
+          fpath = v
+        end
+
+        op.on(
+          '-p',
+          '--port VALUE',
+          "server port number                (default #{port})"
+        ) do |v|
+          port = v
+        end
+
+        op.on(
+          '-n',
+          '--not-force-compliant-hpke',
+          'not force compliant ECHConfig HPKE cipher suite'
+        ) do
+          force_compliant = false
+        end
+
+        op.on(
+          '-v',
+          '--verbose',
+          'verbose mode; prints message stack if raised an error'
+        ) do
+          verbose = true
+        end
+
+        op.on(
+          '-s',
+          '--sections SECTIONS',
+          'sections to test; by the default, test all sections'
+        ) do |v|
+          sections = v.split(',')
+        end
+
+        op.banner = <<~USAGE
+          Usage: echspec run [OPTIONS...] {HOSTNAME}
+
+          Run ECH conformance tests for a server.
+
+          Examples:
+
+            $ echspec run localhost
+            $ echspec run -f echconfigs.pem -p 4433 localhost
+
+          Options:
+        USAGE
+
+        begin
+          args = op.parse(argv)
+        rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+          warn op
+          warn "** #{e.message}"
+          exit 1
+        end
+
+        if !fpath.nil? && !File.exist?(fpath)
+          warn '** {FILE} is not found'
+          exit 1
+        end
+
+        unknowns = sections.nil? ? [] : sections - Spec.sections
+        unless unknowns.empty?
+          warn "** #{unknowns} are unknown sections"
+          exit 1
+        end
+
+        if args.length != 1
+          warn op
+          warn '** {HOSTNAME} argument is not specified'
+          exit 1
+        end
+        hostname = args[0]
+
+        [fpath, port, force_compliant, verbose, hostname, sections]
+      end
+      # rubocop: enable Metrics/AbcSize
+      # rubocop: enable Metrics/MethodLength
+    end
+  end
+end

data/lib/echspec/cli.rb

@@ -1,96 +1,33 @@
+require_relative 'cli/gen_configs'
+require_relative 'cli/run'
+
 module EchSpec
   class CLI
-    # rubocop: disable Metrics/AbcSize
-    # rubocop: disable Metrics/MethodLength
-    def parse_options(argv = ARGV)
-      op = OptionParser.new
-
-      # default value
-      fpath = nil
-      port = 443
-      force_compliant = true
-      verbose = false
-      sections = nil
-
-      op.on(
-        '-f',
-        '--file FILE',
-        'path to ECHConfigs PEM file       (default resolve ECHConfigs via DNS)'
-      ) do |v|
-        fpath = v
-      end
-
-      op.on(
-        '-p',
-        '--port VALUE',
-        "server port number                (default #{port})"
-      ) do |v|
-        port = v
-      end
-
-      op.on(
-        '-n',
-        '--not-force-compliant-hpke',
-        'not force compliant ECHConfig HPKE cipher suite'
-      ) do
-        force_compliant = false
-      end
-
-      op.on(
-        '-v',
-        '--verbose',
-        'verbose mode; prints message stack if raised an error'
-      ) do
-        verbose = true
-      end
-
-      op.on(
-        '-s',
-        '--sections SECTIONS',
-        'sections to test; by the default, test all sections'
-      ) do |v|
-        sections = v.split(',')
-      end
-
-      op.banner = 'Usage: echspec [OPTIONS] <HOSTNAME>'
-      begin
-        args = op.parse(argv)
-      rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
-        warn op
-        warn "** #{e.message}"
-        exit 1
-      end
+    using Refinements
 
-      if !fpath.nil? && !File.exist?(fpath)
-        warn '** <FILE> is not found'
-        exit 1
-      end
+    def execute(argv = ARGV)
+      subcommands = %i[run gen_configs]
 
-      unknowns = sections.nil? ? [] : sections - Spec.sections
-      unless unknowns.empty?
-        warn "** #{unknowns} are unknown sections"
-        exit 1
-      end
+      op = OptionParser.new
 
-      if args.length != 1
-        warn op
-        warn '** <HOSTNAME> argument is not specified'
-        exit 1
-      end
-      hostname = args[0]
+      op.banner = <<~USAGE
+        Usage: echspec {SUBCOMMAND}
 
-      [fpath, port, force_compliant, verbose, hostname, sections]
-    end
-    # rubocop: enable Metrics/AbcSize
-    # rubocop: enable Metrics/MethodLength
+        Available subcommands: #{subcommands.join(', ')}, version, help.
+      USAGE
 
-    def run
-      fpath, port, force_compliant, verbose, hostname, sections = parse_options
+      op.version = EchSpec::VERSION
+      op.order!(argv)
 
-      if sections.nil?
-        Spec.run(fpath, port, hostname, force_compliant, verbose)
+      subcommand = argv.shift
+      case subcommand&.to_sym
+      when :version
+        puts EchSpec::VERSION
+      when *subcommands
+        klass = self.class.const_get(subcommand.to_camel)
+        klass.new.__send__(:execute, argv)
       else
-        Spec.run_only(fpath, port, hostname, sections, verbose)
+        puts op
       end
     end
   end

data/lib/echspec/utils.rb

@@ -20,6 +20,10 @@ module EchSpec
       def yellow
         colorize(33)
       end
+
+      def to_camel
+        gsub(/(?:^|_)(.)/) { Regexp.last_match(1).upcase }
+      end
     end
   end
 end

data/lib/echspec/version.rb

@@ -1,3 +1,3 @@
 module EchSpec
-  VERSION = '0.0.3'.freeze
+  VERSION = '0.0.5'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: echspec
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - thekuwayama
@@ -101,6 +101,8 @@ files:
 - fixtures/server.key
 - lib/echspec.rb
 - lib/echspec/cli.rb
+- lib/echspec/cli/gen_configs.rb
+- lib/echspec/cli/run.rb
 - lib/echspec/error.rb
 - lib/echspec/log.rb
 - lib/echspec/result.rb
@@ -136,7 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.7
+rubygems_version: 4.0.8
 specification_version: 4
 summary: A conformance testing tool for ECH implementation
 test_files: []