SSL/TLS Security

Using and Enabling 5250 & 3270 SSL/TLS

NOTE: As of StayLinked version 14, SSL connections are no longer allowed and TLS 1.0 is the default protocol. With StayLinked version 14.5, TLS 1.1 and 1.2 was fully supported.

Basic instructions for how to enable SSL/TLS in StayLinked to connect to 5250 and 3270 systems.

First, on the Telnet host Entry within StayLinked you want to set the following Emulation Properties under Telnet Host Groups:

TLS Session -> True

If you want to then use TLS 1.1 or higher, you'll need to enable JSSE and set the version you want to use.

TLS Use JSSE for TLS v1.1-v1.2 -> True
TLS Version Support -> TLS Version 1.2 (JSSE)

If you are using a SSL/TLS certificate issued by a known Certificate Authority (CA), that is all you need to do. For JSSE, the list of CAs that are supported is in in the ..\jre\lib\security\cacerts jks file for the Java Runtime you’re using.

If however, you are using a SSL/TLS certificate issued by a private CA, then you need to put the CA cert into a special jks file so StayLinked can use it. For JSSE, this is done in one of two ways:

1. We recommend placing the certificate into Java’s default custom file. This is done by taking the cacerts file mentioned above, which is in the ..\jre\lib\security folder of the JRE that StayLinked uses, and making a local copy of it with a name of jssecacerts. In our Windows install the ..\jre folder is in C:\Program Files\Stay-Linked. Once this is done, use a key management tool to insert the private CA cert into jssecacerts. The password is "changeit", which can be changed without any issues. Put this file back into the ..\jre\lib\security folder. When the StayLinked server process is started, it will automatically use jssecacerts instead of cacerts. If jssecacerts is changed, the StayLinked process must be restarted to use the updated version. Since this is a custom file, upgrades to the Java Runtime will not replace it. Keep a copy of jssecacerts in case you need to re-deploy it.
2. If you do not have access to the ../jre folder, you can create an empty jks file (typically we call it CustomizedCAs.jks with a password of hodpwd) and then putting in your private CA cert. You then get Java to use that file by adding the following parameters to the startup SH script anywhere before the -classpath argument. (Option 1 above will work fine, but Option 2 is more explicit).
   
   -Djavax.net.ssl.trustStore=CustomizedCAs.jks -Djavax.net.ssl.trustStorePassword=hodpwd
   
   The upside of this method is it works for any JRE being used. The downside is an update of StayLinked (and thus the startup script) will not include the manual script adjustment.

If you need to obtain the private CA cert file, this can be done with the IBM i Access Client Solutions Emulator by clicking on the SSL/TLS lock in the lower right corner. This will open the security information for the SSL/TLS connection. Next click "Show Issuer Certificate…" and then "Extract…". As long as the Name and Issuer of the "Issuer-Certificate" are the same, you have the root CA and are done. Save the extracted file as a .cer and "Add" it into the file being used in step 1 or 2 above with your Key Management Tool.

A CA certificate can be added to the jks file by Opening the Key Manangement Tool, clicking on "Key Database File", and selecting "Open…". When open, the CAs will be listed under "Trusted Certificates". Click "Add.." to select a CA certificate file to add. Give it a label (all lower case). There is no need to save the jks file, the tool can be closed.

If you are not using JSSE and are instead using TLS 1.0, please contact support for assistance.