これは、Ruby Advent Calendar 2024 の 16 日目の記事です。
はじめに
本記事では、Ruby で ECH のサーバテストツールを実装した話について書きます。
ECH の概要
2024 年 12 月現在、IETF の TLS WG において ECH (Encrypted Client Hello) という TLS 拡張が議論されています。
TLS は、ハンドシェイクメッセージの Client Hello に通信先のホスト名を記載します。このメッセージは平文で送信されます。第三者は、Client Hello を観測することでクライアントがアクセスしている Web サイトを特定できます。ECH は、Client Hello を暗号化することで第三者から読み取れないようにする拡張です。
ECH のテストツール echspec
ECH は新しい TLS 拡張であり、さまざまなプログラミング言語で実装が進んでいます。新しい仕様において、異なる実装間の動作や互換性を確認することは非常に重要です。そこで、サーバ実装が仕様に沿った動作をするかどうかをテストするツール echspec を実装することにしました。
echspec は TLS 1.3 のクライアントとして動作し、サーバとハンドシェイクを試みます。このハンドシェイクの過程で、サーバが ECH の仕様に沿った実装になっているかどうかをテストします。
例えば、ECH のドラフトには以下の記述があります。
First it parses EncodedClientHelloInner, interpreting all bytes after client_hello as padding. If any padding byte is non-zero, the server MUST abort the connection with an "illegal_parameter" alert.
https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-22#section-5.1-9
詳細は省きますが、クライアントから送信されるメッセージの 0 パディング部分が 0 以外でパディングされていた場合、サーバは illegal_parameter アラートを返してハンドシェイクを中止する必要があります (MUST) 。echspec は、この部分を 0 以外でパディングしてサーバに送信し illegal_parameter アラートが返送されるかどうかをテストします。echspec は、このような仕様に基づくサーバの振る舞いをテストケースとして検証します。
echspec の実行例
下記は実行例です。
$ echspec 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]
✔ 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]
x 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]
Failures:
1) MUST abort with an "illegal_parameter" alert, if ECHClientHello.type is not a valid ECHClientHelloType in ClientHelloOuter. [7-5]
did not send expected alert: illegal_parameter
1 failure
ECH は、Client Hello を暗号化します。そのため、Wireshark を用いてもクライアントが送信した Client Hello を読むことは難しいです。2024 年 12 月現在、ECH を復号するための SSLKEYLOGFILE 拡張はドラフト段階です。
echspec は、失敗したテストケースのハンドシェイクメッセージやアラートメッセージを JSON フォーマットで出力できます。下記のように、jq を使用してテスト結果であるメッセージのスタックを確認できます。
$ echspec research.cloudflare.com -v 2>&1 > /dev/null | jq .
{
"Alert": {
"level": "0x02",
"description": "0x32"
},
"ClientHello": {
"msg_type": "0x01",
"legacy_version": "0x0303",
"random": "0x07091fa0eec43ccc4158b1514998092b4dda0303b238ad51867d355651aa1377",
"legacy_session_id": "0x1679fc195436817295f55b4bba927826d7f26c0ac6b936d2ea69692a3c00f418",
"cipher_suites": [
"0x1302",
"0x1303",
"0x1301"
],
"legacy_compression_methods": [
"0x00"
],
"extensions": {
"0x0000": {
"extension_type": "0x0000",
"server_name": "0x636c6f7564666c6172652d6563682e636f6d"
},
"0x002b": {
"extension_type": "0x002b",
"msg_type": "0x01",
"versions": [
"0x0304"
]
},
"0x000d": {
"extension_type": "0x000d",
"supported_signature_algorithms": [
"0x0403",
"0x0503",
"0x0603",
"0x0804",
"0x0805",
"0x0806",
"0x0401",
"0x0501",
"0x0601"
]
},
"0x000a": {
"extension_type": "0x000a",
"named_group_list": [
"0x0017",
"0x0018",
"0x0019"
]
},
"0x0033": {
"extension_type": "0x0033",
"msg_type": "0x01",
"key_share_entry": [
{
"group": "0x0017",
"key_exchange": "0x04e08b2ff2039880820a03a9706661ca6351bb1b4f03befb011478d18a84acee6caf99bcdbc15434038ccbeb2eac727dc0e223c173d0ae30510679131de0a28937"
},
{
"group": "0x0018",
"key_exchange": "0x04646da67d01eb822c3438f73c23cc1f110d327798ed494b0f3e80f0f610da9e23ee7c40ba0416e58b6ae7b07c144aed35d81aead168a24488f028894d2fad3507deb22fdbff1fadf2a52e99e44596315bc43d99d1bd14be334e6de522282e86b3"
},
{
"group": "0x0019",
"key_exchange": "0x04012e6c12fc453a168987c0188b328c9e3c0da51761b5f7c2dc2a91037ca80771d5b5f434c9070bb3103e966fb0528409152b5ab65c9bb4ac2d21801dd4c70cd88028003a5faef2b03632cd956987ed9e1e9e6cb38a94f5c82a97826788d3a8ba0ce9477f82bcfc56adf2bc57d1abdbbd1602b401465f7e344ed682d30d2f6e3d7aa955c9"
}
]
},
"0xfe0d": {
"extension_type": "0xfe0d",
"type": "0x02",
"cipher_suite": {
"kdf_id": {
"uint16": 1
},
"aead_id": {
"uint16": 1
}
},
"config_id": 8,
"enc": "0x6a618d214da5991b687feadaec52ae1ab3243fd64a9a225cb63fb98544b1b91e",
"payload": "0x00e3f0f2d4c86c4530df0a9b2b43d2f7e518f204c0af348fb687d23365d794cd0e88aadf48d2bc238cb8dc8fbc0327fb2013450de909c92a9572f557f61e0cb03c2fc5e197ed4f376b329ec945ae2e5e40cb7fe8dc9ebef1b08d21570f8dd3eded591a786b3902af010840f2fa3fabe3f49303faeca8a72ee0941f62d447a700da3a7f2cfe2faa041cc9601f52eb0d12e157145a58234531b3306a43bf3b63bf7b1d2ed0953bdb875d3763d5837cd71307b8cf2b5427cf3a083275f0d14eea61d513a72b16a572fe9a87f7399e5ee8540927370aae0c3188ec746e3144b60da4ccb2a80e78e485d0a54fb5398f54063bed2bb3e017ce4cdc2a0cd3c8edc646d9a239ffd30359be6323e5f4934fecdbcc5742ebc662ff5b1f2086aa2895475a8ec7bb2398ef8c9878fa64d50e725d5fc5bdc3783b8455d25de3a5ef87881790e0a88ef5d75e8724fbed93630edd417696a917cb48bc14f7cd0bdbcee70923e598236bd462f634387e6cf415ae6fc366e93b661738e8622e32e0de05d7da3551696c53776ca941bb8d7b19f8b4920a9435bc68ea12e7d609beb67ef95ddd35feb8e5891fc9869644942fd259b7bb690ec60551026bed930efd919473340f0560997b104cb69e671a211ce4f575af70b96b"
}
}
},
"ClientHelloInner": {
"msg_type": "0x01",
"legacy_version": "0x0303",
"random": "0xd344d5fdc653ff8f5183ded8f334c64a40f4e5f894088f0e9ffe33bef096cd68",
"legacy_session_id": "0x1679fc195436817295f55b4bba927826d7f26c0ac6b936d2ea69692a3c00f418",
"cipher_suites": [
"0x1302",
"0x1303",
"0x1301"
],
"legacy_compression_methods": [
"0x00"
],
"extensions": {
"0x0000": {
"extension_type": "0x0000",
"server_name": "0x72657365617263682e636c6f7564666c6172652e636f6d"
},
"0x002b": {
"extension_type": "0x002b",
"msg_type": "0x01",
"versions": [
"0x0304"
]
},
"0x000d": {
"extension_type": "0x000d",
"supported_signature_algorithms": [
"0x0403",
"0x0503",
"0x0603",
"0x0804",
"0x0805",
"0x0806",
"0x0401",
"0x0501",
"0x0601"
]
},
"0x000a": {
"extension_type": "0x000a",
"named_group_list": [
"0x0017",
"0x0018",
"0x0019"
]
},
"0x0033": {
"extension_type": "0x0033",
"msg_type": "0x01",
"key_share_entry": [
{
"group": "0x0017",
"key_exchange": "0x04e08b2ff2039880820a03a9706661ca6351bb1b4f03befb011478d18a84acee6caf99bcdbc15434038ccbeb2eac727dc0e223c173d0ae30510679131de0a28937"
},
{
"group": "0x0018",
"key_exchange": "0x04646da67d01eb822c3438f73c23cc1f110d327798ed494b0f3e80f0f610da9e23ee7c40ba0416e58b6ae7b07c144aed35d81aead168a24488f028894d2fad3507deb22fdbff1fadf2a52e99e44596315bc43d99d1bd14be334e6de522282e86b3"
},
{
"group": "0x0019",
"key_exchange": "0x04012e6c12fc453a168987c0188b328c9e3c0da51761b5f7c2dc2a91037ca80771d5b5f434c9070bb3103e966fb0528409152b5ab65c9bb4ac2d21801dd4c70cd88028003a5faef2b03632cd956987ed9e1e9e6cb38a94f5c82a97826788d3a8ba0ce9477f82bcfc56adf2bc57d1abdbbd1602b401465f7e344ed682d30d2f6e3d7aa955c9"
}
]
},
"0xfe0d": {
"extension_type": "0xfe0d",
"type": "0x01",
"cipher_suite": null,
"config_id": null,
"enc": null,
"payload": null
}
}
}
}
echspec の実装について
本章では、echspec の実装において特に注目している部分について説明します。
ちなみに、echspec は、HTTP/2 の仕様準拠テストツール h2spec に大変影響を受けました。
HPKE
先ず、ECH は仕様として HPKE (Hybrid Public Key Encryption) という仕組みを用います。
ECH を実装するには、HPKE の実装が必要です。Ruby の HPKE 実装 hpke-rb が公開されています。
これを利用して、TLS 1.3 自前実装である tttls1.3 を ECH に対応させました。
テストケース
echspec は tttls1.3 をオーバーライドしています。例えば、「メッセージの 0 パディング部分を 0 以外でパディングする」などオーバーライドしています。テストケースごとに、サーバの特定の振る舞いを検証するためにクライアントの動作をオーバーライドして実装しました。
$ tree lib/echspec/spec/
lib/echspec/spec/
├── 5.1-10.rb
├── 5.1-9.rb
├── 7-5.rb
├── 7.1-11.rb
├── 7.1-14.2.1.rb
├── 7.1.1-2.rb
├── 7.1.1-5.rb
└── 9.rb
1 directory, 8 files
パターンマッチによるテスト結果出力
echspec では、TLS ハンドシェイクがアラートメッセージによって中止されても、プログラムを停止させません。なぜなら、テストケースによってはサーバから特定のアラートメッセージを受け取ることを期待するためです。tttls1.3 はアラートメッセージを受け取った際に例外オブジェクトを生成しますが、echspec は各テストケースの結果を EchSpec::Ok または EchSpec::Err クラスで包んで返すようにしています。つまり、テストケースの呼び出し元に例外を返すのではなく、EchSpec::Ok または EchSpec::Err クラスを返すということです。例えば、サーバから仕様通りのアラートメッセージを受け取った場合は EchSpec::Ok を返し、サーバが仕様に反するメッセージを受け取った場合はメッセージスタックなどを EchSpec::Err に包んで返します。呼び出し元は、EchSpec::Ok または EchSpec::Err クラスをパターンマッチしてテスト結果を抽出して出力したり、サマライズしたりします。
下記はテスト結果を出力する部分の実装です。
def print_summarize(result, desc)
check = "\u2714"
cross = "\u0078"
summary = case result
in Ok
"\t#{check} #{desc}".green
in Err
"\t#{cross} #{desc}".red
end
puts summary
end
おわりに
今後テストケースを増やしていきたいと考えています。
ぜひお試しいただき、フィードバックをいただけると嬉しいです。