Importing SSL Certificates

When using CyberSource Toolkit for i to connect to CyberSource via SSL, you might receive one of the following error messages depending on which version of CyberSource 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 CyberSource. Fortunately, this is easy to fix.

The necessary certificates can be downloaded as a zip file here: CyberSource SSL Certificates

Unzip the certificates and FTP the files to your IBM i.

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”. For CyberSource, the first certificate that must be installed is CS_WebService_Root.cer.

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.

Once the CS_WebService_Root.cer certificate is installed, repeat the process for the second certificate, CS_WebService_Level1.cer.

If you are using the CyberSource Toolkit for i reporting APIs, you must also install the following certificates in order:

  1. CS_Reporting_Root.cer
  2. CS_Reporting_Level1.cer
  3. CS_Reporting_Level2.cer

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