Installing Certificate Authorities
When using RXS to connect to a web service via SSL, you might receive one of the following error messages depending on which version of RXS you’re using:
- “Error performing SSL handshake. There is no error. RC(23) errno().”
- “SSL peer certificate or SSH remote key was not OK”
These error messages mean that you do not have the required certificate authorities installed on your IBM i to secure communication between your IBM i and the web service you’re calling. Fortunately, this is easy to fix.
This guide shows the process using the new DCM interface. For instructions using heritage DCM, click here.
Obtaining the Certificates
To resolve this issue, you first need to retrieve the certificate authorities for installation on your IBM i. These certificate authorities can generally be retrieved from a browser, or your web service provider may offer the certificates as a download from their support site.
You will need to have first set up SSL at least once on your IBM i.
We will be retrieving the certificates from the URI set in your program code, either in gInCfg.URI or TransmitDS.URI. To obtain the certificates, go to the URI/URL using your web browser. Once the web service page is loaded in your browser, follow the steps below for your browser to open the certificate information window.
Note that the instructions below were prepared using our documentation site as an example. Be sure that you are instead visiting your web service URI and retrieving those certificates.
Select your browser to continue:
Google Chrome
This example was created with Chrome version 137.
Click the icon on the left-hand side of the URL bar:
Click on “Connection is secure”:
Then click on “Certificate is valid”:
Click on the “Details” tab:
The bottom-most certificate displayed is the server-level certificate - we do not need to download and install this certificate (crossed out in blue). Instead, we are interested in all of the certificate authorities that are higher up in the chain (outlined in pink).
Click on one of the certificate authorities - in our case, R11. Click on the “Export” button at the bottom to download a .cer file for this CA:
Repeat this process for each additional certificate authority in the chain. Continue on to Installing the Certificate Authorities.
Microsoft Edge
This example was created with Edge version 137.
Click the icon on the left-hand side of the URL bar:
Click on “Connection is secure”:
Then click on the icon at the top right:
Click on the “Details” tab:
The bottom-most certificate displayed is the server-level certificate - we do not need to download and install this certificate (crossed out in blue). Instead, we are interested in all of the certificate authorities that are higher up in the chain (outlined in pink).
Click on one of the certificate authorities - in our case, R11. Click on the “Export” button at the bottom to download a .cer file for this CA:
Repeat this process for each additional certificate authority in the chain. Continue on to Installing the Certificate Authorities.
Mozilla Firefox
This example was created with Firefox version 140.
Click the icon on the left-hand side of the URL bar:
Click on “Connection is secure”:
Click on “More information”:
A new tab will appear that displays the certificate authorities in the certificate chain. The first certificate displayed is the server-level certificate - we do not need to download and install this certificate. Instead, we are interested in all of the certificate authorities that are higher up in the chain (tabs to the right on the page).
Click on the tab for the first certificate authority - in our example, this is the R11 tab. Find the “Miscellaneous” header and click on the first link next to the “Download” label to download a PEM file of the cert (the PEM(cert) link). Do not download the PEM (chain) link - this format is not accepted by DCM.
Repeat this process for each additional certificate authority in the chain (all remaining tabs). Continue on to Installing the Certificate Authorities.
Installing the Certificate Authorities
We will now take the downloaded certificates and install them in DCM. Make sure that all downloaded certificates are easily retrievable from your computer.
Accessing DCM
To begin, verify that the *ADMIN HTTP server job is running with the following command:
WRKSBSJOB SBS(QHTTPSVR)
If you don’t see *ADMIN in the list, please run the following command to start it:
STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
After you’ve ensured that the *ADMIN server is running, open a web browser, and go to http://YourIBMIPAddress:2006/dcm/ - you should see a login page as seen below:
You will want to log in to DCM using a profile with elevated permissions.
Open the *SYSTEM certificate store by first clicking on the “Open Certificate Store” link under the Actions header, then select *SYSTEM:
Enter your *SYSTEM store password when prompted and click “open”.
Uploading the Certificates
From the *SYSTEM certificate store, click “Upload Certificate” in the left-hand navigation menu:
Click the “Choose File” button to open a file browser:
Use the file browser to navigate to the location where you saved the previously downloaded certificate files. Select one of the files:
Press “Upload”. Repeat for any remaining downloaded certificates in this chain. Once you have uploaded the certificates, you should see them listed under the “Certificates” heading on this same page:
Installing the Certificates
In the left-hand navigation menu, select the *SYSTEM store to return to the main page. Click the “Import” link at the top:
Select the type “Certificate Authority” and then click “Browse Uploads”:
This will bring up a list of the certificates that were previously uploaded to the system. You should see all of the certificates that we just uploaded in the list:
Select the root (highest) certificate in the chain. In our case, we will install the ISRG Root X1 certificate first. In our example, we have labeled each certificate file with a number indicating its installation order, with 1 being the root and further intermediate certificates being numbered sequentially. This process helps avoid confusion during installation.
Click the “Select” link above (or below) the certificate list. This will return you to the previous page and populate the Path field.
Click “Continue” to install the selected certificate:
On the next page, provide DCM with a recognizable label for the certificate. In our example, we have labeled the certificate with the name of the related web service (Sixfold) as well as its issuer (ISRG) and its chain position (Root).
Click “Import”. You will either get a message that the import was successful, or a message that a certificate with the same label or public key already exists in the certificate store. The latter message is not necessarily an error - it just means that this certificate authority was already installed in your DCM and does not need to be installed again. If you get a different error message, please reach out to our team at isupport@katointegrations.com.
Repeat the import process for the remaining intermediate certificates in the chain. It is important that they are imported in order, as each subsequent certificate authority relies on the previously imported certificates for validation and verification.