1. 问题现象与背景分析最近在Android开发中使用Retrofit请求本地测试服务器https://192.168.43.73:8080时遇到了Handshake failed的错误。这个错误通常发生在SSL/TLS握手阶段表明客户端和服务器未能成功建立安全连接。让我先还原一下典型的错误场景// Retrofit初始化代码 Retrofit retrofit new Retrofit.Builder() .baseUrl(https://192.168.43.73:8080/) .client(new OkHttpClient()) .build(); // 执行请求时报错 try { Response response myApi.getData().execute(); } catch (IOException e) { // 抛出 javax.net.ssl.SSLHandshakeException: Handshake failed Log.e(Retrofit, 请求失败, e); }这个错误背后有几个关键点需要注意我们使用的是HTTPS协议而非HTTP目标地址是本地局域网IP192.168.x.x端口是非标准HTTPS端口8080而非443错误发生在握手阶段而非后续通信阶段2. HTTPS握手失败的核心原因排查2.1 证书信任问题本地开发环境通常使用自签名证书而Android系统默认不会信任这类证书。当Retrofit底层使用OkHttp尝试建立连接时系统证书验证失败就会抛出HandshakeException。验证方法在浏览器中访问相同URL查看证书警告内容。如果浏览器提示此网站的安全证书有问题则确认是证书信任问题。2.2 TLS版本不匹配服务器和客户端支持的TLS版本不一致也会导致握手失败。Android 5.0以下默认只支持TLS 1.0而现代服务器可能已禁用不安全的TLS版本。检查方法在服务器端运行openssl s_client -connect 192.168.43.73:8080 -tls1_2查看是否能成功连接。2.3 证书链不完整服务器配置不当可能导致证书链不完整某些Android设备对此检查更严格。使用以下命令检查openssl s_client -showcerts -connect 192.168.43.73:80803. 解决方案与实现步骤3.1 临时方案信任所有证书仅限开发环境对于开发测试可以配置OkHttp信任所有证书OkHttpClient unsafeClient new OkHttpClient.Builder() .sslSocketFactory(getUnsafeSSLSocketFactory(), getUnsafeTrustManager()) .hostnameVerifier((hostname, session) - true) .build(); // 然后在Retrofit中使用这个client Retrofit retrofit new Retrofit.Builder() .baseUrl(https://192.168.43.73:8080/) .client(unsafeClient) .build();配套工具方法private static SSLSocketFactory getUnsafeSSLSocketFactory() { try { SSLContext sslContext SSLContext.getInstance(SSL); sslContext.init(null, getUnsafeTrustManager(), new SecureRandom()); return sslContext.getSocketFactory(); } catch (Exception e) { throw new RuntimeException(e); } } private static TrustManager[] getUnsafeTrustManager() { return 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[]{}; } } }; }警告此方案会完全禁用SSL验证存在严重安全风险绝对不要用于生产环境3.2 推荐方案正确配置证书信任3.2.1 导出服务器证书从服务器导出证书假设使用OpenSSLopenssl s_client -connect 192.168.43.73:8080 -showcerts /dev/null | openssl x509 -outform PEM server.crt3.2.2 将证书打包到Android应用将server.crt放入res/raw/目录创建自定义TrustManagerprivate OkHttpClient getSafeClient(Context context) { try { // 加载证书 CertificateFactory cf CertificateFactory.getInstance(X.509); InputStream certInput context.getResources().openRawResource(R.raw.server); Certificate ca cf.generateCertificate(certInput); // 创建KeyStore String keyStoreType KeyStore.getDefaultType(); KeyStore keyStore KeyStore.getInstance(keyStoreType); keyStore.load(null, null); keyStore.setCertificateEntry(ca, ca); // 创建TrustManager String tmfAlgorithm TrustManagerFactory.getDefaultAlgorithm(); TrustManagerFactory tmf TrustManagerFactory.getInstance(tmfAlgorithm); tmf.init(keyStore); // 创建SSLContext SSLContext sslContext SSLContext.getInstance(TLS); sslContext.init(null, tmf.getTrustManagers(), null); return new OkHttpClient.Builder() .sslSocketFactory(sslContext.getSocketFactory(), (X509TrustManager)tmf.getTrustManagers()[0]) .build(); } catch (Exception e) { throw new RuntimeException(e); } }3.3 进阶配置TLS版本控制针对不同Android版本可以强制指定TLS版本ConnectionSpec spec new ConnectionSpec.Builder(ConnectionSpec.MODERN_TLS) .tlsVersions(TlsVersion.TLS_1_2, TlsVersion.TLS_1_3) .build(); OkHttpClient client new OkHttpClient.Builder() .connectionSpecs(Collections.singletonList(spec)) .build();4. 调试技巧与日志分析4.1 启用OkHttp详细日志添加日志拦截器查看完整握手过程HttpLoggingInterceptor logging new HttpLoggingInterceptor(); logging.setLevel(HttpLoggingInterceptor.Level.BODY); OkHttpClient client new OkHttpClient.Builder() .addInterceptor(logging) .build();典型错误日志分析certificate_unknown证书信任问题tls_version_not_supportedTLS版本不匹配unable_to_get_issuer_cert证书链不完整4.2 使用Stetho进行网络调试Facebook的Stetho工具可以实时查看网络请求// 在Application中初始化 Stetho.initializeWithDefaults(this); // 配置OkHttpClient OkHttpClient client new OkHttpClient.Builder() .addNetworkInterceptor(new StethoInterceptor()) .build();5. 生产环境最佳实践5.1 证书固定Certificate Pinning防止中间人攻击的有效方法OkHttpClient client new OkHttpClient.Builder() .certificatePinner(new CertificatePinner.Builder() .add(192.168.43.73, sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA) .build()) .build();获取证书指纹的方法openssl s_client -connect 192.168.43.73:8080 | openssl x509 -pubkey | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base645.2 安全配置检查清单使用权威CA签发的证书禁用不安全的TLS版本1.0和1.1启用证书撤销检查CRL/OCSP定期更新证书不超过1年有效期监控证书到期时间6. 常见问题解答6.1 为什么在模拟器上能运行真机却失败模拟器通常使用宿主机的网络配置而真机可能有不同的TLS实现运营商中间件干扰系统安全策略限制6.2 如何兼容Android 4.x等旧版本需要额外配置ConnectionSpec legacyTls new ConnectionSpec.Builder(ConnectionSpec.MODERN_TLS) .tlsVersions(TlsVersion.TLS_1_0, TlsVersion.TLS_1_1) .build(); OkHttpClient client new OkHttpClient.Builder() .connectionSpecs(Arrays.asList(modernTls, legacyTls)) .build();6.3 使用Charles等抓包工具后出现握手失败抓包工具会注入自己的根证书需要在设备上安装Charles根证书配置OkHttp信任该证书或者临时禁用抓包工具7. 性能优化建议复用OkHttpClient实例避免每次创建新实例启用连接池默认已开启合理设置超时时间OkHttpClient client new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .writeTimeout(15, TimeUnit.SECONDS) .build();8. 替代方案比较方案安全性实现难度适用场景信任所有证书低简单开发测试自定义信任证书中中等企业内网权威CA证书高复杂生产环境证书固定最高中等高安全要求在实际项目中我通常会根据环境使用不同配置。开发阶段使用信任所有证书的方案快速验证测试阶段切换为自定义证书上线时则必须使用权威CA签发的证书。
Android Retrofit HTTPS握手失败解决方案
1. 问题现象与背景分析最近在Android开发中使用Retrofit请求本地测试服务器https://192.168.43.73:8080时遇到了Handshake failed的错误。这个错误通常发生在SSL/TLS握手阶段表明客户端和服务器未能成功建立安全连接。让我先还原一下典型的错误场景// Retrofit初始化代码 Retrofit retrofit new Retrofit.Builder() .baseUrl(https://192.168.43.73:8080/) .client(new OkHttpClient()) .build(); // 执行请求时报错 try { Response response myApi.getData().execute(); } catch (IOException e) { // 抛出 javax.net.ssl.SSLHandshakeException: Handshake failed Log.e(Retrofit, 请求失败, e); }这个错误背后有几个关键点需要注意我们使用的是HTTPS协议而非HTTP目标地址是本地局域网IP192.168.x.x端口是非标准HTTPS端口8080而非443错误发生在握手阶段而非后续通信阶段2. HTTPS握手失败的核心原因排查2.1 证书信任问题本地开发环境通常使用自签名证书而Android系统默认不会信任这类证书。当Retrofit底层使用OkHttp尝试建立连接时系统证书验证失败就会抛出HandshakeException。验证方法在浏览器中访问相同URL查看证书警告内容。如果浏览器提示此网站的安全证书有问题则确认是证书信任问题。2.2 TLS版本不匹配服务器和客户端支持的TLS版本不一致也会导致握手失败。Android 5.0以下默认只支持TLS 1.0而现代服务器可能已禁用不安全的TLS版本。检查方法在服务器端运行openssl s_client -connect 192.168.43.73:8080 -tls1_2查看是否能成功连接。2.3 证书链不完整服务器配置不当可能导致证书链不完整某些Android设备对此检查更严格。使用以下命令检查openssl s_client -showcerts -connect 192.168.43.73:80803. 解决方案与实现步骤3.1 临时方案信任所有证书仅限开发环境对于开发测试可以配置OkHttp信任所有证书OkHttpClient unsafeClient new OkHttpClient.Builder() .sslSocketFactory(getUnsafeSSLSocketFactory(), getUnsafeTrustManager()) .hostnameVerifier((hostname, session) - true) .build(); // 然后在Retrofit中使用这个client Retrofit retrofit new Retrofit.Builder() .baseUrl(https://192.168.43.73:8080/) .client(unsafeClient) .build();配套工具方法private static SSLSocketFactory getUnsafeSSLSocketFactory() { try { SSLContext sslContext SSLContext.getInstance(SSL); sslContext.init(null, getUnsafeTrustManager(), new SecureRandom()); return sslContext.getSocketFactory(); } catch (Exception e) { throw new RuntimeException(e); } } private static TrustManager[] getUnsafeTrustManager() { return 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[]{}; } } }; }警告此方案会完全禁用SSL验证存在严重安全风险绝对不要用于生产环境3.2 推荐方案正确配置证书信任3.2.1 导出服务器证书从服务器导出证书假设使用OpenSSLopenssl s_client -connect 192.168.43.73:8080 -showcerts /dev/null | openssl x509 -outform PEM server.crt3.2.2 将证书打包到Android应用将server.crt放入res/raw/目录创建自定义TrustManagerprivate OkHttpClient getSafeClient(Context context) { try { // 加载证书 CertificateFactory cf CertificateFactory.getInstance(X.509); InputStream certInput context.getResources().openRawResource(R.raw.server); Certificate ca cf.generateCertificate(certInput); // 创建KeyStore String keyStoreType KeyStore.getDefaultType(); KeyStore keyStore KeyStore.getInstance(keyStoreType); keyStore.load(null, null); keyStore.setCertificateEntry(ca, ca); // 创建TrustManager String tmfAlgorithm TrustManagerFactory.getDefaultAlgorithm(); TrustManagerFactory tmf TrustManagerFactory.getInstance(tmfAlgorithm); tmf.init(keyStore); // 创建SSLContext SSLContext sslContext SSLContext.getInstance(TLS); sslContext.init(null, tmf.getTrustManagers(), null); return new OkHttpClient.Builder() .sslSocketFactory(sslContext.getSocketFactory(), (X509TrustManager)tmf.getTrustManagers()[0]) .build(); } catch (Exception e) { throw new RuntimeException(e); } }3.3 进阶配置TLS版本控制针对不同Android版本可以强制指定TLS版本ConnectionSpec spec new ConnectionSpec.Builder(ConnectionSpec.MODERN_TLS) .tlsVersions(TlsVersion.TLS_1_2, TlsVersion.TLS_1_3) .build(); OkHttpClient client new OkHttpClient.Builder() .connectionSpecs(Collections.singletonList(spec)) .build();4. 调试技巧与日志分析4.1 启用OkHttp详细日志添加日志拦截器查看完整握手过程HttpLoggingInterceptor logging new HttpLoggingInterceptor(); logging.setLevel(HttpLoggingInterceptor.Level.BODY); OkHttpClient client new OkHttpClient.Builder() .addInterceptor(logging) .build();典型错误日志分析certificate_unknown证书信任问题tls_version_not_supportedTLS版本不匹配unable_to_get_issuer_cert证书链不完整4.2 使用Stetho进行网络调试Facebook的Stetho工具可以实时查看网络请求// 在Application中初始化 Stetho.initializeWithDefaults(this); // 配置OkHttpClient OkHttpClient client new OkHttpClient.Builder() .addNetworkInterceptor(new StethoInterceptor()) .build();5. 生产环境最佳实践5.1 证书固定Certificate Pinning防止中间人攻击的有效方法OkHttpClient client new OkHttpClient.Builder() .certificatePinner(new CertificatePinner.Builder() .add(192.168.43.73, sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA) .build()) .build();获取证书指纹的方法openssl s_client -connect 192.168.43.73:8080 | openssl x509 -pubkey | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base645.2 安全配置检查清单使用权威CA签发的证书禁用不安全的TLS版本1.0和1.1启用证书撤销检查CRL/OCSP定期更新证书不超过1年有效期监控证书到期时间6. 常见问题解答6.1 为什么在模拟器上能运行真机却失败模拟器通常使用宿主机的网络配置而真机可能有不同的TLS实现运营商中间件干扰系统安全策略限制6.2 如何兼容Android 4.x等旧版本需要额外配置ConnectionSpec legacyTls new ConnectionSpec.Builder(ConnectionSpec.MODERN_TLS) .tlsVersions(TlsVersion.TLS_1_0, TlsVersion.TLS_1_1) .build(); OkHttpClient client new OkHttpClient.Builder() .connectionSpecs(Arrays.asList(modernTls, legacyTls)) .build();6.3 使用Charles等抓包工具后出现握手失败抓包工具会注入自己的根证书需要在设备上安装Charles根证书配置OkHttp信任该证书或者临时禁用抓包工具7. 性能优化建议复用OkHttpClient实例避免每次创建新实例启用连接池默认已开启合理设置超时时间OkHttpClient client new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .writeTimeout(15, TimeUnit.SECONDS) .build();8. 替代方案比较方案安全性实现难度适用场景信任所有证书低简单开发测试自定义信任证书中中等企业内网权威CA证书高复杂生产环境证书固定最高中等高安全要求在实际项目中我通常会根据环境使用不同配置。开发阶段使用信任所有证书的方案快速验证测试阶段切换为自定义证书上线时则必须使用权威CA签发的证书。
