IBM i Access for Web r7.2 5250 SSL Enablement

Resolving The Problem

To use the IBM i Access for Web 5250 display interface to connect to the Secure Telnet Server on port 992, IBM i Access for Web product 5770XH2 must be installed at r7.2 and have Service Pack PTF SI54619 or later applied.

This document assumes that the IBM i OS Systems to which a connection will be established are already configured for Secure Telnet. If not, reference the IBM i OS Software Technote "Configuring the SSL Telnet and Host Servers for Server Authentication for the First Time" which can be linked to here:

http://www-01.ibm.com/support/docview.wss?uid=nas8N1010449

To allow communication with the Secure Telnet Server, IBM i Access for Web must be able to determine trust of the Certificate Authority (CA) that issued the Server Certificate assigned to the Secure Telnet Server. To accomplish this, place a Java KeyStore (JKS) file containing the trusted CA certificates in a product configuration directory. The JKS file must be named 'cacerts' (with no file extension) and have a password of 'xw1certs'.

IBM i Access for Web will first took for 'cacerts' in the deployment specific configuration directory.

The deployment specific configuration directory for an IBM i OS Integrated Application Server instance will be the following:

/QIBM/UserData/Access/Web2/intappsvr/<instance_name>/config/

The <instance_name> for the IBM provided special case deployments are:

*ADMIN = Admin

*MOBILE = __MOBILE__

The deployment specific configuration directory for an IBM Websphere Appplication Server instance will be the following:

/QIBM/UserData/Access/Web2/<WAS_server_type>/<library_name>/<profile_name>/<application_server_name>/config/

If that is not found, IBM i Access for Web will look in the global configuration directory:

/QIBM/UserData/Access/Web2/config/

For many customers it will be preferable to just leverage this global configuration directory and have all deployments of IBM i Access for Web share the same Java KeyStore file.

To create the JKS 'cacerts' file use the other IBM i Access family products, IBM i Access Client Solutions or IBM i Access for Windows, and the Key Management tools shipped with them. First use whichever product you choose and establish a Secure Telnet connection to the IBM i OS Systems or Partitions to which IBM i Access for Web Secure Telnet connections will be established. Then, once the Certification Authority trust has been confirmed in that product's key database file, we can use its Key Management tool to open that default key database file, and save it as a Java KeyStore (JKS) file called 'cacerts'. IBM i Access for Web also requires that the file have a password of 'xw1certs'.

Expand for instructions, with screen shots, on how to do this with IBM i Access Client Solutions.

1) Open the Key Management tool by selecting the IBM i Access Client Solutions Main User Interface menu option of Tools -> Key Management

2) This will open the current IBM i Access Client Solutions trusted Java KeyStore in a Key Management utility. From that Key Management utility select the menu option of Key Database File -> Save As

3) Choose an easily found location like the Desktop for Save in and specify a File name of 'cacerts' and press the Save button

4) The Key Management Utility will now be managing the newly created Java KeyStore called 'cacerts'. To change the password to the required value from the Key Management menu of Key Database File -> Change password...

4) Specify a password of 'xw1certs' and press OK

5) You can now close the Key Management utility. The 'cacerts' file on your desktop can now be copied into the IBM i Access for Web configuration directory discussed above and the Certificate Authority trust from this Java KeyStore will be used by Access for Web when connecting to a Secure Telnet Server.

Expand for instructions, with screen shots, on how to do this with IBM i Access for Windows.

1) Open the IBM Key Management utility from the IBM i Access for Windows Program group

2) In IBM Key Management select the menu option of Key Database File -> Open

3) Ensure that you are opening the cwbssldf.kdb file of type CMS and press OK. This should be the default

4) Provide the Password of 'ca400' and press OK

5) Now we need to save this Key Database file as a Java KeyStore (JKS) file named 'cacerts'. In IBM Key Management select the menu option
Key Database File -> Save As

6) In the New panel change the Key database type to JKS, change the File Name to 'cacerts' and Browse or specify an easily found location like the Desktop and press OK

7) There will be a Password Prompt to specify a new password. Enter a password of 'xw1certs' in both fields and press OK

8) You can now close the IBM Key Management utility. The 'cacerts' file on your desktop can now be copied into the IBM i Access for Web configuration directory discussed above and the Certificate Authority trust from this Java KeyStore will be used by Access for Web when connecting to a Secure Telnet Server.

Finally, the Access for Web 5250 interface needs to specify a connection to the Secure Telnet server. From the Start Session, or Configure new session, panels specify a Port of 992 in the System area as shown.

Note: The IBM i Access for Web product is deployed to a Web Application Server environment like IBM Websphere Application Server or the IBM i Integrated Web Appplication Server. If IBM i Access for Web does not find a 'cacerts' Java KeyStore (JKS) file in the product configuration directories, it will look to the Web Application Server's default trust store, so the Certificate Authorities to be trusted can be added there via the support provided by that application server.