【lwIP】Tips #1｜TLS1.2通信をWiresharkで復号する方法｜mbedTLS環境でのTLS通信解析手法

(English Version Here.)

このnoteでは、lwIPで実際に起こり得る不具合・脆弱性・再現方法・最小修正の考え方やデバッグのノウハウをシリーズで解説しています。
▶ 日本語記事一覧はこちら：lwIPトラブル対策室｜日本語記事一覧

■ こんな時に役立ちます

Wiresharkでキャプチャしたのに、暗号化された `Application Data` しか見えない。そんな経験はありませんか？

次のような場面で、この記事が役立ちます。

• Wiresharkでパケットは取得できているのに中身が見えず解析できない

• MQTT over TLS の通信異常の原因を調べたい

• TLS通信中のHTTPリクエスト／レスポンスを確認したい

• REST API のレスポンスや詳細なJSONエラーを確認したい

• TLS通信の途中で切断される原因を解析したい

• 「接続できない」の原因がTLSなのかアプリなのか切り分けたい

• TLS対応アプリケーション開発を効率化したい

lwIP + mbedTLS 環境で TLS1.2 通信をWiresharkで復号する手順を解説します。

※TLS 1.3 についてはシークレットの種類と出力手順が TLS 1.2 と異なるため、別記事（Tips #2）で解説しています。wolfSSL・OpenSSLは本記事の対象外です。

■ 対象環境

• mbedTLSバージョン： 2.x/3.x/4.x

• lwIPバージョン： 2.x

• TLSバージョン： 1.2

■ この記事で分かること

1. TLS通信をWiresharkで復号する仕組み（NSS Key Log形式）

2. mbedTLS 2.x（〜2.17.x） の `ssl_tls.c` にパッチを当てて、Wiresharkで復号できるキーログを出力する具体的な実装方法

3. mbedTLS 2.x（2.18.0〜）・3.x・4.x でキーログを出力する、より簡単な実装方法（コールバックAPIを使う方法）

4. Wiresharkで平文を確認する手順と動作確認方法

5. 復号できない場合のトラブルシューティング（チェックリスト付き）

■ TLS通信をWiresharkで復号する仕組み

Wiresharkでキャプチャした直後、TLS1.2通信はこのように見えます。

`Application Data` と表示されるだけで、中身は16進数の羅列です。暗号化されて何のデータが流れているか、まったく分かりません。

キーログ（TLS通信の復号に必要な鍵情報を記録したファイル）をWiresharkに設定すると、同じパケットがこのように変わります。

`Decrypted TLS` タブが現れ、暗号化されていた通信の中身が平文で読めるようになります。この記事では、組み込み環境（mbedTLS）でこの状態を実現する方法を解説します。

TLS通信が増えた現在では、MQTT・HTTPS・REST API・WebSocket など様々な通信がTLS上で動作しています。Wiresharkでキャプチャしても中身が見えないため、原因の特定に時間がかかるケースが増えています。

■ PCブラウザやcurlコマンドなら簡単

WiresharkでTLS通信を復号するには、NSS Key Log形式のキーログファイルを使う方法が標準的です。

NSS Key Log形式とは、WiresharkがTLS通信を復号するために使うキーログの形式です。TLS 1.2の場合、1行が次の形式になります。

CLIENT_RANDOM <ClientRandom 32バイト hex> <MasterSecret 48バイト hex>

WindowsやLinuxでChromeやFirefoxを使っている場合、`SSLKEYLOGFILE` 環境変数を設定してブラウザを起動するだけで、キーログが自動的にファイルへ出力されます。

Windowsの例（コマンドプロンプト）：

set SSLKEYLOGFILE=C:\keylog.txt
start chrome

Linuxの例：

export SSLKEYLOGFILE=/tmp/keylog.txt
google-chrome &

あとはWiresharkの設定画面（編集 → 設定 → Protocols → TLS）で `(Pre)-Master-Secret log filename` にそのファイルを指定するだけです。`Application Data` だったパケットが平文で見えるようになります。

ChromeやFirefoxはTLSライブラリに `SSLKEYLOGFILE` の検出機能が組み込まれているため、環境変数を設定するだけで自動的にキーログを出力します。

curl（OpenSSLビルド版）でも同じ環境変数が使えます。なお `--tls-max 1.2` を指定すれば TLS 1.2 に固定できます。

Windowsの例（コマンドプロンプト）：

set SSLKEYLOGFILE=C:\keylog.txt
curl --tls-max 1.2 https://example.com

⚠️ 注意：Windows標準搭載のcurlは動作しない場合があります

Windows 10/11 に標準搭載されている `curl.exe` は、OpenSSL ではなく Windows 独自の Schannel バックエンドでビルドされています。Schannel は `SSLKEYLOGFILE` に対応していないため、環境変数を設定してもキーログが出力されません。

動作しない場合は、curl公式サイト（curl.se/windows） から OpenSSL ビルド版 の curl を入手してください。

Linuxの例：

export SSLKEYLOGFILE=/tmp/keylog.txt
curl --tls-max 1.2 https://example.com

■ 組み込みでは同じようにはできない

組み込み機器でlwIP + mbedTLSを使ってTLS通信を実装している場合、`SSLKEYLOGFILE` 環境変数は使えません。

mbedTLSでTLS1.2のキーログを使用するには、ClientRandomとMasterSecretを出力する処理を追加する必要があります。実装方法はmbedTLSのバージョンによって異なります。

■ 有料パートについて

有料パートでは、lwIP + mbedTLSのTLS通信を復号するための実装例を具体的に解説します。

またlwIPの全体像や、各ベンダーSDKごとの差異、なぜlwIPの不具合情報が重要なのか、といった背景については、導入記事で整理しています。

【lwIP】よくある不具合と対策まとめ｜組み込みTCP/IPトラブル事例集

■ 実装手順

mbedTLS のバージョンによって実装手順が異なります。