====== SSL Certificate for Java Keystore =====

===== Context =====

When loading web resources via a secured https connection, the website's Security Certificate must be available (known and trusted) to Java Runtime Engine used by Orbit. \\
Oracle includes certificates from widely recognized Certificate Authorities with a significant customer base and global reach. \\
Orbit embeds the most recent JRE available at the release of a new version. 

More information about Security Certificates and Java Keystore :
  * https://www.oracle.com/technetwork/java/javase/javasecarootcertsprogram-1876540.html
  * https://en.wikipedia.org/wiki/Keystore
  * https://en.wikipedia.org/wiki/Certificate_authority


===== Connectivity Issues =====

=== Mixed Content ===

Occurs when loading an insecure connection in a secured session. 

=== Invalid or Self-Signed certificates ===

Occurs when the Website/Webservice certificate is not known by Java. Thus the expected secured connection cannot be guaranteed, a SSL handshake error will prevent successful connection. 

When a proxy/firewall offloads secured communication to repacakage network traffic with its own SSL certificate, ensure the proxy uses a valid, officially authorized certificate. Self-signed certificates are, for well know reasons, not trusted and need to be added explicitly to the Java Keystore to enable connectivity. 

===== Orbit Logfile Error =====

Following exception is printed in the [[227:technology:platforms:logfiles|Orbit logfile]] if a certificate is missing : 
  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

===== Add Certificate to Java Keystore =====

Steps to add a certificate to the Java Keystore used by Orbit. 

=== Download certificate from website ===

Browse to the secured website and download the certificate file via the browser's certificates manager.
  * File format : ''DER Encoded Binairy X.509 (CER)''

=== Add certificate to Orbit's Java Keystore ===

From command line. \\

Go to Orbit's Jre bin directory. \\
On Windows 
  * Client/Server \\ ''<Orbit Installation Directory>/client/program/jre64/bin/'' \\ ''<Orbit Installation Directory>/server/program/jre64/bin/''
  * Standalone \\ ''<Orbit Installation Directory>/program/jre/bin/''   

Execute following command : \\ <code>
keytool -import -alias <Alias> -keystore ..\lib\security\cacerts -file <File Directory>\<Filename>.cer
</code>
  * Alias : free of choice
  * Password : default, ''changeit'', requested after prompt.

After confirmation and entering the password the message ''Certificate was added to keystore'' should be printed.