How to import a public SSL certificate into a JVM

Problem

When connecting two servers via HTTPS, the public SSL certificate from each server must be added to the other server's JVM truststore.

• Refer to Connecting to SSL services

Resolution

There are 2 ways to import a public SSL certificate into a JVM:

• From the command line.
• Using Portecle.

Command Line Installation

1. Fetch the certificate, replacing google.com with the FQDN of the server your application is attempting to connect to:

   Method using openssl

   Unix:

   openssl s_client -connect google.com:443 -servername google.com < /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > public.crt

   Windows:

   openssl s_client -connect google.com:443 -servername google.com < NUL | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > public.crt

   If you are under a redirection domain page, you must specify always -servername <your_domain_name> in order to ensure we are loading the correct domain, otherwise, openssl takes the first SSL cert it receives, when it should be the second cert that belongs to your domain.

   The command above will only be executed if you have Sed for Windows as well as OpenSSL installed on your environment. If you don't have Sed or OpenSSL or you don't want to install it, use the instructions below as an alternative. Issue the following command:

   openssl s_client -connect google.com:443 -servername google.com

   Save the output to a file called public.crt. Edit the the public.crt file so it contains only what is between the BEGIN CERTIFCATE and END CERTIFICATE lines. This is how your file should look like after you edited it:

   -----BEGIN CERTIFICATE-----
   < Certificate content as fetched by the command line. 
   Don't change this content, only remove what is before 
   and after the BEGIN CERTIFICATE and END CERTIFICATE. 
   That's what your Sed command is doing for you :-) >
   -----END CERTIFICATE-----

   Method using keytool

   keytool for fetching a certificate that does not support Server Name Indication (SNI). If you need to specify a server name to get the correct certificate, please use openssl instead.

   
   

   Unix:

   $JAVA_HOME/bin/keytool -printcert -sslserver google.com:443 -rfc >> public.crt

   Windows:

   %JAVA_HOME%/bin/keytool -printcert -sslserver google.com:443 -rfc >> public.crt

2. Import the certificate:

   Java 8:

   <JAVA_HOME>/bin/keytool -importcert -alias <server_name> -keystore <JAVA_HOME>/jre/lib/security/cacerts -file public.crt

   
   Java 11:

   <JAVA_HOME>/bin/keytool -importcert -alias <server_name> -keystore <JAVA_HOME>/lib/security/cacerts -file public.crt

   Then enter the password if prompted (the default is changeit).
   
   

   ---

   Note: If the cacerts file already has a certificate for the same server name, the import may fail with the following error:

   keytool error: java.lang.Exception: Certificate not imported, alias already exist

   If this happens, you first need to remove the existing certificate from cacerts before re-trying to import the new certificate.
   To remove the existing certificate, you can use the command below:
   
   Java 8:

   <JAVA_HOME>/bin/keytool -delete -alias <server_name> -keystore <JAVA_HOME>/jre/lib/security/cacerts

   
   Java 11:

   <JAVA_HOME>/bin/keytool -delete -alias <server_name> -keystore <JAVA_HOME>/lib/security/cacerts

3. Restart your application
4. Test that you can connect to the host.

Alternative TrustStore Locations

Java will normally use a system-wide truststore:

• Java 8: $JAVA_HOME/jre/lib/security/cacerts
• Java 11: $JAVA_HOME/lib/security/cacerts

However it is possible to use a different truststore by specifying a parameter, -Djavax.net.ssl.trustStore=/path/to/truststore, where '/path/to/truststore' is the absolute file path of the alternative truststore. Information on how to configure JIRA startup variables can be found here.

However, setting this is not recommended because if Java is told to use a custom truststore (eg. containing a self-signed certificate), then Java will not have access to the root certificates of signing authorities found in $JAVA_HOME/jre/lib/security/cacerts, and accessing most CA-signed SSL sites will fail. It is better to add new certificates (eg. self-signed) to the system-wide truststore (as above).

Debugging

Problems are typically one of two forms:

• The certificate was installed into the incorrect truststore.
• The truststore does not contain the certificate of the SSL service you're connecting to.

Using Portecle

1. Download and install the Portecle app onto the server that runs your application.

   This is a third-party application and not supported by Atlassian.

2. Ensure the <JAVA_HOME> variable is pointing to the same version of Java that your application uses. See our Setting JAVA_HOME docs for further information on this.

    If running on a Linux/UNIX server, X11 will need to be forwarded when connecting to the server (so you can use the GUI), as below:

   ssh -X user@server

3. Select the Examine menu and then click Examine SSL/TLS Connection:
   
4. Enter the SSL Host and Port of the target system:
   
5. Wait for it to load, then select the public certificate and click on PEM:
   
6. Export the certificate and save it.
7. Go back to the main screen and select the Open an existing keystore from disk option, select the truststore file (for example $JAVA_HOME/lib/security/cacerts) then enter the password (the default is changeit).
8. Select the Import a trusted certificate into the loaded keystore button:
   
9. Select the certificate that was saved in step 6 and confirm that you trust it, giving it an appropriate alias (e.g.: confluence).
   1. You may hit this error: 
      
   2. If so, hit OK, and then accept the certificate as trusted.
10. Save the keystore to disk:
    
11. Restart your application.
12. Test that you can connect to the host.