OkHttpで始める「証明書ピン留め（Certificate Pinning）」超入門

はじめに

Androidアプリの開発において、HTTPS通信はもはや必須です。しかし、単に https:// を使うだけでは、中間者攻撃（MitM）などの高度なセキュリティ脅威を完全に防ぐことはできません。

この記事では、Androidのデファクトスタンダードである通信ライブラリ OkHttp（Kotlin） を使い、アプリの安全性を劇的に高める「証明書ピン留め（Certificate Pinning）」の実装方法と、陥りがちな罠について解説します。

---

なぜ「常時HTTPS」だけでは不十分なのか？

通常のHTTPS通信では、Androidシステムに内蔵されている信頼されたCA（認証局）のリストをベースに、サーバーの証明書が正当かどうかを検証します。

しかし、以下のようなリスクが存在します：

• ユーザーが不正なフリーWi-Fiに接続し、悪意のあるCA証明書をデバイスにインストールさせられた場合
• 信頼されている大手のCA自体がハッキングされ、偽のルート証明書が発行された場合

このような場合、システムは「正規の証明書」と判断してしまうため、通信が盗聴・改ざんされる（中間者攻撃）危険性があります。

---

証明書ピン留め（Certificate Pinning）とは？

「システムが信頼しているCA」を盲信するのをやめ、「アプリが指定した特定のサーバー公開鍵（ハッシュ値）以外との通信は、たとえCAが承認していても絶対に拒否する」 という強力な防御手法です。

---

OkHttpでの実装コード（Kotlin）

OkHttp 4.x / 5.x（Kotlinファースト）では、CertificatePinner クラスを使用することで、非常にシンプルに実装できます。

import okhttp3.CertificatePinner
import okhttp3.OkHttpClient
import okhttp3.Request
import java.io.IOException

fun createSecureHttpClient(): OkHttpClient {
    // 1. CertificatePinner の作成（ドメインとSHA-256ハッシュを指定）
    val certificatePinner = CertificatePinner.Builder()
        // メインの公開鍵ハッシュ
        .add("yourdomain.com", "sha256/Base64EncodedSha256HashHere=")
        // 🔥【超重要】緊急時・証明書更新用のバックアップ公開鍵ハッシュ
        .add("yourdomain.com", "sha256/BackupBase64EncodedSha256HashHere=")
        // サブドメインも一括してロックする場合はワイルドカード（*.）が使用可能
        // ⚠️ 注意：配下のサブドメイン全てに同じピンが適用されるため、
        //    サブドメインごとに鍵が異なる場合は意図しない通信拒否が起きる
        .add("*.yourdomain.com", "sha256/SubDomainSha256HashHere=")
        .build()

    // 2. OkHttpClient にピン留め設定を注入
    return OkHttpClient.Builder()
        .certificatePinner(certificatePinner)
        .build()
}

fun fetchSecureData() {
    val client = createSecureHttpClient()
    val request = Request.Builder()
        .url("https://yourdomain.com/api/v1/data")
        .build()

    // Kotlinの `.use` を使ってレスポンスを確実にクローズ
    try {
        client.newCall(request).execute().use { response ->
            if (!response.isSuccessful) throw IOException("Unexpected code $response")
            println(response.body?.string())
        }
    } catch (e: IOException) {
        // ピン留め検証に失敗した場合は SSLPeerUnverifiedException がスローされる
        e.printStackTrace()
    }
}

⚠️ 重要な制約： CertificatePinner は OkHttp 経由の通信にのみ 有効です。HttpsURLConnection や WebView など他の通信経路には効きません。アプリ全体をカバーしたい場合は、後述の Network Security Config との併用を検討してください。

---

なぜ「.crt」ファイルを使ってはいけないのか？

初学者が陥りがちな罠として、「サーバーから .crt や .cer ファイルをもらって、アプリの assets フォルダに突っ込んで検証しようとする」というものがあります。

OkHttpの標準的なアプローチでは、ファイルではなく 「公開鍵のハッシュ値（文字列）」 をピン留めします。これには大きな理由があります。

証明書ファイル（.crt）の寿命は非常に短い

SSL証明書の有効期限は年々短縮される傾向にあり、2025年以降はCA/Browser Forumの決議（Apple主導）により、業界標準が 最大47日 へ短縮される方向で進んでいます。証明書ファイルを丸ごとアプリに埋め込むと、証明書が更新されるたびにアプリのアップデートが必要になり、事実上の運用は不可能です。

公開鍵（Public Key）は使い回せる

証明書の有効期限が切れて新しく更新（再署名）する際、サーバーの「秘密鍵と公開鍵のペア」を変更せずに使い回すことができます。公開鍵が変わらなければSHA-256のハッシュ値も変わらないため、アプリをアップデートすることなく、サーバー側の証明書だけを安全に更新可能 です。

