Talend Studio: How to set a truststore for an SSL/TLS connection in a Job

[TalendSolutionExpert]

Users might encounter SSL related errors when connecting Talend Studio to an HTTPS URL (such as gitlab.company.com). The error messages displayed indicate a failure during the SSL handshake process, and the Talend logs record:

!STACK 0 javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target ......... Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target at sun.security.validator.PKIXValidator.doBuild(Unknown Source) at sun.security.validator.PKIXValidator.engineValidate(Unknown Source) at sun.security.validator.Validator.validate(Unknown Source) at sun.security.ssl.X509TrustManagerImpl.validate(Unknown Source) at sun.security.ssl.X509TrustManagerImpl.checkTrusted(Unknown Source) at sun.security.ssl.X509TrustManagerImpl.checkServerTrusted(Unknown Source) ... 19 more Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target at sun.security.provider.certpath.SunCertPathBuilder.build(Unknown Source) at sun.security.provider.certpath.SunCertPathBuilder.engineBuild(Unknown Source) at java.security.cert.CertPathBuilder.build(Unknown Source)

To connect to the HTTPS URL of a non-public server, you must provide the Talend Job or Talend server with the SSL certificate file of the server you are trying to connect to.

Connecting to various public servers, such as GitHub or Microsoft, is often easy (that is, you do not have to do any special configuration) because your browser and your Job can check the validity of those servers' SSL certificates with a public certificate authority.

However, if you are trying to connect to a non-public server such as your internal Jira server; for example, jira.mycompany.com, then that server's SSL certificate is not known to the public certificate authorities. This means you will need to configure your Job or Talend server to trust this specific SSL certificate, and therefore trust the Jira server.

For more information, see the Java67 article, Difference between trustStore vs keyStore in Java SSL.

You can choose to install the certificate to your default JRE cacerts file, a collection of trusted certificate authority (CA) certificates, or install it in a separate Keystore and provide the Keystore path to Talend Studio/Job.

Resolution

To resolve the issue, perform the following steps:

1. Download the SSL certificate from the remote server.

2. Identify the location where you want to install the certificate by performing one of the following:

   1. Import the certificate to your default Truststore.

   2. Create a Keystore file, store the certificate in that Keystore file, and make your Talend Job aware of the location of that Keystore file.

The steps are documented below.

Download the SSL certificate from the remote server

Using CommandLine

If you have the OpenSSL tool, use the appropriate command for your platform:

Windows:

openssl s_client -connect {HOSTNAME}:{PORT} 2>NUL <NUL | openssl x509 -outform der > {mykey}.cer

Linux/UNIX/Mac OS/X:

openssl s_client -connect {HOSTNAME}:{PORT} 2>/dev/null </dev/null | openssl x509 -outform der > {mykey}.cer

Notes about these commands:

• Certificate files can have various formats and extensions. The DER file format is often stored with either a .der or .cer extension; use .cer here.

• NUL is the Windows equivalent of Linux/Unix/OSX /dev/null, so 2>NUL and 2>/dev/null specify to send all error output to nowhere, that is, ignore it or get rid of it.

• <NUL and </dev/null specify to send/read nothing into the command as STDIN, so the OpenSSL command is not waiting on input. You may still have to press Enter once or twice for control to return to the console.

The .der format is a binary format, so if you try to use type or cat on the .cer file, it will likely be unreadable:

> type microsoft.cer
 0üï10å≈ UUS10U0
Washington10URedmond10U
200116212402Z0üê10tion1UUS10crosUWA10URedmond10ULS CA 40
Microsoft Corporation10UMicrosoft Corporation1

This example connects to https://www.microsoft.com/ over SSL, so it uses microsoft.cer as the name of the SSL certificate.

For a readable version of the file, use the following command; this is useful for troubleshooting:

> openssl x509 -in microsoft.cer -inform der -text -noout

For more OpenSSL uses and examples, see the freeCodeCamp OpenSSL Command Cheatsheet web page.

Using your browser

