*
 * ## Warning: Certificate Pinning is Dangerous!
 *
 * Pinning certificates limits your server team's abilities to update their TLS certificates. By
 * pinning certificates, you take on additional operational complexity and limit your ability to
 * migrate between certificate authorities. Do not use certificate pinning without the blessing of
 * your server's TLS administrator!
 *

    // rogue CA is trusted) but it should fail certificate pinning.
    val request =
      Request
        .Builder()
        .url(server.url("/"))
        .build()
    val call = client.newCall(request)
    assertFailsWith<SSLPeerUnverifiedException> {
      call.execute()
    }.also { expected ->
      // Certificate pinning fails!

Use [CertificatePinner](https://square.github.io/okhttp/5.x/okhttp/okhttp3/-certificate-pinner/) to restrict which certificates and 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!**

=== ":material-language-kotlin: Kotlin"
    ```kotlin
      private val client = OkHttpClient.Builder()

    // If the problem was a CertificateException from the X509TrustManager, do not retry.
    e is SSLHandshakeException && e.cause is CertificateException -> false

    // e.g. a certificate pinning error.
    e is SSLPeerUnverifiedException -> false

    // Retry for all other SSL failures.
    e is SSLException -> true

    else -> false

 * certificate.
 *
 * Use of the chain cleaner is necessary to omit unexpected certificates that aren't relevant to
 * the TLS handshake and to extract the trusted CA certificate for the benefit of certificate
 * pinning.
 */
abstract class CertificateChainCleaner {
  @Throws(SSLPeerUnverifiedException::class)
  abstract fun clean(
    chain: List<Certificate>,
    hostname: String,
  ): List<Certificate>

  companion object {

    )
    server.enqueue(MockResponse())
    assertFailsWith<SSLPeerUnverifiedException> {
      val response = execute(url)
      response.close()
    }
  }

  /** Can still coalesce when pinning is used if pins match.  */
  @Test
  fun coalescesWhenCertificatePinsMatch() {
    val pinner =
      CertificatePinner
        .Builder()
        .add("san.com", pin(certificate.certificate))
        .build()

     * If the host platform is compromised or misconfigured this may contain untrustworthy root
     * certificates. Applications that connect to a known set of servers may be able to mitigate
     * this problem with [certificate pinning][CertificatePinner].
     */
    fun addPlatformTrustedCertificates() =
      apply {
        val platformTrustManager = Platform.get().platformTrustManager()

first connect fails. This is necessary for IPv4+IPv6 and services hosted in redundant data
centers. OkHttp supports modern TLS features (TLS 1.3, ALPN, certificate pinning). It can be
configured to fall back for broad connectivity.

Using OkHttp is easy. Its request/response API is designed with fluent builders and immutability. It

      // do not retry.
      if (e.cause is CertificateException) {
        return false
      }
    }
    if (e is SSLPeerUnverifiedException) {
      // e.g. a certificate pinning error.
      return false
    }
    // An example of one we might want to retry with a different route is a problem connecting to a

    // 3. This connection's server certificates must cover the new host.
    if (address.hostnameVerifier !== OkHostnameVerifier) return false
    if (!supportsUrl(address.url)) return false

    // 4. Certificate pinning must match the host.
    try {
      address.certificatePinner!!.check(address.url.host, handshake()!!.peerCertificates)
    } catch (_: SSLPeerUnverifiedException) {
      return false
    }