---

開発時に役立つ「正しいハッシュ値」の簡単な取得方法

「サーバーの公開鍵のSHA-256ハッシュってどうやって調べるの？」という場合、一番手っ取り早いのが 「わざと間違ったハッシュを設定してエラーを起こす」 方法です。

適当なダミー値（例：sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=）を設定して通信を走らせると、OkHttpは正しいハッシュ値をログに出力した上で通信を遮断（SSLPeerUnverifiedException）してくれます。

ログの出力例：

javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure!
  Peer certificate chain:
    sha256/p9XyZ... (★これがサーバーから送られてきた実際の正しいハッシュ値)
  Pinned certificates for yourdomain.com:
    sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=

Peer certificate chain に表示されたハッシュ値をコピーしてコードに貼り付けるのが、最も確実で手軽な方法です。

注意： この方法はあくまで開発・検証時のみの手順です。本番環境への適用前に、サーバー管理者から公式に提供されたハッシュ値と必ず照合してください。

---

Network Security Config との使い分け

Android 7.0（API 24）以降では、XMLベースの Network Security Config を使ってもピン留めが設定できます。

<!-- res/xml/network_security_config.xml -->
<network-security-config>
    <domain-config>
        <domain includeSubdomains="false">yourdomain.com</domain>
        <pin-set expiration="2026-01-01">
            <pin digest="SHA-256">Base64EncodedSha256HashHere=</pin>
            <!-- バックアップピン -->
            <pin digest="SHA-256">BackupBase64EncodedSha256HashHere=</pin>
        </pin-set>
    </domain-config>
</network-security-config>
<!-- AndroidManifest.xml -->
<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >

OkHttp の CertificatePinner vs Network Security Config

比較項目	OkHttp CertificatePinner	Network Security Config
適用範囲	OkHttp 経由の通信のみ	アプリ全通信（WebView含む）
設定方法	コード（Kotlin/Java）	XML ファイル
expiration 設定	なし	あり（期限切れで自動無効化）
柔軟性	高い（動的変更も可能）	低い（静的な設定）
主な用途	OkHttpを使うAPIクライアント	アプリ全体のセキュリティポリシー

推奨： OkHTTP を使う API 通信には CertificatePinner、WebView やその他の通信も含めてアプリ全体をカバーしたい場合は Network Security Config を、状況に応じて組み合わせて使うのがベストプラクティスです。

---

運用上の最大のリスクと「バックアップピン」

証明書ピン留めを導入する上で、絶対に忘れてはならないのが 「バックアップ用のピン（Backup Pins）の登録」 です。

メインの公開鍵ハッシュのみ登録している状態で、以下のような事態が起きると：

• サーバーの秘密鍵が漏洩して緊急で鍵ペアを変更した
• サーバー管理者が誤って新しい鍵ペアで証明書を更新した

配信済みのすべての古いアプリが即座にサーバーと通信できなくなります。修正版のリリースとユーザーのアップデートが完了するまで、サービスは完全停止します。

対策： 必ず将来使用予定のバックアップ公開鍵ハッシュ、または上位の信頼できるCA（中間CAなど）のハッシュを最低1つは予備として登録しておきましょう。

---

ピン留めをバイパスされるリスクについて

証明書ピン留めは強力な防御手段ですが、万能ではありません。以下のような手法でバイパスされる可能性があります：

• ルート化端末 + Frida などのフッキングツール： ランタイムで CertificatePinner の検証ロジックを書き換えることが可能です
• 逆コンパイルによるコード改ざん： APK を解析してピン留め処理を無効化した改造版アプリを作られる可能性があります

完全な対策のためには、ピン留めと合わせて以下も検討してください：

• Root 検出 / 改ざん検出（SafetyNet Attestation / Play Integrity API）
• コード難読化（R8 / ProGuard）
• アンチデバッグ対策

証明書ピン留めは「多層防御（Defense in Depth）」の一部として位置づけるのが適切です。

---

まとめ

ポイント	内容
実装方法	OkHttpの CertificatePinner を使う
ピン留め対象	.crt ファイルではなく、公開鍵のSHA-256ハッシュ
ハッシュ取得	開発時はわざとエラーを起こしてログから取得すると楽
バックアップ	バックアップピンの登録は必須（運用事故防止）
有効期限の短縮	2025年以降、SSL証明書は最大47日に短縮の方向。公開鍵ピン留めの重要性が増している
適用範囲	OkHttp以外の通信も保護したい場合は Network Security Config を併用
限界と注意	ルート化端末・フッキングツールによるバイパスのリスクがある。多層防御の一部として捉える

正しく導入して、中間者攻撃に負けない堅牢なAndroidアプリを構築しましょう！

---