HTTPS 与 TLS 基础配置：SSLSocketFactory、HostnameVerifier、证书校验

在 OkHttp 接口防护中，HTTPS 不仅依赖 URL 前缀，还需要在底层配置 SSL/TLS 握手参数。OkHttp 通过 SSLSocketFactory 自定义加密套件和协议版本，通过 HostnameVerifier 校验服务器域名与证书的匹配性，并支持双向证书校验。本章从原理出发，给出完整的配置流程、代码示例、调试方法及常见错误处理。

3.1 核心概念与原理

TLS 握手阶段，客户端需要确认服务器身份（单向认证），或双方相互认证（双向认证）。OkHttp 将这些控制权委托给三个关键组件：

// 典型 TLS 握手核心逻辑（伪代码）
SSLSocketFactory factory = SSLContext.getInstance("TLSv1.3")       // 协议版本
    .init(keyManager, trustManager, secureRandom)
    .getSocketFactory();
OkHttpClient client = new OkHttpClient.Builder()
    .sslSocketFactory(factory, trustManager)  // 提供信任管理器
    .hostnameVerifier(new StrictHostnameVerifier())
    .build();

3.2 实现流程与代码示例

以下从最严格的配置开始，逐步给出实际代码。

3.2.1 自定义 SSLSocketFactory（限用 TLSv1.3、指定密码套件）

// 创建安全 SSLContext，只启用 TLSv1.3
SSLContext sslContext = SSLContext.getInstance("TLSv1.3");
TrustManager[] trustManagers = new TrustManager[]{
    new X509TrustManager() {
        @Override public void checkClientTrusted(X509Certificate[] chain, String authType) {}
        @Override public void checkServerTrusted(X509Certificate[] chain, String authType) {}
        @Override public X509Certificate[] getAcceptedIssuers() { return new X509Certificate[0]; }
    }
};
sslContext.init(null, trustManagers, new SecureRandom());

// 获取 SSLSocketFactory
SSLSocketFactory factory = sslContext.getSocketFactory();

// 应用到 OkHttpClient
OkHttpClient client = new OkHttpClient.Builder()
    .sslSocketFactory(factory, (X509TrustManager) trustManagers[0])
    .hostnameVerifier(OkHostnameVerifier.INSTANCE)
    .build();

3.2.2 自定义 HostnameVerifier（拒绝域名不匹配）

OkHttpClient client = new OkHttpClient.Builder()
    .hostnameVerifier(new HostnameVerifier() {
        @Override
        public boolean verify(String hostname, SSLSession session) {
            // 只允许特定域名通过校验
            return hostname.equals("api.secure-example.com")
                   && session.getPeerPrincipal() != null;
        }
    })
    .build();

3.2.3 证书锁定（CertificatePinner）

// 方式一：锁定公钥指纹（SHA-256 base64）
CertificatePinner pinner = new CertificatePinner.Builder()
    .add("api.secure-example.com", 
         "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")  // 示例指纹
    .add("api.secure-example.com",
         "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=")  // 备用指纹
    .build();

OkHttpClient client = new OkHttpClient.Builder()
    .certificatePinner(pinner)
    .build();

3.3 内联 SVG：TLS 握手与证书校验流程

下图为 OkHttp 启用自定义 SSL 配置后的完整握手与校验流程：

3.4 调试与日志

启用 OkHttp 的 Wire 级别日志可观察 TLS 握手详情：

// 在 OkHttpClient 构建时添加拦截器
HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
logging.setLevel(HttpLoggingInterceptor.Level.BODY);
// 或使用 BODY 级别查看证书详情
client = client.newBuilder()
    .addInterceptor(logging)
    .build();

TLS 握手阶段的常见日志输出：

D/OkHttp: <-- 200 OK https://api.example.com/path (325ms)
D/OkHttp: Connection: keep-alive
D/OkHttp: Content-Type: application/json
D/OkHttp: 
D/OkHttp: {"status":"ok"}

若发生握手失败，日志会包含 javax.net.ssl.SSLHandshakeException 及具体原因，如证书链不完整、域名不匹配、证书过期或未知 CA。

3.5 部署注意事项

• 证书链完整：服务器须发送完整链（包含中间证书），否则 Android 4.x 以下设备可能报错。
• 证书更换：CertificatePinner 锁定公钥时，至少保留一个备用指纹（新证书指纹），避免到期前服务中断。
• 兼容性：Android 5.0+ 原生支持 TLSv1.2，建议在 AndroidManifest.xml 的 <application> 中添加 android:networkSecurityConfig 作为兜底策略。

3.6 常见错误与解决方案

3.7 性能与稳定性优化

• 复用 SSLSocketFactory：创建 SSLContext 非常昂贵，应当作为单例缓存，所有请求共用同一个工厂。
• 避免每次请求建立新连接：OkHttp 默认开启连接池，如需自定义 TLS 参数，确保使用 ConnectionPool 复用。
• 协议降级：某些老旧服务器只支持 TLSv1.1，此时需在 SSLContext.getInstance("TLS") 后通过 SSLParameters 设置 setProtocols(new String[]{"TLSv1.1","TLSv1.2"})，但必须设置超时时间，避免因协议协商导致慢连接。
• 证书固定更新策略：使用远程配置下发最新的指纹列表，避免升级客户端才能更换证书。

// 推荐：全局单例 SSLContext
public class SSLContextHolder {
    private static final SSLContext SSL_CONTEXT = createContext();
    
    private static SSLContext createContext() {
        try {
            SSLContext ctx = SSLContext.getInstance("TLSv1.3");
            ctx.init(null, new TrustManager[]{new MyTrustManager()}, null);
            return ctx;
        } catch (Exception e) {
            throw new RuntimeException("Failed to initialize SSLContext", e);
        }
    }
    
    public static SSLSocketFactory getSocketFactory() {
        return SSL_CONTEXT.getSocketFactory();
    }
}