PAINT installation instructions

PAINT client installation instructions

Download the application by clicking on the download link from the browser.
Copy the file into a directory and unzip using either the tar -xvf paintApp.tar for MAC or the unzip command in Windows.
Ensure Java version 11 is installed and the path variable has been set to utilize Java version 11.
Since the PAINT client exchanges information with the PAINT server via HTTPS, it is necessary for the PAINT client to ensure it can verify the validity of the information from the PAINT server via a certificate. This can be done by including the PAINT servers certificate in the list of certificates that are 'trusted' by Java. See instructions for adding certificate.
If the terminal outputs Java exception similar to the following:
Exception in thread "main" 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, the server certificate has not been installed for the Java version that is being used by the PAINT client application.

Instructions for adding the PAINT server certificate into the list of certificates that are trusted by the JAVA application

Save the certificate to your system.
1. Open the web browser to the website from which the application was downloaded, for example https://go.paint.usc.edu.
2. Depending on the browser, the steps to save the certificate on your system are different:
  1. For FireFox do as follows:
    1. Click on the lock icon on the address bar -> Connection secure-> More information-> Click on view Certificate button
    2. Under miscellaneous section in download, click 'PEM (Cert)' to download certificate.
    3. Note, location of download since it has to passed in as a parameter when adding into the truststore
    4. There are instructions on the following web site to obtain the certificate: https://www.baeldung.com/linux/ssl-certificates
  2. For Chrome do as follows:
    1. Click on the lock icon on the address bar -> Connection is secure-> Certificate is valid
    2. Click on Details tab and export button.
    3. This will bring up a save dialog. For format, select “Base64-encoded ASCII, single certificate (*.pem, *.crt)”.
    4. Note, location of download since it has to passed in as a parameter when adding into the truststore
  3. For Safari, do as follows:
    1. Click the lock in the address bar.
    2. Click show certificate.
    3. Drag the certificate icon to a Finder folder or the desktop to download it.
    4. Note, location of download since it has to passed in as a parameter when adding into the truststore
  4. For Microsoft Edge, do as follows:
    1. Click on the lock icon on the address bar -> Connection is secure-> Click on certificate icon.
    2. Click on Details tab and export button.
    3. This will bring up a save dialog. For format, select “Base64-encoded ASCII, single certificate (*.pem, *.crt)”.
    4. Note, location of download since it has to passed in as a parameter when adding into the truststore

Add the certificate to your system

The certificate has to be added to the Java Truststore using a command. First, determine where it should be stored. Depending on the system, it should be stored in a Java lib/security directory in file cacerts as given in the table below:

System	Location of Java truststore
Newer Mac OS (with JDK installed)	$(/Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home/lib/security/cacerts or /Library/Java/JavaVirtualMachines/openjdk-11.0.2.jdk/Contents/Home/lib/security/cacerts (could be jre directory) depending on version of Java 11
Mac (with JRE installed only)	$(/usr/libexec/java_home)/lib/security/cacerts
Mac (with JDK installed)	$(/usr/libexec/java_home)/jre/lib/security/cacerts (could be jdk directory)
Windows	C:\Program Files (x86)\Java\jre\lib\security\cacerts (could be jdk directory)

Use the keytool command to add the certificate downloaded from step I. to the Java keystore:
1. Determine where java is running from, by using the ‘echo $PATH ‘ (MAC) or ‘java -version’ command on Windows and ensure keyttool executable in same directory as java executable. If launch.sh/launch.bat has been modified to refer to another Java executable, use this executable path.
2. Open a terminal window or command prompt window with administrator privileges or execute the command with necessary privilege (sudo and enter password) to update the Java truststore
3. Syntax of the command is: keytool -import -alias CHOOSE-AN-ALIAS -file certificate.pem -keystore /path/to/your/truststore
4. To execute the keytool command from the Java executable directory, in MAC as root, is as follows, change directory location as necessary:
  - sudo keytool -import -alias gopaintuscedu -file ~/Downloads/go-paint-usc-edu.pem -keystore /Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home/lib/security/cacerts
  - Enter password for sudo
  - password
  - keystore
  - changeit
  - yes to add certificate
5. To execute the keytool command from the Java executable directory, in Windows, is as follows:
  - C:\Program Files\Java\jdk-11.0.10\bin>keytool -import -alias gopaintuscedu -file C:\Users\my_user_name\Downloads\go-paint-usc-edu.pem -keystore "C:\Program Files\Java\jdk-11.0.10\lib\security\cacerts"
6. Note, the name of the alias for the certificate being added is 'gopaintuscedu'
7. Enter default keystore password ‘changeit’ unless it has been saved as something else
8. The system will display the certificate details and prompt to save. Enter ‘yes’. System will indicate that the certificate has been added to the Java keystore.
Verify the certificate has been added using command keytool with the list option. For example, in Windows it is as follows:

keytool -list -keystore "C:\Program Files\Java\jdk-11.0.10\lib\security\cacerts". The trusted certificate list will have an entry for certificate with the specified alias name.

For additional details, refer to https://www.tutorialworks.com/java-trust-ssl/