Troubleshooting
Problem
The IBM Toolbox for Java access classes provide support for accessing an IBM i products server over Secure Sockets Layer (SSL) connections. This document provides instructions for configuring the Toolbox to properly connect over SSL/TLS.
Resolving The Problem
The IBM Toolbox for Java access classes provide support for accessing an IBM i products server over Secure Sockets Layer (SSL) connections. The preferred method of establishing an SSL connection with the Toolbox is to use the Java Secure Socket Extension (JSSE) classes. JSSE classes are built into the Java runtime on all current JVMs.
Support for JSSE connections is built into the IBM Toolbox for Java. The following instructions explain how to configure SSL connections in the IBM Toolbox for Java using JSSE.
Note your JDK may include 3rd party certificates and if you intend to use those, you do not need to import any certificates, you can jump right to step 3.
Instructions for Configuring SSL over JSSE
Step 1: Obtain a copy of the certificate for the IBM i server to be used. Do the following:
Note: The following steps are applicable when the system is using a self signed certificate. If the certificate has been purchased, or obtained from another system, then it must be exported through other methods.
| a. | Open a Web browser and connect to the HTTP administration server on the target System i server (for example: http://MyIBMiSysname:2001). |
| b. | Click on the link for the IBM i Tasks Page |
| c. | Click on the link for Digital Certificate Manager. |
| d. | Click on the link for Install Local CA Certificate on Your PC. |
| e. | In the right pane, click on the link to Copy and paste certificate. |
| f. | Highlight the entire certificate text, including the BEGIN CERTIFICATE and END CERTIFICATE lines. |
| g. | Open a text editor (such as Notepad), and paste the certificate data into the new text file. |
| h. | Save the file as MYSYS.cer (replace MYSYS with the system name, as appropriate). |
Step 2: Import the certificate file into a new keystore. Do the following:
| a. | Open a command prompt (QShell on a System i server or command prompt on Microsoft Windows). |
| b. | Change the directory to the location of the certificate file that was created in Step 1. |
| c. | Type the following command: keytool -import -alias MYSYSCERT -file MYSYS.cer -keystore truststore Press the Enter key. |
| d. | When prompted, type a password for the new keystore. |
| e. | When prompted, type yes to trust the new certificate. A new keystore file named truststore is created. |
Note: Rather than creating a new keystore, the default keystore used by the JVM can be updated to contain the new certificate. Replace the command in Step 2c with the following:
keytool -import -alias MYSYSCERT -file MYSYS.cer -keystore <path to JRE>/lib/security/cacerts
The default password when this keystore is used is changeit.
Step 3: Create and compile an IBM Toolbox for Java program that takes advantage of SSL connections. Do the following:
| a | If you are using Toolbox Access classes, replace instances of the AS400 class with SecureAS400 references. |
| b | If you are using the Toolbox JDBC driver, change the connection string to contain secure=true;. |
Note: The JDBC connection properties key ring name and key ring password are for the SSLight implementation; they are not applicable for JSSE connections.
Step 4: Run the program and specify the location of the new truststore file. Type the following command:
java -Djavax.net.ssl.trustStore=<path to trust store> ProgramName
where <path to trust store> is replaced with the complete path to the file (including the file name) that was created in Step 2. If the default keystore was updated as described in the Note for Step 2, this property does not need to be provided.
Related Information
Historical Number
444891768
Was this topic helpful?
Document Information
Modified date:
11 April 2025
UID
nas8N1014468