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.

Obtaining the Certificates

To fix this problem you need to obtain the CA for installing on your iSeries via the Digital Certificate Manager (i.e. *ADMIN instance). You will need to have already set up SSL at least once on your IBM i.

You will be retrieving the certificates from the URI set in your program code, either in gInCfg.URI or TransmitDS.URI.

To obtain the certificate go to the URL/URI using your web browser. These examples were created using Internet Explorer 11 and Chrome version 60. Once the web service page is loaded in your browser, follow these steps to open the certificate information window.

Internet Explorer

Click the padlock at the right-hand side of the URL bar, then click on “View certificates”:

Chrome

From the Menu, go to “More Tools” > “Developer Tools”:

In the developer tools frame, to go the “Security” tab:

Then, click on “View certificate”:

Downloading the Certificates

From the Certificate Information window:

Click on the “Certification Path” tab to view the different signers of this certificate. In this case we have two signers, DST Root CA X3 and Let’s Encrypt Authority X3. With DST highlighted, select the “View Certificate” button.

You should now be presented with a new Certificate window, and upon clicking the “Details” tab should see a window like the below image. Select the “Copy to File” button which will start you into a wizard process:

Select the “Next” button.

Leave “DER encoded binary X.509 (.CER)” selected, and select the “Next” button.

You will be prompted to save the file. Browse to your Desktop and save it with a recognizable name as shown in the following screen shot:

Now repeat this process by closing all dialogs and returning to the original browser window. This time after double clicking on the padlock, select Let’s Encrypt and then the “View Certificate” button. Save this certificate to the desktop as well.

Upload the .cer files to your IBM i via FTP (or other means) and place them in /home (or other folder of choice, just remember where you put it).

Applying the Certificates

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 (Internet Explorer is recommended), and go to http://[YourIBMIPAddress]:2001 - you should see a login page as seen below:

Enter your IBM i username and password, and click “Log in”. You should see a page split into two sections - a menu on the left, and a larger content area on the right that looks like the below image:

Click the “IBM i Tasks Page” link.

Now, click the “Digital Certificate Manager” link. You may be prompted to log in again - if you are, enter your IBM i username and password. It is recommended to log into the Digital Certificate Manager on a profile with elevated authority.

After you are logged in, click on the “Select a Certificate Store” button in the far left of the page. Then, select the *SYSTEM store and press the “Continue” button. If you do not see *SYSTEM, you will need to go set up SSL on your IBM i.

It will then prompt you for your *SYSTEM store password. Enter your password and select the “Continue” button. Note: If you do not remember the password, you can simply select “Reset Password” - you will be allowed to reset the password without knowing the previous password.

Next, select “Manage Certificates” on the left:

Click “Import Certificate”

Select “Certificate Authority”, and then click “Continue”:

Enter the IFS file path of the certificate you are importing. It is very typical that there will be multiple levels of SSL certificates arranged in a “chain”. If this is the case, you need to import the highest level first. In this case we need to import DST_cert.cer, and then LetsEncrypt_cert.cer. Below shows how to import the DST_cert.cer certificate.

You will be prompted to enter a label for the certificate. The label you choose doesn’t matter, but it’s recommended to choose a label that describes the certificate you’re uploading. Then, click “Continue”.

At this point, you will likely receive one of two messages. The first possible message looks like the below image. This indicates that someone has already imported this certificate into your IBM i’s *SYSTEM store. In this case, your work is done for this certificate - move onto the next one.

Otherwise, you should receive a message indicating that the certificate has been successfully imported.

Now, repeat the process for each certificate you uploaded to your IBM i.

Lastly, go back and attempt to run the program that was producing the error messages, and they should stop appearing.