thekuwayama / echspec

A conformance testing tool for ECH implementation.

echspec

echspec is a conformance testing tool for ECH implementation.

• https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-18

Initial Setup

You can install with:

$ gem install specific_install

$ gem specific_install [email protected]:thekuwayama/echspec.git

Usage

$ echspec --help
Usage: echspec [OPTIONS] <HOSTNAME>
    -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
    -v, --verbose                    verbose mode; prints message stack if raised an error
    -s, --sections SECTIONS          sections to test; by the default, test all sections

You can run it the following:

$ echspec crypto.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]
        ✔ MUST abort with an "illegal_parameter" alert, if any referenced extension is missing in ClientHelloOuter. [5.1-10]
        ✔ MUST abort with an "illegal_parameter" alert, if any extension is referenced in OuterExtensions more than once. [5.1-10]
        ✔ MUST abort with an "illegal_parameter" alert, if "encrypted_client_hello" is referenced in OuterExtensions. [5.1-10]
        ✔ MUST abort with an "illegal_parameter" alert, if the extensions in ClientHelloOuter corresponding to those in OuterExtensions do not occur in the same order. [5.1-10]
        ✔ MUST abort with an "illegal_parameter" alert, if ECHClientHello.type is not a valid ECHClientHelloType in ClientHelloInner. [7-5]
        ✔ MUST abort with an "illegal_parameter" alert, if ECHClientHello.type is not a valid ECHClientHelloType in ClientHelloOuter. [7-5]
        ✔ MUST abort with an "illegal_parameter" alert, if ClientHelloInner offers TLS 1.2 or below. [7.1-11]
        ✔ MUST include the "encrypted_client_hello" extension in its EncryptedExtensions with the "retry_configs" field set to one or more ECHConfig. [7.1-14.2.1]
        ✔ 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]
        ✔ MUST abort with a "decrypt_error" alert, if fails to decrypt 2nd ClientHelloOuter. [7.1.1-5]

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:

$ echspec -f fixtures/echconfigs.pem -p 4433 localhost

By default, echspec uses the following HPKE cipher suite

• KEM
  • DHKEM(X25519, HKDF-SHA256)
• KDF
  • HKDF-SHA256
• AEAD
  • AES-128-GCM

By using the -n, --not-force-compliant-hpke, you can not enforce the HPKE cipher suite.

$ echspec -f fixtures/echconfigs.pem -p 4433 -n localhost

If you specify the SECTIONS, you can run only SECTIONS the following:

$ echspec -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]
        ✔ MUST abort with a "decrypt_error" alert, if fails to decrypt 2nd ClientHelloOuter. [7.1.1-5]

License

echspec is available as open source under the terms of the MIT License.

echspec's Issues

backend server test mode

                +---------------------+
                |                     |
                |   2001:DB8::1111    |
                |                     |
Client <----->  | private.example.org |
                |                     |
                | public.example.com  |
                |                     |
                +---------------------+
                        Server
          (Client-Facing and Backend Combined)

https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-17#name-shared-mode-topology

           +--------------------+     +---------------------+
           |                    |     |                     |
           |   2001:DB8::1111   |     |   2001:DB8::EEEE    |
Client <----------------------------->|                     |
           | public.example.com |     | private.example.com |
           |                    |     |                     |
           +--------------------+     +---------------------+
            Client-Facing Server            Backend Server

https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-17#name-split-mode-topology

echspec assumes to connect with Client-Facing Server. For Backend Server in Split Mode, support "backend server test mode".

generate PEM file for ECH

for local server testing

• https://datatracker.ietf.org/doc/draft-farrell-tls-pemesni/

7.1-11 protocol_version or illegal_parameter

ECH が有効化され、TLS1.3 のみをサポートするように設定されたサーバーに対して、encrypted_client_hello 拡張と TLS 1.2 を指定してハンドシェイクを試みると、次の二つのアラートが返される可能性があると理解しています。

• protocol_version
  • https://datatracker.ietf.org/doc/html/rfc8446#section-6.2
• illegal_parameter
  • https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-18#section-7.1-11

echspec 7.1-11 のテストケースでは、illegal_parameter アラートを期待しています。したがって、このテストケースは protocol_version アラートを受け取ったなら fail します。protocol_version を受け付けるように echspec 7.1-11 を変更すると、当該のテストケースについて ECH の仕様で illegal_parameter を返さなくても pass するようになってしまいます。よって、サーバーの ECH 実装を検証するためには、TLS 1.2 もサポートするようにサーバー設定した上で、このテストケースを検証する必要があると考えています。

echspec 7.1-11 について、protocol_version アラートを受け取った場合に「TLS 1.2 もサポートするようにサーバーを設定する」ように促すメッセージを表示する、という改善案があります。これにより、ユーザーはテストの結果を理解しやすくなります。

Test 5.1-10: valid ech_outer_extensions

Next it makes a copy of the client_hello field and copies the legacy_session_id field from ClientHelloOuter. It then looks for an "ech_outer_extensions" extension. If found, it replaces the extension with the corresponding sequence of extensions in the ClientHelloOuter. The server MUST abort the connection with an "illegal_parameter" alert if any of the following are true:

• Any referenced extension is missing in ClientHelloOuter.
• Any extension is referenced in OuterExtensions more than once.
• "encrypted_client_hello" is referenced in OuterExtensions.
• The extensions in ClientHelloOuter corresponding to those in OuterExtensions do not occur in the same order.

https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-17#section-5.1-10