ech_config 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 669b29a1c5c1ec227e23a1f417b18a694449c21b1fd2f8ca90ea2afc67ad7e02
+  data.tar.gz: 2e748100fb8990fa38e1bd784868dff959da998a727164bf27869cdc21b35b0c
+SHA512:
+  metadata.gz: da1970fab247c1428188b088a26462f8fcf5cc150363e85b57bd1336bac1146bbf46b1396437045f2c190481d7636def112ef4d8ebf1edc95a1e9e7b5e47dad8
+  data.tar.gz: 73448f4886946b2f969ce9f45830a0bb798d26d5f8d34dd59f85b5f7b99ada2d02afba322d29229b44658bcbb9f00bc2f52d341e677f15ad6e18a6dbbd7c6bce

data/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.7.x', '3.0.x', '3.1.x', '3.2.x']
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: |
+          gem --version
+          gem install bundler
+          bundle --version
+          bundle install
+      - name: Run Rubocop
+        run: |
+          bundle exec rake rubocop
+      - name: Run Sorbet type checker
+        run: |
+          bundle exec rake sorbet

data/.gitignore

@@ -0,0 +1,16 @@
+*.gem
+*.rbc
+.config
+.rvmrc
+/.bundle/
+/vendor/
+/lib/bundler/man/
+/pkg/
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+/coverage/
+/spec/reports/
+/tmp/
+*.rdb

data/.rubocop.yml

@@ -0,0 +1,34 @@
+AllCops:
+  TargetRubyVersion: 2.7
+
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/NumericLiterals:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact
+
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/MethodLength:
+  Max: 30
+
+Naming/MethodParameterName:
+  MinNameLength: 1
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/*.rb'
+    - 'sorbet/**/*'
+
+require:
+  - rubocop-sorbet
+
+Sorbet:
+  Enabled: true

data/.ruby-version

@@ -0,0 +1 @@
+3.1.2

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'sorbet-runtime'
+
+group :test do
+  gem 'byebug'
+  gem 'rake'
+  gem 'rspec', '3.11'
+  gem 'rubocop', '1.42'
+  gem 'rubocop-sorbet'
+  gem 'sorbet'
+  gem 'webrick'
+end

data/Gemfile.lock