If you are accessing an HTTPS service (as opposed to an FTP service, a database service through JDBC, and so on), you can use your browser to export or download the certificate. Most major browsers allow you to export an SSL certificate from a web site. Visit the web site with your browser, then export the certificate and store it on your hard drive.

This method will differ between browsers, our example uses Microsoft Edge.

1. Click the Lock in the address bar, then click Connection is secure
   
   
   
   
2. Click the Certificate icon
   
   
   
   
3. Switch to the Details tab
   
   
4. Click Export
   
   
5. Select the option .der as the format and save the certificate to disk 

Import the cert to your default Truststore

If you want to import the certificate to the standard truststore, use the following command:

keytool -import -alias microsoft -keystore "%JAVA_HOME%/jre/lib/security/cacerts" -storepass changeit -keypass changeit
  -file microsoft.der -noprompt

If you have any difficulty with %JAVA_HOME%, try using the full path directly instead of using the variable, for example:

keytool -import -alias microsoft -keystore "C:/Program Files/Java/jdk1.8.0_181/jre/lib/security/cacerts" -storepass changeit 
  -keypass changeit -file microsoft.der -noprompt

The quotation marks (") around the "-keystore <cacerts_path>" argument may be necessary because of spaces within the %JAVA_HOME% path.

Create a Keystore file, store the certificate in that Keystore file

Talend highly recommends using your own separate Keystore file, not the default Java Keystore file stored at %JAVA_HOME%\jre\lib\security\cacerts. If you use the default Java Keystore, your Job cannot run in the cloud (in a Cloud Engine), but if configured properly it can run through the cloud on a Remote Engine.

Note: This recommendation is very specific to Jobs that expect an SSL certificate, and the specifics are explained in the next section.

The discussion surrounding Keystore best practices can be nuanced and complex, but using your own Keystore is the simpler option for use with Talend. This article demonstrates both options.

The following command creates a Keystore at c:\certs\mykeystore.jks, sets its password to changeit (a common convention, but your company may use its own best practices for how to set this password), and imports the microsoft.cer SSL certificate into the new Keystore file:

keytool -import -alias microsoft -file microsoft.cer -keystore c:/certs/mykeystore.jks -storepass changeit -keypass changeit -noprompt

The -alias microsoft argument means you are giving the name microsoft to the certificate you are importing, so you can refer to this certificate with future keytool commands if necessary.

Make your Talend Job aware of the location of your Keystore

If you used the default Java Keystore location, at %JAVA_HOME%\jre\lib\security\cacerts, you should not have to do anything else to run your Talend Job or Talend server on this machine, your Job is ready to run.

However, to run your Job on any other machine, such as your remote JobServer, ESB runtimes, and Remote Engines, you have to do this same certificate-import process on each machine. This is the downside of not creating a separate Keystore file to store the private SSL certificate. Also, with this method, your Job cannot run in the cloud on a Cloud Engine, though it can run on a properly-configured Remote Engine. There are also some exceptions to using this method because certain Talend components require the use of the tSetKeystore component, for example, tKafkaConnection.

Every Talend Job, because it is a Java program, automatically looks for certificates in the default Java Keystore; that is how this mechanism works. If you chose to create a separate Keystore, then you have to explicitly tell your Talend Job where to find the Keystore containing the certificate you want it to use.

Use any one of the three methods below:

1. Use the tSetKeystore component:
   
   

   
   
   

2. Use the tPrejob and tJava components with the following code:

   System.setProperty("javax.net.ssl.trustStore", "C:/Users/username/myKeystore.keystore");
   System.setProperty("javax.net.ssl.trustStorePassword", "password");

   
   
   

3. Set up the following two JVM arguments for the Job's RUN VM:

   -Djavax.net.ssl.trustStore="C:/Users/username/myKeystore.keystore" 
   -Djavax.net.ssl.trustStorePassword=password

   

   The path to your Keystore file can be anything you like, as long as the user can read the file. Typically, your Job is executing as talenduser.