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.

What follows are the simplest 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

To enable 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)

The Port will also need to be changed from 23 (regular Telnet) to 992 (TLS encrypted Telnet)

The Telnet Host Entry should look like the following…

If you are using a SSL/TLS certificate issued by a known Certificate Authority (CA), that is all you need to do.

If however, you are using a SSL/TLS certificate issued by a private CA, then you need to put a file with the CA certs that StayLinked needs where StayLinked can use them. This can be done as follows and requires IBM i Access Client Solutions (ACS)

1. In ACS, have started a TLS secured session to all IBM i hosts that StayLinked will connect to (it can be more than one)
2. Open the ACS Key Management tool
3. Grab the path for the default cacerts file that ACS uses (e.g. D:\Users\greg.DNE\Documents\IBM\iAccessClient\Private\greg\). You can see the CA cert in the file under "Trusted Certificates"
4. Go get the cacerts file from that path
5. Rename the file from cacerts to jssecacerts. This is the override file for cacerts in Java's JSSE engine
6. Take this file and place it into the correct place in StayLinked's JRE. This is done by taking the jssecacerts file obtained above, and placing it into the ..\lib\security folder of the JRE that StayLinked uses.
   1. In Windows the JRE folder is in C:\Program Files\Stay-Linked\jre.
   2. On the IBM i, you can find the path in /QIBM/UserData/stay-linked/strserver.sh on the line that say "export JAVA_HOME=". The JRE default path is /QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit.
   3. This is an example of what ..\lib\security looks like in Windows

Two additional methods are as follows…

1. Get the cacerts file in the ..\jre\lib\security folder that StayLinked uses. Alter the name to jssecacerts. Use a key management tool to insert your 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. Once Java has loaded cacerts or jssecacerts, the StayLinked process must be restarted to use an updated jssecacerts file. 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 are not using JSSE and are instead need to use TLS 1.0 with a private CA, please contact support for assistance.