Importing SSL Certificates

When using CyberSource Toolkit for i, you may 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. This may occur during initial setup, or when CyberSource updates certificates on their server. 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 all of the files to your IBM i. The recommended directory to upload the certificates to is:

/ktprod/cti/certs

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, 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”:

Note that each certificate is part of a chain, and that the certificates need to be imported in a specific order. For CyberSource, the first certificate that must be installed is CS_WebService_Root.cer. Enter the full IFS file path of the certificate.

You will be prompted to enter a label for the certificate. The label you choose doesn’t matter, but we recommend labeling the certificate in a manner similar to the filename of the certificate. 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 this specific certificate has already been imported into your IBM i’s *SYSTEM store. In this case, your work is done for this certificate, and you can 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, you need to 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 each of the following certificates in order:

  1. CS_Reporting_Root.cer
  2. CS_Reporting_Level1.cer
  3. CS_API_Root.cer
  4. CS_API_Level1.cer

Lastly, go back and attempt to run the program that was producing the SSL error messages, and you should no longer receive SSL error messages. However, if you are still seeing SSL errors after following the above process, please reach out to our support team at isupport@katointegrations.com.