My extension is getting a “PKIX path building failed” error. Why?

[Abhishek.Saxena]

Why am I getting a “PKIX path building failed” error when my extension tries to connect to an application server?

Sometimes a “PKIX path building failed” error is reported in Machine Agent logs for extensions that are trying to connect to an HTTPS endpoint.

Contents

• What does the PKIX error mean?
• How do I resolve a PKIX error?
• How do I manually import the certificates?
• If I continue to see PKIX errors, how else can I troubleshoot?
• Additional resources

What does the PKIX error mean?

PKIX stands for Public Key Infrastructure X509.

Whenever Java attempts to connect to another application over SSL, the connection will only succeed if it can trust the application. If the extension is not able to establish trust with the configured server then it returns the “PKIX path building failed” error.

How do I resolve a PKIX error?

The most convenient resolution for this error is to configure SSL parameters in the config.yml file of the extension.

You can add a “connection” property in the config file with relevant SSL parameters as mentioned below:

 

Make sure that you have correct certificates in truststore and keystore before configuring the path.

How do I manually import the certificates?

Following are the steps to be followed on how to manually import the certificates which are required for SSL configuration in the extension

1. Download the full certification path:
   

   echo | openssl s_client -showcerts -connect <host>:<port> 2>&1 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cert.pem

2. Import the CA hierarchy in the truststore
   

   keytool -import -alias <Alias_for_your_certificate> -file “<Path_to_certificate_in_quotes>” -keystore cacerts.jks -storepass <truststore_password>

   
   You can configure the “connection” property in the config file only for extensions which are HTTP based extensions. More details on HTTP client and “connection” properties can be found in the Advanced Troubleshooting Document for HTTP Client.
   

JMX-based extension import options

For JMX based extensions (for which mbeans configuration is required), you can either:

• Follow extension-specific SSL configurations if any SSL guidelines are provided in the documentation, or 
• Pass SSL parameters to the Machine Agent startup command, as below:
  

  java -Djavax.net.ssl.trustStore=/path/to/truststore/cacert.jks -Djavax.net.ssl.trustStorePassword=changeit -jar machineagent.jar

Note that two flags are available in JMX: 

• Securing server communication to use SSL: This is the default SSL configuration (com.sun.management.jmxremote.ssl) that must be set to true. Setting this configuration to true secures the communications via SSL by using a server certificate.
  
  
• JMX RMI registry SSL secured: Starting with JDK 6, an additional parameter (com.sun.management.jmxremote.registry.ssl) was added to force the creation of an SSL-secured Remote Method Invocation (RMI) registry.

The extension does not support SSL encryption of the RMI Registry, it does support SSL encryption of the JMX connections themselves.

If I continue to see PKIX errors, how else can I troubleshoot?

The error might continue to come up if incorrect certificates are imported and configured, or if correct SSL parameters are not supplied in the extension.

Please reach out to your application team for the correct certificates, and configure them in the extension. 

Also, verify whether all the relevant SSL parameters are correctly configured in the extension or provided as Java arguments.

Additional resources

• Why am I getting PKIX 'path building failed' errors in the Agent log file?
• JMX-based extension connectivity: How do I troubleshoot issues?