Configuring HTTPS

By Rich Loeber,

If you’ve been developing applications on your IBM i that access the system through a web browser, then you’re probably already familiar with the durable and reliable Apache web server function built into the IBM i/OS. This tip will show you how to upgrade an existing HTTP server instance so that it can be used with HTTPS security. If you have any sensitive information being passed between your browser and your IBM i, implementing HTTPS security will encrypt the data and protect it from unscrupulous “sniffers” either in your network structure or over the public Internet.

This example assumes that you have a working Apache server instance named WEBSERVER. It also assumes that you will create and use a self-signed digital certificate named WEBCERT.

HTTPS Configuration Overview
—————————-

The following sequence of events must be completed to convert your working HTTP server instance from a plain HTTP server configuration to a secure HTTPS server configuration.

1. Start the *ADMIN server instance on your System i and log in.

2. Select your current HTTP server instance.

3. Enable SSL for the server instance and register the WEBSERVE application.

4. Change the server instance to use port 443.

5. Connect to the Digital Certificate Manager application on your browser.

6. Create a new digital certificate in the *SYSTEM certificate store.

7. Validate the newly created certificate.

8. Assign the new certificate to the WEBSERVE application.

9. Start the updated WEBSERVER server instance.

10. Verify that the configuration is working correctly.

————–

Step 1 – Start the *ADMIN server instance on your System i and log in.

From the command line on your system, enter the following command:

STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

This will start the web server administration tool on your system. This startup process can take a minute or two to complete. After waiting, go to your web browser and enter the following address in the address box of your browser:

http://yoursystemi.com:2001

You will be prompted for a logon process. You must sign on as a security officer with full authority to your system, such as QSECOFR. When the logon is complete, the IBM i5/OS Tasks menu should be displayed. On some releases of the IBM i/OS, you may have to select a link to the “i5/OS Tasks” page following a successful logon process.
————————————————————–

Step 2 – Select your current HTTP server instance.

From the i5/OS Tasks menu, select the “IBM Web Administration for i5/OS” link. This will start the Apache web administration tool. Select the “Manage” tab and then, when it is displayed, select the “HTTP Servers” tab. In the “Server:” selection box, locate and select the WEBSERVER server. If it is not there, then you need to configure it and test it in a non-secure environment before continuing with this procedure. When you have selected the WEBSERVER server, verify that it is showing with a status of “Stopped”. If it is showing as active, then you will need to stop it now before continuing.
————————————————————–

Step 3 – Enable SSL for the server instance and register the WEBSERVER application

Select the “Security” link from the lefthand panel. In the tab labeled “SSL with Certificate Authentication”, select the SSL box and choose the “Enabled” setting. Then, in the box immediately next to the “SSL certificate application name:”, key in the value “WEBSERVE”. We recommend that you do this in all capital letters. Press the “Apply” button to record these changes.
————————————————————–

Step 4 – Change the server instance to use port 443.

Select the “General Server Configuration” link in the lefthand panel. Under the “General Settings” tab, locate the port selection. You will need to first remove the entry for port 80 (the default for non-secure web connections) and then add an entry for port 443. When this is done, make sure you press the “Apply” button at the bottom of the page.

Next, select the “Security” link again. Scroll down until you see the entry box for “HTTPS_PORT environment variable” and enter the value 443 in this box as well. Press the “Apply” button at the bottom of the page.
————————————————————–

Step 5 – Connect to the Digital Certificate Manager application on your browser.

In your browser, re-enter the base address for the i5/OS Tasks:

http://yoursystemi.com:2001

This will bring you back to the main menu. Select the link for the “Digital Certificate Manager”.

Note: The following process will self-issue a digital certificate for use with your HTTPS server instance. When used from your browser, this will give you a warning because your server is not a registered certificate issuer, but the process will work correctly as long as you bypass the warning. On some browsers, such as Firefox, you will be allowed to accept the certificate the first time you use it and it will not be questioned again. Other browsers, like some versions of Internet Explorer, will question your use every time. Regardless, you will know where the certificate came from and you will be able to trust it by virtue of that knowledge.
————————————————————–

Step 6 – Create a new digital certificate in the *SYSTEM certificate store.

Select the button in the top left corner of your browser that reads “Select a Certificate Store”. On the next panel, select the *SYSTEM store and press the “Continue” button. (If the *SYSTEM store does not exist, you will need to first create it using the “Create New Certificate Store” link.) Your system will prompt you for the password for the *SYSTEM certificate store. If you don’t know the password, you can use the reset function to assign a new password. When you are finished, the *SYSTEM certificate store will be open and available.

Now, select the “Create Certificate” link from the left-hand panel. On the next panel, select the option for “Server or client certificate” and press the “Continue” button. Next, select the option for “Local Certificate Authority” and press “Continue” again. Now the certificate form is displayed. Fill out the required fields as follows:

Certificate label Enter the value “WEBSERVER”.

Common name Enter a unique name. I recommend that you use the system name for your system (or partition) as shown from the DSPNETA command display.

Organization name Enter the name of your company or organization.

State or province Enter the name of the state or province where you are located.

Country or region Enter an abbreviation for your country.

Select the “Continue” button at the bottom of the page and your certificate will be created.
————————————————————–

Step 7 – Validate the newly created certificate.

In the left hand panel, select the “Manage certificates” link. Next, select the “Validate certificate” link. Choose the “Server or client” option and press the “Continue” button. Select the WEBSERVER that you just created, then press the “Validate” button at the bottom of the page. If everything with the certificate is OK, a message will be displayed confirming that the certificate is valid.
————————————————————–

Step 8 – Assign the new certificate to the WEBSERVE application.

In the left hand panel, select the “Assign certificate” link. Select the WEBSERVER certificate, then press the “Assign to Applications” button. Locate the WEBSERVE application in the list displayed and place a check mark next to it. Press the “Continue” button. A message will be displayed confirming that the certificate is now assigned to the application.
————————————————————–

Step 9 – Start the updated WEBSERVER server instance.

On a terminal session command line, enter the following command:

STRTCPSVR SERVER(*HTTP) HTTPSVR(WEBSERVER)

This will start the server instance that has been converted for use with HTTPS security. If the server instance fails to start, make sure there is not another server instance active using the secure port number 443. Only one application at a time can be active using this port. If you need more than one active, you will have to change the server instance to use a different port number.
————————————————————–

Step 10 – Verify that the configuration is working correctly.

Once the server instance has been started, enter the following web address into your browser’s address box:

https://yoursystemi.com

A test page from the WEBSERVER server instance should be displayed. As stated earlier, a warning message about the certificate in use may be issued by your browser. Please note the comments associated with Step 5 above about this issue.

Comments are closed.