はじめに
Proxymanを使っているときに「SSL Handshake Failed」というエラーに戸惑っていませんか？本書はそのような疑問に答えるために作りました。目的は、エラーの意味を分かりやすく説明し、原因の見つけ方と対処法を順を追って示すことです。初心者の方でも読み進められるよう、専門用語は必要最小限にとどめ、具体例を交えて解説します。
対象読者:
– ProxymanでHTTPS通信をデバッグする開発者や運用担当者
– SSL/TLSに詳しくないが通信エラーを解決したい人
本書でできること:
– エラー発生時にまず確認すべきポイントを把握できます
– よくある原因と実際の対処手順を学べます
– よくある質問と対応策を参照できます
構成:
第2章: エラーの概要と発生シーン
第3章: 主な原因とチェックポイント
第4章: 具体的な対策・トラブルシューティングフロー
第5章: よくある質問・追加情報
第6章: まとめと参考リンク
まずは落ち着いて順番に確認していきましょう。次章から具体的に説明します。
SSL Handshake Failedの概要と発生シーン
概要
SSL Handshake Failedとは、HTTPS接続の最初のやり取り（ハンドシェイク）で安全な接続が確立できない状態です。簡単に言えば、サーバーとクライアントが「この通信は安全だ」とお互いに確認できないために接続を断念するエラーです。Proxymanなどのプロキシを使ってHTTPSをデバッグする際に特に目にします。
なぜProxymanで起きやすいのか
Proxymanは中間者（プロキシ）として通信を一度受け取り、復号して表示します。そのためProxymanの証明書を端末にインストールし、信頼させる必要があります。証明書や設定に問題があるとハンドシェイクが失敗します。
典型的な発生シーンと具体例
- 証明書未インストール・信頼されていない
- 端末にProxymanのルート証明書が入っていないか、信頼設定が済んでいないと接続が拒否されます。例：iPhoneで証明書をインストールしたが“信頼”を有効にしていない場合。
- 端末の時刻がずれている
- 証明書は有効期間があり、時刻が大きくずれていると無効と判定されます。例：開発用端末の時計が数年ずれている場合。
- アプリ側の証明書ピンニング
- アプリが特定の証明書だけ許可する設定（ピンニング）だと、Proxymanの中間証明書は拒否されます。例：金融系アプリで頻繁に発生します。
- OSやアプリのバージョン差
- 新しいOSのセキュリティ強化やアプリの更新で、以前は通っていたデバッグ方法が使えなくなることがあります。
- ネットワークやプロキシ設定の問題
- VPNや企業ネットワーク、Wi‑Fiのキャプチャ防止設定が干渉する場合があります。
以上のような場面でSSL Handshake Failedが起きやすく、まずは証明書のインストール・信頼設定と端末時刻を確認するのが基本的な出発点です。
主な原因とチェックポイント
この章では、SSLハンドシェイクが失敗する代表的な原因と、現場で確認すべきチェックポイントを分かりやすく説明します。
1) Proxyman（中間プロキシ）証明書の未インストール・未信頼
- チェックポイント：macでは「Keychain Access」で証明書が存在し、信頼済みになっているか確認。iOSでは「設定→一般→プロファイル」や「証明書」項目を確認。ブラウザで接続先の証明書を見て、発行者がProxymanになっているか確認します。
- 対処例：証明書を再インストールして信頼設定を行う。インストール後はブラウザやアプリを再起動します。
2) デバイス／シミュレータの時刻ズレ
- チェックポイント：端末の時刻が正確か、自動時刻が有効かを確認。数分のズレでも検証に影響します。
- 対処例：自動時刻にするか手動で合わせ、必要なら再起動。
3) 証明書の仕様要件違反
- チェックポイント：有効期限、SAN（SubjectAltName）に正しいホスト名が入っているか、署名アルゴリズムが古くないかを確認。macOS 10.15やiOS 13以降で要件が厳しくなっています。iOS 16の一部環境でバグ報告もありますので注意してください。
- 対処例：要件を満たす新しい証明書を作成・適用し、Proxymanやツールを最新版に更新します。
4) ネットワーク設定やVPNの干渉
- チェックポイント：VPNや企業プロキシが通信に介入していないか、別ネットワーク（例：モバイル回線）で同じ問題が出るかを試す。
- 対処例：VPNを一時停止、ネットワーク設定の見直し、DNSキャッシュのクリア。
5) OSや開発環境のバグ・互換性問題
- チェックポイント：OSや開発ツールのバージョン、既知の不具合報告を確認。シミュレータ特有の問題がないかもチェックします。
- 対処例：アップデート適用、別のデバイスや実機で動作確認、公式の回避策を適用。
上記を順に確認すると問題箇所を特定しやすくなります。次章では、これらの項目に対する具体的な対策手順を詳しく解説します。
具体的な対策・トラブルシューティングフロー
前提確認
まず、どの環境でエラーが出ているかを整理します。実機かシミュレータか、iOSのバージョン、ネットワーク（社内LAN／モバイル／VPN）を控えてください。状況を把握すると次の手順が効率よく進みます。
ステップ1：証明書の確認と再インストール
- 有効期限と発行チェーンを確認します。期限切れや中間証明書の欠落が原因のことが多いです。
- 証明書を一度削除して再インストールし、端末で「信頼」設定を確認します（iOSは設定→一般→情報→証明書信頼設定）。
ステップ2：時刻設定の確認
端末とシミュレータの時刻を自動設定（ネットワーク時刻）に戻してください。大きくずれているとハンドシェイクが失敗します。
ステップ3：ネットワークの切り分け
別のWi‑Fiやモバイル通信、VPNをオフにして試します。プロキシやファイアウォールが中間でTLSを破壊することがあります。
ステップ4：TLS仕様とサーバ設定の再確認
サーバ側でサポートしているTLSバージョンや暗号スイートを確認します。iOSの古いバージョンは新しい暗号をサポートしない場合があります。
ステップ5：iOS／シミュレータの切り分け
別のiOSバージョンやクリーンなシミュレータで再現するか試してください。シミュレータのリセット（Reset Content and Settings）も有効です。
ステップ6：ログと接続確認
- クライアントのコンソールログ、サーバのTLSログを確認します。
- opensslやcurlで直接接続確認を行います（例：openssl s_client -connect example.com:443 -servername example.com）。
ステップ7：サービス再起動と最終手順
サーバの再起動、証明書の再発行を行い、端末を再起動して再試行します。上記で改善しない場合は、ログを添えてサーバ管理者や証明書発行者に相談してください。
よくある質問・追加情報
ProxymanでのSSL Proxying有効化
- Proxymanを起動し、対象のドメインやアプリを右クリックして「Enable SSL Proxying」を選びます。例：example.comや、モバイルアプリのバンドルIDを指定します。
- Proxymanのルート証明書をシステムキーチェーンに追加し、信頼するよう設定します（macOSではKeychain Accessで「常に信頼」に変更）。
- iOSでキャプチャする場合は、証明書をインストールしてプロファイルで信頼設定を行います。
カスタム証明書利用時の注意点
- 証明書はシステムキーチェーン（ローカルマシン）に入れ、信頼設定を行ってください。アプリが独自に証明書ピンニングしていると、通信を復号できません。
- 証明書期限や署名アルゴリズム（例：SHA-1は非推奨）を確認してください。期限切れや弱いアルゴリズムだと拒否されます。
macOS/iOSのアップデート後に起きる問題
- OSアップデートで証明書の取り扱いルールが変わることがあります。まずProxymanを最新版に更新し、証明書を再インストールして信頼設定を確認してください。
- ネットワーク設定やプロファイルがリセットされることがあるため、プロキシ設定やVPNの干渉もチェックしてください。
トラブル時の簡単チェックリスト
- 対象ドメインが「Enable SSL Proxying」されているか
- ルート証明書がシステムで信頼されているか
- アプリが証明書ピンニングしていないか（ピンニングあると復号不可）
- ProxymanとOSを最新版にする
- デバイス／アプリを再起動する
これでも解決しない場合は、Proxymanのログやブラウザ/アプリのエラーメッセージを確認し、必要ならProxymanのサポートへお問い合わせください。
まとめと参考リンク
まとめ
SSL Handshake Failedは、証明書の信頼性、プロトコルや暗号スイートの不一致、端末設定、ネットワーク経路の問題が絡んで発生します。発生時は原因を一つずつ切り分け、証明書チェーンと日時、クライアント設定、プロキシやファイアウォールの影響を順に確認してください。ログやキャプチャを残すと再現と原因特定が早まります。
実践的な次のステップ
- 最初に：端末の日時と証明書の有効期限を確認します。
- 証明書検証：中間証明書を含めたチェーンを確認し、不足があれば追加します。
- クライアント設定：TLSバージョンや暗号スイートを最新の推奨設定に合わせます。
- ネットワーク確認：プロキシやTLS復号を行う中間機器の設定をチェックします。
- 記録：エラー時のログ、証明書のダンプ、パケットキャプチャを保存します。
参考リンク
- Proxyman公式ドキュメント: https://proxyman.io/docs
- GitHub Issues（Proxyman）: https://github.com/ProxymanApp/Proxyman/issues
- MozillaのTLSガイド: https://developer.mozilla.org/ja/docs/Web/Security/TLS
- OpenSSLドキュメント: https://www.openssl.org/docs/
追加のヒント
ガイドを実践的にするには、代表的な事例ごとにスクリーンショットやログ例、再現手順を添えてください。これにより同じ症状で悩む人が素早く対応できるようになります。必要ならテンプレート（ログの取り方やキャプチャ手順）も用意すると親切です。
