javax.net.ssl.SSLPeerUnverifiedException: Hostname Not Verified or Pinning Failure

javax.net.ssl.SSLPeerUnverifiedException is a subclass of SSLException that, in the Java documentation's words, «indicates that the peer's identity has not been verified» (Java SE API). Unlike PKIX path building failed, which says the certificate chain is not trusted, this exception is thrown when trust in the chain is not the question: the certificate is for another name, does not match a pin, or was never received.

Three messages cover almost every report:

• Hostname example.com not verified: followed by the certificate pin, DN and subjectAltNames — OkHttp's host name check (OkHttp ConnectPlan). Apache HttpClient 4.5 says Certificate for <example.com> doesn't match any of the subject alternative names: [...].
• Certificate pinning failure! followed by Peer certificate chain: and Pinned certificates for example.com: — OkHttp's CertificatePinner found no pin that matches the chain.
• peer not authenticated — thrown by the JDK when code asks SSLSession.getPeerCertificates() on a session that has no peer certificates, typically because the handshake did not complete (SSLSessionImpl).

Check the name against the certificate's subjectAltName list, which is what modern clients and the CA/Browser Forum rules rely on; do not count on a name that appears only in the Common Name. The host name in the URL is what is checked, so a request to https://203.0.113.10/ fails against a certificate for api.example.com even when that is the right server. A wildcard covers one label: *.example.com matches api.example.com but not example.com or a.b.example.com.

List the names the server's certificate actually covers, sending the same SNI your app sends:

openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -ext subjectAltName
keytool -printcert -sslserver api.example.com:443 | grep -A3 SubjectAlternativeName

For peer not authenticated, turn on the JSSE debug log for one run and read the last messages before the failure:

java -Djavax.net.debug=ssl:handshake -jar app.jar

For a pinning failure, compute the pin of what the server presents now and compare it with the pins in your code. OkHttp pins are sha256/ plus the base64 SHA-256 of the certificate's public key info:

openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null \
  | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der \
  | openssl dgst -sha256 -binary | openssl enc -base64

The OkHttp exception prints the same hashes for every certificate in the chain, so you can also copy them from the stack trace.

1. Name mismatch: connect with a host name that the certificate lists. If you must reach a server by an internal name or IP, issue a certificate that contains it (an IP needs an IP-address SAN). Do not replace the verifier with NoopHostnameVerifier or a HostnameVerifier that returns true; that accepts a valid certificate for any other site.
2. Wrong server answered: make sure the client sends SNI for the host name (it does when you use the name, not the IP, in the URL) and that DNS resolves to the right machine.
3. Pinning failure after a certificate renewal: pin the public key of an intermediate or root you control the change of, include at least one backup pin, and update the app before you rotate keys. Re-using the same key on renewal keeps leaf pins valid.
4. peer not authenticated: fix the handshake the debug log shows: enable TLS 1.2/1.3 on the server or upgrade an old JDK, or provide the client certificate the server requires.
5. Untrusted chain instead: if the log shows PKIX path building failed earlier, follow the PKIX page: that is a trust store problem, not a name problem.

openssl s_client -connect api.example.com:443 -servername api.example.com -verify_hostname api.example.com </dev/null 2>/dev/null | grep 'Verify return code'
# Verify return code: 0 (ok)

-verify_hostname makes OpenSSL apply the same name check your Java client does. The SSL/TLS checker shows the certificate names and chain your server presents from outside.

• PKIX path building failed — the chain itself is not trusted
• Trust anchor for certification path not found — Android's untrusted-chain message
• ERR_TLS_CERT_ALTNAME_INVALID — the Node.js host name mismatch
• NET::ERR_CERT_COMMON_NAME_INVALID — the browser's name mismatch
• SSL handshake failed — when the handshake behind peer not authenticated breaks