Importing SSL Certificates

When using UPS Toolkit for i to connect to UPS OnLine Tools via SSL, you might receive one of the following error messages depending on which version of UPS Toolkit for i 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 UPS. 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.

To obtain the certificate go to URL/URI https://wwwcie.ups.com/ups.app/xml/AV using your web browser. Internet Explorer is recommended and used for this example, but other browsers can be used and function similarly. On any browser after you’ve loaded the web service page, you should notice a “padlock” - either up near the URL bar, or perhaps down in one of the lower corners of the window. Wherever the padlock is located, double-click it, and you should see the following window:

Click on the “Certification Path” tab to view the different signers of this certificate. In this example, we have two signers, GTE Cyber Trust and Akamai - your results may be different. With GTE 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 name of ups_GTE.cer 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 Akamai and then the “View Certificate” button. Name this exported certificate ups_Akamai.cer

Upload the .cer files to your iSeries 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 ups_GTE.cer, and then ups_Akamai.cer. Below shows how to import the ups_GTE.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.