Package okhttp3

Class CertificatePinner

java.lang.Object

okhttp3.CertificatePinner

public final class CertificatePinner
extends Object

Constrains which certificates are trusted. Pinning certificates defends against attacks on certificate authorities. It also prevents connections through man-in-the-middle certificate authorities either known or unknown to the application's user.

This class currently pins a certificate's Subject Public Key Info as described on Adam Langley's Weblog. Pins are either base64 SHA-256 hashes as in HTTP Public Key Pinning (HPKP) or SHA-1 base64 hashes as in Chromium's static certificates.

Setting up Certificate Pinning

The easiest way to pin a host is turn on pinning with a broken configuration and read the expected configuration when the connection fails. Be sure to do this on a trusted network, and without man-in-the-middle tools like Charles or Fiddler.

For example, to pin https://publicobject.com, start with a broken configuration:

   

     String hostname = "publicobject.com";
     CertificatePinner certificatePinner = new CertificatePinner.Builder()
         .add(hostname, "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
         .build();
     OkHttpClient client = OkHttpClient.Builder()
         .certificatePinner(certificatePinner)
         .build();

     Request request = new Request.Builder()
         .url("https://" + hostname)
         .build();
     client.newCall(request).execute();
 

As expected, this fails with a certificate pinning exception:

   

 javax.net.ssl.SSLPeerUnverifiedException: Certificate pinning failure!
   Peer certificate chain:
     sha256/afwiKY3RxoMmLkuRW1l7QsPZTJPwDS2pdDROQjXw8ig=: CN=publicobject.com, OU=PositiveSSL
     sha256/klO23nT2ehFDXCfx3eHTDRESMz3asj1muO+4aIdjiuY=: CN=COMODO RSA Secure Server CA
     sha256/grX4Ta9HpZx6tSHkmCrvpApTQGo67CYDnvprLg5yRME=: CN=COMODO RSA Certification Authority
     sha256/lCppFqbkrlJ3EcVFAkeip0+44VaoJUymbnOaEUk7tEU=: CN=AddTrust External CA Root
   Pinned certificates for publicobject.com:
     sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
   at okhttp3.CertificatePinner.check(CertificatePinner.java)
   at okhttp3.Connection.upgradeToTls(Connection.java)
   at okhttp3.Connection.connect(Connection.java)
   at okhttp3.Connection.connectAndSetOwner(Connection.java)
 

Follow up by pasting the public key hashes from the exception into the certificate pinner's configuration:

   

     CertificatePinner certificatePinner = new CertificatePinner.Builder()
       .add("publicobject.com", "sha256/afwiKY3RxoMmLkuRW1l7QsPZTJPwDS2pdDROQjXw8ig=")
       .add("publicobject.com", "sha256/klO23nT2ehFDXCfx3eHTDRESMz3asj1muO+4aIdjiuY=")
       .add("publicobject.com", "sha256/grX4Ta9HpZx6tSHkmCrvpApTQGo67CYDnvprLg5yRME=")
       .add("publicobject.com", "sha256/lCppFqbkrlJ3EcVFAkeip0+44VaoJUymbnOaEUk7tEU=")
       .build();
 

Pinning is per-hostname and/or per-wildcard pattern. To pin both publicobject.com and www.publicobject.com, you must configure both hostnames.

Wildcard pattern rules:

1. Asterisk * is only permitted in the left-most domain name label and must be the only character in that label (i.e., must match the whole left-most label). For example, *.example.com is permitted, while *a.example.com, a*.example.com, a*b.example.com, a.*.example.com are not permitted.
2. Asterisk * cannot match across domain name labels. For example, *.example.com matches test.example.com but does not match sub.test.example.com.
3. Wildcard patterns for single-label domain names are not permitted.

If hostname pinned directly and via wildcard pattern, both direct and wildcard pins will be used. For example: *.example.com pinned with pin1 and a.example.com pinned with pin2, to check a.example.com both pin1 and pin2 will be used.

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!

Note about self-signed certificates

CertificatePinner can not be used to pin self-signed certificate if such certificate is not accepted by TrustManager.

See Also:

OWASP: Certificate and Public Key Pinning

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	CertificatePinner.Builder	Builds a configured certificate pinner.

Field Summary

Fields

Modifier and Type	Field	Description
static CertificatePinner	DEFAULT

Method Summary

Modifier and Type	Method	Description
void	check(String hostname, Certificate... peerCertificates)	Deprecated. replaced with check(String, List).
void	check(String hostname, List<Certificate> peerCertificates)	Confirms that at least one of the certificates pinned for hostname is in peerCertificates.
boolean	equals(Object other)
int	hashCode()
static String	pin(Certificate certificate)	Returns the SHA-256 of certificate's public key.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT

public static final CertificatePinner DEFAULT

Method Detail

equals

public boolean equals(@Nullable
                      Object other)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

check

public void check(String hostname,
                  List<Certificate> peerCertificates)
           throws SSLPeerUnverifiedException

Confirms that at least one of the certificates pinned for hostname is in peerCertificates. Does nothing if there are no certificates pinned for hostname. OkHttp calls this after a successful TLS handshake, but before the connection is used.

Throws:

SSLPeerUnverifiedException - if peerCertificates don't match the certificates pinned for hostname.

check

public void check(String hostname,
                  Certificate... peerCertificates)
           throws SSLPeerUnverifiedException

Deprecated. replaced with check(String, List).

Throws:

SSLPeerUnverifiedException

pin

public static String pin(Certificate certificate)

Returns the SHA-256 of certificate's public key.

In OkHttp 3.1.2 and earlier, this returned a SHA-1 hash of the public key. Both types are supported, but SHA-256 is preferred.