@@ -0,0 +1,73 @@
+PATH
+  remote: .
+  specs:
+    ech_config (0.0.1)
+      sorbet-runtime
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    byebug (11.1.3)
+    diff-lcs (1.5.0)
+    json (2.6.3)
+    parallel (1.22.1)
+    parser (3.2.0.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.1)
+    rexml (3.2.5)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.1)
+    rubocop (1.42.0)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.1.2.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.24.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.24.1)
+      parser (>= 3.1.1.0)
+    rubocop-sorbet (0.6.11)
+      rubocop (>= 0.90.0)
+    ruby-progressbar (1.11.0)
+    sorbet (0.5.10607)
+      sorbet-static (= 0.5.10607)
+    sorbet-runtime (0.5.10607)
+    sorbet-static (0.5.10607-universal-darwin-21)
+    unicode-display_width (2.4.2)
+    webrick (1.7.0)
+
+PLATFORMS
+  arm64-darwin-21
+  x86_64-darwin-21
+
+DEPENDENCIES
+  bundler
+  byebug
+  ech_config!
+  rake
+  rspec (= 3.11)
+  rubocop (= 1.42)
+  rubocop-sorbet
+  sorbet
+  sorbet-runtime
+  webrick
+
+BUNDLED WITH
+   2.3.7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Tomoya Kuwayama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,22 @@
+# ech_config
+
+[![Gem Version](https://badge.fury.io/rb/ech_config.svg)](https://badge.fury.io/rb/ech_config)
+[![CI](https://github.com/thekuwayama/ech_config/workflows/CI/badge.svg)](https://github.com/thekuwayama/ech_config/actions?workflow=CI)
+
+`ech_config` is Ruby implementation of [Encrypted ClientHello Configuration](https://datatracker.ietf.org/doc/draft-ietf-tls-esni/).
+
+`ech_config` supports `0xfe0b` ~ `0xfe0f` ECHConfig.version.
+
+
+## Installation
+
+The gem is available at [rubygems.org](https://rubygems.org/gems/ech_config). You can install with:
+
+```sh-session
+$ gem install ech_config
+```
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
+require 'rspec/core/rake_task'
+
+RuboCop::RakeTask.new
+RSpec::Core::RakeTask.new(:spec)
+
+desc 'Run Sorbet type checker'
+task :sorbet do
+  sh 'srb tc'
+end
+
+task default: %i[rubocop sorbet spec]

data/ech_config.gemspec

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ech_config/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'ech_config'
+  spec.version       = ECHConfig::VERSION
+  spec.authors       = ['thekuwayama']
+  spec.email         = ['thekuwayama@gmail.com']
+  spec.summary       = 'ECHConfig'
+  spec.description   = spec.summary
+  spec.homepage      = 'https://github.com/thekuwayama/ech_config'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>=2.7.0'
+
+  spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler'
+  spec.add_runtime_dependency 'sorbet-runtime'
+end

data/example/README.md

@@ -0,0 +1,9 @@
+## Usage
+
+```sh-session
+$ cd /path/to/ech_config/example
+
+$ ruby well_known_url_client.rb cover.defo.ie draft-13.esni.defo.ie
+```
+
+https://datatracker.ietf.org/meeting/113/materials/slides-113-dispatch-a-well-known-url-for-publishing-echconfiglists-00

data/example/well_known_url_client.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'net/http'
+require 'uri'
+
+require "#{File.dirname(__FILE__)}/../lib/ech_config"
+
+front = ARGV[0] || 'localhost'
+backend = ARGV[1] || 'draft-13.esni.localhost'
+uri = URI("https://#{front}/.well-known/ech/#{backend}.json")
+
+res = Net::HTTP.get_response(uri)
+unless res.is_a?(Net::HTTPSuccess)
+  warn 'error: HTTP Status is not 200'
+  exit 1
+end
+
+JSON.parse(res.body, symbolize_names: true).each do |h|
+  octet = Base64.decode64(h[:echconfiglist])
+  unless octet.length - 2 == octet.slice(0, 2)&.unpack1('n')
+    warn 'error: failed to parse echconfiglist'
+    exit 1
+  end
+
+  pp ECHConfig.decode_vectors(octet.slice(2..) || '')
+end

data/lib/ech_config/ech_config_contents/extensions.rb

@@ -0,0 +1,24 @@
+# typed: true
+# frozen_string_literal: true
+
+class ECHConfig::ECHConfigContents::Extensions
+  extend T::Sig
+  attr_reader :octet
+
+  sig { params(octet: String).void }
+  def initialize(octet)
+    # Note taht ECHConfig::ECHConfigContents::Extension only has octets.
+    # If you need, deserialize octets to get TLS Extension objects.
+    @octet = octet
+  end
+
+  sig { returns(String) }
+  def load
+    @octet
+  end
+
+  sig { params(octet: String).returns(T.attached_class) }
+  def self.store(octet)
+    new(octet)
+  end
+end

data/lib/ech_config/ech_config_contents/hpke_key_config/hpke_kem_id.rb

@@ -0,0 +1,24 @@
+# typed: true
+# frozen_string_literal: true
+
+class ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeKemId
+  extend T::Sig
+  attr_reader :uint16
+
+  sig { params(uint16: Integer).void }
+  def initialize(uint16)
+    @uint16 = uint16
+  end
+
+  sig { returns(String) }
+  def encode
+    [@uint16].pack('n')
+  end
+
+  sig { params(octet: String).returns(T.attached_class) }
+  def self.decode(octet)
+    raise ::ECHConfig::DecodeError if octet.length != 2
+
+    new(octet.unpack1('n'))
+  end
+end

data/lib/ech_config/ech_config_contents/hpke_key_config/hpke_public_key.rb

@@ -0,0 +1,22 @@
+# typed: true
+# frozen_string_literal: true
+
+class ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkePublicKey
+  extend T::Sig
+  attr_reader :opaque
+
+  sig { params(opaque: String).void }
+  def initialize(opaque)
+    @opaque = opaque
+  end
+
+  sig { returns(String) }
+  def encode
+    @opaque.then { |s| [s.length].pack('n') + s }
+  end
+
+  sig { params(octet: String).returns(T.attached_class) }
+  def self.decode(octet)
+    new(octet)
+  end
+end

data/lib/ech_config/ech_config_contents/hpke_key_config/hpke_symmetric_cipher_suite/hpke_aead_id.rb

@@ -0,0 +1,24 @@
+# typed: true
+# frozen_string_literal: true
+
+class ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeSymmetricCipherSuite::HpkeAeadId
+  extend T::Sig
+  attr_reader :uint16
+
+  sig { params(uint16: Integer).void }
+  def initialize(uint16)
+    @uint16 = uint16
+  end
+
+  sig { returns(String) }
+  def encode
+    [@uint16].pack('n')
+  end
+
+  sig { params(octet: String).returns(T.attached_class) }
+  def self.decode(octet)
+    raise ::ECHConfig::DecodeError if octet.length != 2
+
+    new(octet.unpack1('n'))
+  end
+end

data/lib/ech_config/ech_config_contents/hpke_key_config/hpke_symmetric_cipher_suite/hpke_kdf_id.rb

@@ -0,0 +1,24 @@
+# typed: true
+# frozen_string_literal: true
+
+class ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeSymmetricCipherSuite::HpkeKdfId
+  extend T::Sig
+  attr_reader :uint16
+
+  sig { params(uint16: Integer).void }
+  def initialize(uint16)
+    @uint16 = uint16
+  end
+
+  sig { returns(String) }
+  def encode
+    [@uint16].pack('n')
+  end
+
+  sig { params(octet: String).returns(T.attached_class) }
+  def self.decode(octet)
+    raise ::ECHConfig::DecodeError if octet.length != 2
+
+    new(octet.unpack1('n'))
+  end
+end

data/lib/ech_config/ech_config_contents/hpke_key_config/hpke_symmetric_cipher_suite.rb

@@ -0,0 +1,41 @@
+# typed: true
+# frozen_string_literal: true
+
+class ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeSymmetricCipherSuite
+  extend T::Sig
+  # define class
+end
+
+Dir["#{File.dirname(__FILE__)}/hpke_symmetric_cipher_suite/*.rb"]
+  .sort.each { |f| require f }
+
+class ECHConfig::ECHConfigContents::HpkeKeyConfig::HpkeSymmetricCipherSuite
+  attr_reader :kdf_id, :aead_id
+
+  sig { params(kdf_id: HpkeKdfId, aead_id: HpkeAeadId).void }
+  def initialize(kdf_id, aead_id)
+    @kdf_id = kdf_id
+    @aead_id = aead_id
+  end
+
+  sig { returns(String) }
+  def encode
+    @kdf_id.encode + @aead_id.encode
+  end
+
+  sig { params(octet: String).returns(T::Array[T.attached_class]) }
+  def self.decode_vectors(octet)
+    i = 0
+    cipher_suites = []
+    while i < octet.length
+      raise ::ECHConfig::DecodeError if i + 4 > octet.length
+
+      kdf_id = HpkeKdfId.decode(octet.slice(i, 2) || '')
+      aead_id = HpkeAeadId.decode(octet.slice(i + 2, 2) || '')
+      i += 4
+      cipher_suites << new(kdf_id, aead_id)
+    end
+
+    cipher_suites
+  end
+end

data/lib/ech_config/ech_config_contents/hpke_key_config.rb

@@ -0,0 +1,82 @@
+# typed: true
+# frozen_string_literal: true
+
+class ECHConfig::ECHConfigContents::HpkeKeyConfig
+  # define class
+end
+
+Dir["#{File.dirname(__FILE__)}/hpke_key_config/*.rb"]
+  .sort.each { |f| require f }
+
+class ECHConfig::ECHConfigContents::HpkeKeyConfig
+  extend T::Sig
+  attr_reader :config_id, :kem_id, :public_key, :cipher_suites
+
+  sig do
+    params(
+      config_id: Integer,
+      kem_id: HpkeKemId,
+      public_key: HpkePublicKey,
+      cipher_suites: T::Array[HpkeSymmetricCipherSuite]
+    ).void
+  end
+  def initialize(config_id,
+                 kem_id,
+                 public_key,
+                 cipher_suites)
+    @config_id = config_id
+    @kem_id = kem_id
+    @public_key = public_key
+    @cipher_suites = cipher_suites
+  end
+
+  sig { returns(String) }
+  def encode
+    [@config_id].pack('C') \
+    + @kem_id.encode \
+    + @public_key.encode \
+    + @cipher_suites.map(&:encode).join.then { |s| [s.length].pack('n') + s }
+  end
+
+  sig { params(octet: String).returns([T.attached_class, T.nilable(String)]) }
+  # rubocop:disable Metrics/AbcSize
+  # rubocop:disable Metrics/CyclomaticComplexity
+  # rubocop:disable Metrics/PerceivedComplexity
+  def self.decode(octet)
+    raise ::ECHConfig::DecodeError if octet.empty?
+
+    config_id = octet.slice(0, 1)&.unpack1('C')
+    i = 1
+    raise ::ECHConfig::DecodeError if i + 2 > octet.length
+
+    kem_id = HpkeKemId.decode(octet.slice(i, 2) || '')
+    i += 2
+    raise ::ECHConfig::DecodeError if i + 2 > octet.length
+
+    pk_len = octet.slice(i, 2)&.unpack1('n')
+    i += 2
+    raise ::ECHConfig::DecodeError if i + pk_len > octet.length
+
+    public_key = HpkePublicKey.decode(octet.slice(i, pk_len) || '')
+    i += pk_len
+    raise ::ECHConfig::DecodeError if i + 2 > octet.length
+
+    cs_len = octet.slice(i, 2)&.unpack1('n')
+    i += 2
+    raise ::ECHConfig::DecodeError if i + 2 > octet.length
+
+    cs_bin = octet.slice(i, cs_len)
+    i += cs_len
+    cipher_suites = HpkeSymmetricCipherSuite.decode_vectors(cs_bin || '')
+    hpke_key_config = new(
+      config_id,
+      kem_id,
+      public_key,
+      cipher_suites
+    )
+    [hpke_key_config, octet[i..]]
+  end
+  # rubocop:enable Metrics/AbcSize
+  # rubocop:enable Metrics/CyclomaticComplexity
+  # rubocop:enable Metrics/PerceivedComplexity
+end

data/lib/ech_config/ech_config_contents.rb

@@ -0,0 +1,78 @@
+# typed: true
+# frozen_string_literal: true
+
+class ECHConfig::ECHConfigContents
+  # define class
+end
+
+Dir["#{File.dirname(__FILE__)}/ech_config_contents/*.rb"]
+  .sort.each { |f| require f }
+
+class ECHConfig::ECHConfigContents
+  extend T::Sig
+  attr_reader :key_config, :maximum_name_length, :public_name, :extensions
+
+  sig do
+    params(
+      key_config: HpkeKeyConfig,
+      maximum_name_length: Integer,
+      public_name: String,
+      extensions: Extensions
+    ).void
+  end
+  def initialize(key_config,
+                 maximum_name_length,
+                 public_name,
+                 extensions)
+    @key_config = key_config
+    @maximum_name_length = maximum_name_length
+    @public_name = public_name
+    @extensions = extensions
+  end
+
+  sig { returns(String) }
+  def encode
+    @key_config.encode \
+    + [@maximum_name_length].pack('C') \
+    + @public_name.then { |s| [s.length].pack('C') + s } \
+    + @extensions.load.then { |s| [s.length].pack('n') + s }
+  end
+
+  sig { params(octet: String).returns(T.attached_class) }
+  # rubocop:disable Metrics/AbcSize
+  # rubocop:disable Metrics/CyclomaticComplexity
+  # rubocop:disable Metrics/PerceivedComplexity
+  def self.decode(octet)
+    key_config, octet = HpkeKeyConfig.decode(octet)
+    raise ::ECHConfig::DecodeError if octet.nil?
+    raise ::ECHConfig::DecodeError if octet.length < 2
+
+    maximum_name_length = octet.slice(0, 1)&.unpack1('C')
+    raise ::ECHConfig::DecodeError if maximum_name_length.nil?
+
+    pn_len = octet.slice(1, 1)&.unpack1('C')
+    i = 2
+    raise ::ECHConfig::DecodeError if i + pn_len > octet.length
+
+    public_name = octet.slice(i, pn_len)
+    raise ::ECHConfig::DecodeError if public_name.nil?
+
+    i += pn_len
+    raise ::ECHConfig::DecodeError if i + 2 > octet.length
+
+    ex_len = octet.slice(i, 2)&.unpack1('n')
+    i += 2
+    raise ::ECHConfig::DecodeError if i + ex_len != octet.length
+
+    extensions = Extensions.store(octet)
+    new(
+      key_config,
+      maximum_name_length,
+      public_name,
+      extensions
+    )
+  end
+  # rubocop:enable Metrics/AbcSize
+  # rubocop:enable Metrics/CyclomaticComplexity
+  # rubocop:enable Metrics/PerceivedComplexity
+end

data/lib/ech_config/error.rb

@@ -0,0 +1,11 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Generic error, common for all classes under ECHConfig module.
+class ECHConfig::Error < StandardError; end
+
+# Raised if configure is invalid.
+class ECHConfig::DecodeError < ECHConfig::Error; end
+
+# Raised if version is unsupported.
+class ECHConfig::UnsupportedVersion < ECHConfig::Error; end

data/lib/ech_config/version.rb

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+class ECHConfig
+  VERSION = '0.0.1'
+end