Aplicações Java lançam a exceção javax.net.ssl.SSLHandshakeException: PKIX path building failed quando a cadeia de certificados do servidor está incompleta ou o truststore do JDK no cliente não inclui o certificado raiz necessário. Identifique a causa aplicável e siga a correção correspondente.
Sintomas
Uma aplicação Java que se conecta a um endpoint HTTPS falha com a seguinte mensagem:
javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested targetO mesmo endereço HTTPS funciona normalmente em navegadores como Chrome ou Firefox (exibindo o ícone de cadeado de segurança), enquanto clientes que não são navegadores — aplicações Java, curl, wget — relatam falha no handshake TLS ou erro de verificação de certificado.
Por que navegadores funcionam, mas o Java falha: Navegadores modernos implementam o recurso AIA (Authority Information Access) chasing. Quando um servidor envia uma cadeia de certificados incompleta, os navegadores baixam automaticamente os certificados intermediários ausentes para completá-la. Clientes Java não fazem isso; eles exigem que o servidor envie a cadeia completa durante o handshake TLS.
Causas
Causa 1: Cadeia de certificados do servidor incompleta. O servidor envia apenas o certificado do servidor (certificado de nome de domínio) e omite os certificados intermediários que o vinculam a uma raiz confiável. Clientes Java não conseguem construir a cadeia de confiança e rejeitam a conexão.
Causa 2: Truststore do JDK desatualizado. O servidor envia uma cadeia completa, mas o truststore do JDK no cliente (
$JAVA_HOME/jre/lib/security/cacerts) não inclui o certificado raiz ou o certificado raiz com assinatura cruzada utilizado pela cadeia. Isso geralmente ocorre em versões mais antigas do JDK. Por exemplo, após a DigiCert migrar da raiz G1 para a raiz G2, versões antigas do JDK deixaram de confiar na raiz G2. Para mais detalhes, consulte Anúncio de substituição do certificado raiz da DigiCert.
Diagnosticar o servidor
Antes de aplicar uma correção, confirme se o servidor está enviando uma cadeia de certificados completa. Use uma das opções abaixo:
Opção A: Comando OpenSSL (requer OpenSSL)
Execute o comando abaixo, substituindo your.domain.com:443 pelo endpoint real do seu servidor.
# Connect to the server and display the certificate chain it provides
openssl s_client -connect your.domain.com:443 -showcertsOpção B: SSL Labs Server Test (não requer CLI)
Acesse https://www.ssllabs.com/ssltest/, insira seu domínio e verifique o campo Chain issues no relatório. O valor None indica que a cadeia está completa; Incomplete ou Extra download significa que o servidor não está enviando os certificados intermediários necessários.
Interpretar a saída do OpenSSL
Cadeia incompleta (Causa 1)
A seção Certificate chain mostra apenas uma entrada (depth=0). O código de retorno da verificação é diferente de zero:
Certificate chain
0 s:/CN=your.domain.com
i:/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
---
Server certificate
-----BEGIN CERTIFICATE-----
(Server certificate content)
-----END CERTIFICATE-----
...
Verify return code: 20 (unable to get local issuer certificate)Cadeia completa (íntegra)
A saída contém múltiplos certificados formando uma cadeia ordenada de depth=0 (certificado do servidor) até depth=1 (certificado intermediário). O código de retorno da verificação é 0 (ok):
Certificate chain
0 s:/CN=your.domain.com
i:/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
1 s:/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
i:/C=US/O=DigiCert Inc/CN=DigiCert Global Root CA
---
...
Verify return code: 0 (ok)Se a cadeia estiver completa, mas o cliente Java ainda falhar, pule para Corrigir um truststore do JDK desatualizado.
Corrigir uma cadeia de certificados do servidor incompleta
Reconfigure o servidor para enviar a cadeia completa. Este procedimento aplica-se a servidores web como NGINX, Apache e Tomcat, além de balanceadores de carga como Server Load Balancer (SLB).
Obtenha o pacote completo da cadeia de certificados junto à sua autoridade certificadora (CA). Esse arquivo normalmente contém o certificado do servidor seguido por todos os certificados intermediários e geralmente é nomeado como
fullchain.pemouchain.pem.-
Verifique a ordem dos certificados no arquivo: o certificado do servidor deve vir primeiro, seguido por cada certificado intermediário.
Nota: Se os certificados estiverem na ordem errada, seu servidor web pode falhar ao iniciar.
-----BEGIN CERTIFICATE----- (Your server certificate content) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (Intermediate certificate 1 content) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (Intermediate certificate 2 content, if it exists) -----END CERTIFICATE----- Atualize a configuração SSL do seu servidor web ou gateway para apontar para esse arquivo de pacote de certificados completo e reinicie o serviço.
Execute novamente o comando OpenSSL ou o teste do SSL Labs para confirmar
Verify return code: 0 (ok)e a ausência de problemas na cadeia.
Corrigir um truststore do JDK desatualizado
Caso a cadeia do servidor esteja completa, mas o cliente Java ainda apresente falha, o truststore do JDK não possui o certificado raiz necessário.
Atualizar o JDK (recomendado)
Atualize para a versão de patch LTS (Long-Term Support) mais recente da sua versão do JDK — por exemplo, a atualização mais recente para JDK 8, JDK 11 ou JDK 17. Versões de patch mais novas incluem uma biblioteca de certificados raiz atualizada que resolve problemas de substituição de raiz de CA e fornecem correções importantes de segurança.
Importar manualmente o certificado raiz (solução temporária)
Se não for possível atualizar o JDK imediatamente, importe o certificado raiz ausente para o truststore cacerts do JDK.
Baixe o arquivo do certificado raiz ausente. Consulte Baixar certificados raiz.
-
Execute o seguinte comando
keytool. Substitua os espaços reservados pelos valores reais. A senha padrão do truststore échangeit.Espaço reservado
Descrição
<give-a-unique-alias>Um nome exclusivo para esta entrada de certificado no truststore
<path-to-root-ca.crt>O caminho local para o arquivo do certificado raiz baixado
$JAVA_HOMESeu diretório de instalação do Java
# Replace <path-to-root-ca.crt> with the path to the root certificate file # Replace $JAVA_HOME with your Java installation directory keytool -import -alias <give-a-unique-alias> -keystore $JAVA_HOME/jre/lib/security/cacerts -file <path-to-root-ca.crt> -storepass changeit Reinicie a aplicação Java e verifique se ela agora consegue se conectar ao endpoint HTTPS.
Melhores práticas
Implante a cadeia completa em cada atualização de certificado. Sempre que renovar ou substituir um certificado, implante o arquivo
fullchain.pem(ou equivalente), e não apenas o certificado de nome de domínio. Um processo que funciona com o certificado antigo pode quebrar silenciosamente se um certificado intermediário for alterado.Monitore proativamente a integridade dos certificados. Configure o monitoramento de nomes de domínio públicos para receber alertas antes que problemas de certificado causem indisponibilidade.