Okhttp-wiki 之 HTTPS

OkHttp attempts to balance two competing concerns:

  • Connectivity to as many hosts as possible. That includes advanced hosts that run the latest versions of boringssl and less out of date hosts running older versions of OpenSSL.
  • Security of the connection. This includes verification of the remote webserver with certificates and the privacy of data exchanged with strong ciphers.


  • 尽可能多的主机连接.这包括运行最新版本先进的boringssl主机和运行旧版本过时的OpenSSL主机.
  • 连接安全.这包括远程网络服务器证书的验证和用很强的密码交换数据的隐私.

When negotiating a connection to an HTTPS server, OkHttp needs to know which TLS versions and cipher suites to offer. A client that wants to maximize connectivity would include obsolete TLS versions and weak-by-design cipher suites. A strict client that wants to maximize security would be limited to only the latest TLS version and strongest cipher suites.


Specific security vs. connectivity decisions are implemented by ConnectionSpec. OkHttp includes three built-in connection specs:

  • MODERN_TLS is a secure configuration that connects to modern HTTPS servers.
  • COMPATIBLE_TLS is a secure configuration that connects to secure–but not current–HTTPS servers.
  • CLEARTEXT is an insecure configuration that is used for http:// URLs.


  • MODERN_TLS 是一个安全的配置,连接到现有服务器.
  • COMPATIBLE_TLS 是一个安全的配置,连接到安全的但不是现有服务器.
  • CLEARTEXT 是一个不安全的配置, 用于 http:// 的URLs.

By default, OkHttp will attempt a MODERN_TLS connection, and fall back to COMPATIBLE_TLS connection if the modern configuration fails.

默认情况下,OkHttp将尝试 MODERN_TLS 连接,如果现有配置失败则回退至 COMPATIBLE_TLS 连接.

The TLS versions and cipher suites in each spec can change with each release. For example, in OkHttp 2.2 we dropped support for SSL 3.0 in response to the POODLE attack. And in OkHttp 2.3 we dropped support for RC4. As with your desktop web browser, staying up-to-date with OkHttp is the best way to stay secure.

TLS版本和密码组合在每个规格下可以改变每个版本.例如,OkHttp 2.2我们为 POODLE 攻击向下兼容支持SSL3.0;我们在OkHttp 2.3向下兼容支持 RC4.与桌面浏览器相同,保持安全最好的办法是保持OkHttp是最新的.

You can build your own connection spec with a custom set of TLS versions and cipher suites. For example, this configuration is limited to three highly-regarded cipher suites. Its drawback is that it requires Android 5.0+ and a similarly current webserver.

你也可以建立自己的连接规范带有一套定制的TLS版本和密码套件.例如,这个配置仅限于三个主要的密码组合.它的缺点是它需要Android 5.0+和相似的现有网络服务器.

ConnectionSpec spec = new ConnectionSpec.Builder(ConnectionSpec.MODERN_TLS)  

OkHttpClient client = new OkHttpClient.Builder() 

Certificate Pinning 证书锁定

By default, OkHttp trusts the certificate authorities of the host platform. This strategy maximizes connectivity, but it is subject to certificate authority attacks such as the 2011 DigiNotar attack. It also assumes your HTTPS servers’ certificates are signed by a certificate authority.

默认情况下,OkHttp信任主机平台的认证中心.这一策略最大化连接,但受制于2011 DigiNotar attack等认证授权攻击.它还假定HTTPS服务器的证书已经被认证中心签约.

Use CertificatePinner to constrain which certificate authorities are trusted. Certificate pinning increases security, but limits your server team’s abilities to update their TLS certificates. Do not use certificate pinning without the blessing of your server’s TLS administrator!

使用 CertificatePinner 约束所信任的认证中心.证书锁定将增加安全性,但受制于服务器团队的能力来更新他们的TLS证书.不要在没有通知使用你的服务器的TLS管理员的情况下使用证书锁定!

  public CertificatePinning() {
    client = new OkHttpClient.Builder()
        .certificatePinner(new CertificatePinner.Builder()
            .add("publicobject.com", "sha1/DmxUShsZuNiqPQsX2Oi9uv2sCnw=")
            .add("publicobject.com", "sha1/SXxoaOSEzPC6BgGmxAt/EAcsajw=")
            .add("publicobject.com", "sha1/blhOM3W9V/bVQhsWAcLYwPU6n24=")
            .add("publicobject.com", "sha1/T5x9IXmcrQ7YuQxXnxoCmeeQ84c=")

  public void run() throws Exception {
    Request request = new Request.Builder()

    Response response = client.newCall(request).execute();
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

    for (Certificate certificate : response.handshake().peerCertificates()) {

Customizing Trusted Certificates 定制被信任的证书

The full code sample shows how to replace the host platform’s certificate authorities with your own set. As above, do not use custom certificates without the blessing of your server’s TLS administrator!


  private final OkHttpClient client;

  public CustomTrust() {
    SSLContext sslContext = sslContextForTrustedCertificates(trustedCertificatesInputStream());
    client = new OkHttpClient.Builder()

  public void run() throws Exception {
    Request request = new Request.Builder()

    Response response = client.newCall(request).execute();

  private InputStream trustedCertificatesInputStream() {
    ... // Full source omitted. See sample.
        // 详细代码请看官方sample,点击标题链接进入

  public SSLContext sslContextForTrustedCertificates(InputStream in) {
    ... // Full source omitted. See sample.


  1. Okhttp-wiki 之 Home 主页
  2. Okhttp-wiki 之 Calls 调用
  3. Okhttp-wiki 之 Connections 连接
  4. Okhttp-wiki 之 Recipes 秘诀(食谱)
  5. Okhttp-wiki 之 Interceptors 拦截器
  6. Okhttp-wiki 之 HTTPS


  • HTTPS OkHttp attempts to balance two competing concerns: ...
    雪晨杰阅读 473评论 0 0
  • Although you provide only the URL, OkHttp plans its conne...
    汉之风云阅读 2,526评论 0 50
  • OkHttp 试图平衡两种竞争的担忧: Connectivity连接到尽可能多的主机。包括运行最新版本boring...
    谈小龙阅读 3,217评论 0 2
  • 具体怎么来说我对这两个字的理解,我也不知道怎么讲起。倒是想起李清照的一首词里的句子~衣带渐宽终不悔,为伊...
    一个点跳到另一个点阅读 98评论 0 4
  • 《三字经》曰:“养不教、父之过,教不严、师之惰。子不学、非所宜,幼不学、老何为?” 度此言,吾觉非也。我的观点是:...
    杨志刚_785e阅读 105评论 0 2