Offering SSL Web services

This walkthrough details how to create a Local Certificate Authority(CA) so a self-signed certificate can be created. This is an alternative to purchasing a certificate from a respected Certificate Authority like Verisign or Thawte. The advantage to purchasing a certificate from a respected CA is that it then usually means people trying to connect to your web service will NOT need to manually install the CA because it came pre-installed on the machine from the operating system vendor (i.e. IBM, Microsoft, Sun, etc).

Start the *ADMIN Server

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:

Create SSL Application

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.

To create the SSL Application go ahead and select the “Work with server applications” link within “Fast Path”.

Select the “Add Application” button on the “Work with Server Applications” screen.

Fill out the “Add Application” form by specifying the “Application ID” field and the “Application description” field.

Select the “Create a Certificate Authority (CA)” link. Make sure you have already selected the *SYSTEM certificate store (i.e. the “Select a Certificate Store” button is used for that).

Fill out the “Create a Certificate Authority (CA)” form. Specify a secure password. Specify the CA name (I usually specify the “official” name of the company). Specify the Organization name (I usually just copy from the CA name). Specify the State and Country. Select the “Continue” button.

You will now be presented with the “Install Local CA Certificate” screen. From here you can choose to select the “Install certificate” link if you want to save this for use later on (i.e. provide it to a PC programmer connecting to your web service) or click the Continue button. Note you can get to the certificate later if necessary.

If you select the “Install certificate” link then, depending on what browser you are using (FireFox in the case of this tutorial), you will be presented with a dialog to take you through the process of downloading the certificate to your desktop. The following screen shots show how to export the CA certificate.

Modify the Policy Data values if necessary. Below is a common approach for this page as it keeps the certificates valid for the longest period of time (i.e. 2000 days).

At this point the Certificate Authority creation process is complete. You can select the “Cancel” button at this point and continue onto the next step detailed next.

The *SYSTEM Certificate Store should be selected at this point, but to ensure it is we will go ahead and select it again. Select the “Select a Certificate Store” button.

Select the *SYSTEM certificate store and select the Continue button. Do NOT select Local Certificate Authority (CA) at this point as it looks the same as another screen’s radio button that we will select in a bit.

Enter the password and select the Continue button.

In the left nav select the “Create Certificate” link.

On the “Create Certificate” page select the “Server or client certificate” radio button and click Continue.

Select the “Local Certificate Authority (CA)” radio button and select Continue.

On the “Create Certificate” page fill out all of the fields. The “Certificate label” field can be any v alue that will allow you to easily reference this later on apart from other certificates that may be created. The “Common name” value is important because you will want it to match the exact URL of the web service being offered on the AS400. If you don’t make it the same then there is the potential that not all clients will be able to connect to your web service based on warnings being issues when their program initializes the secure connection (our experience).

As noted, the bottom of the form where the “Subject Alternative Name” appears do not require entry in those fields. We do not use these fields when we create certificates.

On the “Select Applications” page you will now select the SSL application you created earlier – in this case “SSL app for XML web services”. Select the “Continue” button.

Finally, select the OK button to complete the creation of the self signed certificate and its assignment to the SSL application.

Next the SSL application needs to be associated to an Apache server instance. To accomplish this we need to go back to the iSeries Tasks page at http://YourIBMIP:2001 (replacing YourIBMIP with the address to access your IBM i), and select link “IBM Web Administration for i5/OS”.

You can either add SSL functionality to an existing Apache server instance or create a new one to facilitate the web service SSL requests. To make it more apparent what needs to be implemented for SSL capabilities we will create a very simple Apache server instance.

On the main “IBM Web Administration for i5/OS” screen select the “Setup” tab and the “Create HTTP Server” link.

Give the server a name and description.

Take the defaults on the “Server root” value and select the “Next” button.

Take the defaults on the “Document root” value and select the “Next” button.

Select an IP address and enter a value of 443 into the “Port” field. Select the “Next” button.

Take the default for the “access log” setting and select the “Next” button.

Take the default for the time to keep the log files and select the “Next” button.

Review the summary of the instance you are about to create and select the “Finish” button.

Next, make sure you are in the “Manage” tab and the “Http Servers” tab and that the correct server is selected, the click the “Edit Configuration File” link.

Enter the below text into the text area in the browser on the “Edit Configuration File” page and select the “Apply” button.


LoadModule ibm_ssl_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVSSL.SRVPGM
Listen 172.29.141.159:443
SetEnv HTTPS_PORT 443
SSLEngine On
SSLAppName SSL_APP1
DocumentRoot /www/secure1/htdocs
CGIConvMode %%EBCDIC/EBCDIC%%
ScriptAliasMatch ^/MYRXS/(.*) /qsys.lib/MYRXS.lib/$1.pgm
<Directory /qsys.lib/MYRXS.lib>
allow from all
order allow,deny
options +ExecCGI
</Directory>

Stop and start your Apache server instance with the buttons in the upper left of the page. Make sure the HTTP instance is fully stopped before starting it by using the blue refresh button (note, it shouldn’t have already been started unless you started it).

Open up another browser tab and enter this address: https://YourIBMIP/myrxs/rxs1 where YOURIBMIP is the IP of your IBM i. Note that by default, the browser will go to port 443 when we specify https.

Because the Apache instance we created isn’t a “trusted” Certificate Authority it will inform you that the connection is not currently secured. Because your certificate is self-signed, your web browser doesn’t know to trust it by default. Go ahead and accept the certificate. The method of accepting the certificate is different based on the browser. Below you can see how it is done in FireFox:

You should now be able to view the web service programs without an error message.