GR:Gravity/Client/Setup/HTTPS
There are scenarios in Gravity where the client needs to be set up for the handling of SSL/TLS (X509) certificates. The first scenario is when the server involved is a Gravity server that can only connect over HTTPS. The second scenario is when the client is used to test an LDAP or Mail server configuration over a secure connection. In any situation where server certificates are involved the idea is to set up the client so that it does not fail due to certificate checking errors. The first line of defense is always the java runtime which contains a list of CA-root certificates that are you used to verify a certificate sent from a server. If the signer of a certificate cannot be determined and applied by the java runtime then the server certificate will be rejected and the connection will fail with the exception: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed.
For all the above scenarios there are multiple ways to handle the SSL configuration so that a certificate does not get rejected, the option you choose depends on the certificate packaging and access to configuration items. If you have a singular self-signed certificate then you can use option 1 or 2 to integrate the certificate as part of the certificate checking process. If the certificate (and optional intermediate certificates) is contained in a trust store file (jks or pcks#12 format) then you need to apply options 3, 4, or 5. Note that if you choose to use options 2 or 5 then the changes made to the client regarding certificates will be lost upon client (re)installation.
1. Adding a certificate to the Remain certificates directory (using the UI). 2. Importing one or more certificates into the java runtime trust-store 3. Adding 1 or more trust stores to the Remain certificates directory. 4. Applying a trust store in the Gravity configuration with the ssl.trust.store option. 5. Applying a trust store with the -Djavax.net.ssl.trustStore option.
Although this section uses Gravity as the application that needs a certificate remedy, the described procedures can also be applied to the TD/OMS client.
The most simple way to add certificates to Gravity is by adding the certificate or trust-store file to the Remain certificates directory as described in options 1 and 3.
Note concerning the Gravity server certificate, the setting up of a certificate for the Gravity client will only be necessary if the Gravity server certificate involved has not been signed by a known Certificate Authority (CA) or is a self-signed certificate not created by the Gravity server itself (i.e. provided by the user). If the server certificate has been signed by a CA and the authority's trusted root certificate (and any intermediate certificates) are already a part of the java runtime, then it will not be necessary to manually handle the server certificate. In this situation CA certified certificates will automatically be handled by the java runtime.
1. Adding a certificate to the Remain certificates directory
Adding a certificate to the Gravity client runtime implies that the certificate will be used by Gravity to aid the java security runtime in its decision to deny or accept a received server certificate. SSL certificates that will become a part of the Gravity runtime need to have a proper identity (subject or SAN must have a domain or server name) and needs to be placed in the client's certificates directory. For the default installed Gravity client (RCP or RDi) the certificates directory can be found in the user's home directory at location '.remain\certificates'. The client loads certificates into its runtime at startup. Note that the client needs to be restarted if a certificate is added manually to the directory while the client is still running. To ease the process of adding a certificate use the Remain Certificates preference page to add, delete or view a certificate to be added or already located in the certificates directory.
Depending on if your security administrator has provided you with a single self-signed certificate file or a jks or pkcs12 trust store file (containing 1 or more (intermediate) certificates), you can copy any of these files to the Remain certificates directory located in your home directory: '?user-dir?./remain/certificates'. Upon Gravity startup any certificate with the extension der, cer or crt or any trust-store with the extension jks, p12 or pfx will be added to the TD/OMS trusted certificate manager. If the trust-store is protected by a password then the password must be made available in a file with the same name as the trust-store file name (including the extension) but with the extension .pwd, for example, plato.remain.local.jks.pwd. The clear password in the password file will be automatically encrypted and saved back to file the first time it is read.
With regards to a certificate file, Gravity can read and process a certificate in either the binary DER or ASCII PEM format.
As of version 2 of the Gravity client a self-signed Gravity server certificate will be automatically added to the client's certificates directory during discovery. When discovery is used to access a Gravity server that can only communicate over HTTPS then on first contact the user will be asked to confirm that the received server certificate is to be trusted. If the user responds with a yes then the certificate will be stored in the Gravity certificates directory (~.remain\work\certificates). Stored certificates will be used to accept a secure server connection of which the initial nature of the connection was untrusted. As of version 2 the Gravity OSGi server can be set up to automatically create a self-signed certificate to support those environments that want a secure (encrypted) connection between client and server but do not want or require a CA signed certificate. Using self-signed server certificates will most likely only occur in a private network as this construction can succumb to certain security threats if used on a public network (although there is no guarantee that such security issues will not occur on a private network). See the following article if you would like to know more about the use of self-signed SSL certificates; When are self-signed certificates acceptable.
Extracting server certificate
If you are unable to obtain a certificate for a server from you administrator then you can use a tool such as openssl to extract the certificate from a server and save it to a file. For example to extract a certificate from a Windows LDAP (Active Directory) server the following command was used:
openssl s_client -connect WIN-SERVER2008:636 -showcerts > WIN-SERVER2008.crt
The created .crt file will first have to be cleaned up to contain only the X509 certificate relevant data. This is done by removing everything before the line
-----BEGIN CERTIFICATE-----
and everything after the line
-----END CERTIFICATE-----
leave one empty line after the '-----END CERTIFICATE-----' and save the file.
The .crt file will then have to be copied to the Gravity client's '../certificates' directory. For the client, the 'certificates' directory is located in the user's home directory under .remain/gravity/work. The client has to be restarted to load the new certificate.
2. Importing a self-signed certificate into the Java trust-store
Importing a self-signed certificate into the Java trust-store
The most convenient way to import a self-signed certificate is to use the InstallCert tool. This tool will access the server providing the certificate and add the server certificate to the java runtime from which the tool is run.
Download this zip file and unpack the java classes into the jre/bin directory of the client application (TD/OMS RCP, Gravity RCP or RDi). Open a command line and switch to the application's ../jre/bin directory.
Execute the following command:
java InstallCert host:port
Then follow the instructions on the screen:
Examples:
java InstallCert exchange01:993 java InstallCert jira:443
Importing CA root certificate(s) into the Java trust-store
The import certificate solution using InstallCert will only work if the server certificate is a self-signed certificate. If not then you will have to obtain the CA root certificate (and any intermediate certificate) used to sign the server certificate and import the certificate(s) into the java trust-store using the keytool utility:
keytool -import -storepass changeit -noprompt -alias ?unique-certificate-alias-name? -keystore ?APP_JRE_HOME?/lib/security/cacerts -trustcacerts -file ?path-tot-certificate file?
for example:
keytool -import -storepass changeit -noprompt -alias ?unique-certificate-alias-name? -keystore "c:/Program Files/IBM/SDP/jdk/jre/lib/security/cacerts" -trustcacerts -file c:/temp/mycert.crt
Depending on the certificate(s) being imported the extension of the certificate file can differ (cer, crt, p7b ...).
Note that with this solution when you upgrade the client you will most likely have to repeat this procedure (it is possible though that an upgrade will also have an updated Java runtime that includes the previously missing CA root certificate).
3. Adding 1 or more trust stores to the Remain certificates directory
Adding a trust store to Gravity extends the default java trust store mechanism with user provided trust stores. For the default installed Gravity client (RCP or RDi) the trust store(s) directory is the same as the certificates directory which is the user's home directory at location '.remain\certificates'. The client loads trust stores into the java runtime at startup. Note that the client needs to be restarted if a trust store is added to the directory while the client is still running.
Gravity can read and process a trust store packaged in either the JKS or PKCS#12 format. The trust store file must have the file extension 'jks', 'p12', or 'pfx'.
If the trust-store is protected by a password then the password must be made available in a file with the same name as the trust-store file name (including the extension) but with the extension .pwd, for example plato.remain.local.jks.pwd. The clear password in the password file will be automatically encrypted and saved back to file the first time it is read.
4. Applying a trust store in the Gravity configuration with the ssl.trust.store option
A single JKS packaged trust store file can be added to java trust store mechanism by making a reference to the trust store from the Gravity configuration. To do this add the entry:
'ssl.trust.store=?fully_qualified_truststore_file_name?'
to the Gravity congfiguration file. Advantage of this option is that the trust store can be located in a location not local to Gravity, for example in a directory on a shared drive.
5. Applying a custom trust-store
The last option to manually apply a server's certificate is to use a custom trust-store. The client will be configured with a custom trust-store that overrides the default java trust-store and the trust-store set with option 4 (applying a ssl.trust.store entry in the configuration file). The trust-store contains public keys or trusted server certificates (root and intermediate). Your security administrator should be able to supply you with the required trust-store file and password. To include the trust-store as part of java's SSL security layer then the following java system properties need to be set:
'-Djavax.net.ssl.trustStore=?fully_qualified_truststore_file_name?'
These properties need to be added to the Eclipse startup ini file.
Depending on the client being used this option should be added to the TDOMS.ini, GravityAdmin.ini, GravityWorkManagement.ini or eclipse.ini (RDi) file to be found in the root of the program's installation directory. The property can be added to the bottom of the list of already configured properties, for example in the GravityAdmin.ini:
-startup plugins/org.eclipse.equinox.launcher_1.3.0.v20130327-1440.jar --launcher.library plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.200.v20140116-2212 --launcher.appendVmargs -vmargs -Dgravity.log.print.level=info -Dgravity.log4j.print.level=info -Dgravity.app=rcpadmin -Dgravity.log.file.level=info -Xms512m -Xmx1024m -Xss2m -XX:PermSize=128m -XX:MaxPermSize=384m -Xverify:none -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled -XX:+DisableExplicitGC -Djavax.net.ssl.trustStore=c:/certificates/gravity/truststore.jks
Override option to indicate that a server is to be trusted
Within Gravity, if you have setup a trust-store or certificate but your connection is still being rejected with a message like 'there is no SSL certificate that supports the hostname' or 'HTTPS hostname wrong' then you are accessing the server with the incorrect hostname. The message implies that the hostname as set in your URL does not match the hostname as set in the server's certificate. This may occur in a test environment where you need to access the server but you cannot use the certificate set hostname (for whatever reason). To overcome this situation you can create an exception for 1 or more servers. To do so add the following java system property:
-Dssl.trusted.hosts=?host1?
to the Eclipse startup ini file as described above.
or add the following property to the Gravity client or server configuration:
ssl.trusted.hosts=?host1?
If you have multiple hosts then these need to be comma separated.
Be aware that trusted servers configured in this manner will be trusted whatever the cause of a trust failure. Use this option only if you are absolutely certain the server can be trusted.
The provided host name may also contain wildcard values '*' or '?', for example 'remainsoftware.*', which will for example resolve remainsoftware.com and remainsoftware.nl.
Note that in the case of host name mismatch it would be better to update your machines 'hosts' file (on Windows this file is located in the directory c:/windows/system32/drivers/etc, on Linux this file is /etc/hosts) to include the host/domain name specified in the certificate, but if this is not possible then use the above described trusted hosts as a alternative option.