Offering SSL Web Services

This walkthrough will help guide you through the process of offering SSL web services using a certificate from either a trusted Certificate Authority or a self-signed certificate generated from your local Certificate Authority.

The advantage to using a certificate from a trusted CA is that it then usually means people trying to connect to your web service will have the CA pre-installed on the machine from the operating system vendor (i.e. IBM, Microsoft, etc). If you opt to use a self-signed certificate, people consuming your web service will have to manually accept and install the CA.

This guide shows the process using the new DCM interface. For instructions using heritage DCM, click here.

Accessing DCM

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:2006/dcm/ - you should see a login page as seen below:

You will want to log in to DCM using a profile with elevated permissions.

Unlike with other processes, we are not necessarily going to immediately open the *SYSTEM store. If you are creating a Local CA, you need to do this from the main DCM page, before accessing a certificate store.

Acquiring the Server Certificate

Trusted Certificate Authority

If you are using a certificate from a Trusted Certificate Authority like Verisign or Let’s Encrypt, follow the guides linked below:

• Creating a Certificate Signing Request - a Certificate Signing Request (CSR) is required by Trusted Certificate Authorities to issue server certificates
• Installing Certificate Authorities - since you will already have your generated certificate from the Certificate Authority, you can skip the retrieval steps and begin with accessing DCM and uploading your certificate. When it comes time to specify the certificate type, ensure that you select Server or Client instead of Certificate Authority as demonstrated in this guide

Local Certificate Authority

In order to generate a certificate yourself, you will first need to configure the Local CA for your system in DCM.

Creating the Local CA

If you are currently in your *SYSTEM certificate store, exit the certificate store and return to the DCM home page by clicking the “Close” link in the top right.

From the main DCM page, click “Create Certificate Store” under the Actions header:

Select “Local CA” as your certificate store type:

Set a password and click “Create”:

Once you’re loaded into the Local CA, click “Create” under the “Certificate Authority (CA)” heading:

Populate the required fields for your environment and click “Create”:

You should now see the created Certificate Authority listed on the main page:

Creating the Server Certificate

Open the *SYSTEM certificate store by first clicking on the “Open Certificate Store” link under the Actions header, then select *SYSTEM:

Enter your *SYSTEM store password when prompted and click “open”.

Once you’ve accessed the *SYSTEM store main page, click “Create” under the “Certificates” heading:

Choose “Local CA” for the Certificate Authority:

Fill in the form that appears - the domain for the server (including subdomain) must be specified as the “Common Name”, along with any other required fields or optional fields as needed.

Click “Create” at the bottom and you should see the newly generated certificate on your main *SYSTEM store page:

Creating the Application Definition

From the main *SYSTEM store, click the “Manage Application Definitions” link at the top:

You’ll be brought to a list of Application Definitions. Click “Create” at the top:

Select “Server” as the application type:

Provide an application ID, and then click the Specify button for the Description, and provide a description of the Application Definition. For the application ID, it must consist only of uppercase letters, numbers, or underscores, and must begin with an uppercase letter. Additionally, you should not begin the application ID with QIBM - this is intended only for IBM provided Application Definitions. The description can be anything you like, and does not have any character requirements other than that it cannot be empty. However, it is important to note that you will not be able to modify the description once the Application Definition has been created.

You can ignore the other application options on this page unless you know you need them. Then, at the bottom of the page, click the Create link. If the link is still gray, this typically means you did not provide both an ID and a Description for this application.

After clicking Create, the page should refresh to a list of Applications Definitions found in DCM, and a green popup should appear in the top right corner of your browser window. In the application list, click the View link for your newly created Application Definition:

Click the Assign Certificates link under the View Application Definition heading:

If you have one or more certificates that can be assigned to this Application Definition, they will appear in a list with checkboxes next to them. Typically you should only have a single certificate assigned to an Application Definition, but this is not always the case. Select whichever certificate(s) you wish to assign, and then click one of the Assign links that appear above and below the list.

After clicking an Assign link, the page will return to the Application Definition page, and you should see the certificate(s) you selected show up in the Assigned Certificates list:

Configuring the Apache Server

Your Application Definition will need to be associated with an Apache server instance. This can either be an existing server instance, or you can create a new HTTP server instance using the CRTRXSSVR command.

We will make use of the RXS command HTTP to work with our Apache server instance and modify the configuration file (/www/[servername]/conf/httpd.conf). This file can also be modified through RDi, or through the IBM Web Admin panel.

Note: In these instructions, we reference the RPG API Express install library of RXS, and our HTTP server created with CRTRXSSVR is also named RXS. These values should be substituted as needed to match your system setup.

1. Open the httpd.conf configuration file for editing with the HTTP command:

   HTTP [servername] *CONF

   

2. Add the following lines to your httpd.conf file:

    LoadModule ibm_ssl_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVSSL.SRVPGM
    Listen *:443
    SetEnv HTTPS_PORT 443
    SSLEngine On
    SSLAppName [your Application Definition in DCM]
   

   If your server was created with CRTRXSSVR, some of these lines may already be present. Do not duplicate these lines.

3. If you already have the ScriptAliasMatch line present, but it looks like this (with either RXS or MYRXS):

   ScriptAliasMatch ^/RXS/(.*) /qsys.lib/RXS.lib/$1.pgm

   We’d recommend replacing it with the version in the code above, which has the same functionality but with a more modern syntax:

   ScriptAliasMatch ^/(([^/.]+/)*[^/.]+)$ /qsys.lib/RXS.lib/$1.pgm

   substituting MYRXS.lib for RXS.lib if your previous statement referenced MYRXS.lib.

4. Stop the Apache server using the HTTP command:

   HTTP [servername] *END

5. Start the Apache server:

   HTTP [servername] *START

6. You should now be able to access your web services using SSL. To confirm, try loading this RXS example program in your browser:

   https://[YourIBMIP]/MYRXS/RXS1

   We are not specifying a port because, by default, the browser will go to port 443 when we specify https.

   Because we are using a self-signed certificate, and not one from a trusted Certificate Authority, you may need to click through a security warning dialog to allow the page to load.

   If your application and server are configured correctly, you should see a page similar to the one below: