Enabling SSL

Before you can configure SSL, you need to make sure that the Cryptographic Service Provider product is installed. This is a no-charge IBM product.

Next, you must start the *ADMIN server using the command:

STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

The *ADMIN server provides a number of browser-based HTTP configuration tools served from port 2001. To access these tools, go to IBM Navigator for i:

http://IBMiServer:2001/

Find Digital Certificate Manager (DCM), which is found under the Internet Configurations option in the IBM i Management section.

Open

The above display may look like this.

You will now enter the DCM

Open

The above display may look like this.

You will have to decide on one of a few options:

• Buy a certificate from a vendor like VeriSign or Thawte – this is appropriate for public Internet applications.

• Create your own certificate – this may be appropriate if your users are predominantly internal. By default, browsers will not recognize you as a trusted certificate authority. You have several options for addressing this:

  • Instruct users to ignore the browser’s warning message

  • Install a local certificate authority (CA) certificate on the end-user’s PC

Ordering a certificate from a trusted vendor like VeriSign, Thawte, or Let's Encrypt

The first step is to create a Certificate Signing Request (CSR). The certificate vendor will need this in order to create your certificate.

• Once inside DCM, click Select Certificate Store. You are looking for the *SYSTEM certificate store.

  • If it is not available, click Create New Certificate Store and create the *SYSTEM store. You’ll be prompted to create password for it.

  • If the *SYSTEM store already exists, select it, and enter the password. There is a password reset option, if you do not know/remember the password.

• Click Create certificate.

• Select Server or Client Certificate.

• Select “VeriSign or other Internet Certificate Authority”

• This will bring up the CSR form. The important fields are:

  • Key size: use the size recommended by the certificate vendor.

  • Common Name: Here, you must give the exact host/domain name that users will type into browser address bar to access the site. The browser will give an error/warning message if the host/domain name used to access the site does not match exactly to the certificate Common Name. For example: www.mydomain.com

• After completing the CSR form, the CSR text will display on screen. Copy and paste the text to a text file on your PC. It’s important to do this before leaving the page, as there is no way to view the CSR text again. When ordering your certificate, the vendor will ask for the CSR – this is typically copied/pasted into a web form, or uploaded as a text file.

When you receive the certificate, create or place a certificate text file on the IBM i IFS in some temporary location.

Then select Manage Certificates, Import Certificate. Select Server or Client Certificate and specify the IFS file name for Import File. You will then have to choose the vendor/certificate issuer.

If the vendor/certificate issuer does not exist, then the certificate will fail to import. You can import a CA certificate of the issuer using a similar process–upload the CA certificate to the IFS, choose Import Certificate, choose Certificate Authority. After adding the CA certificate, repeat the step to import the certificate from an IFS file.

Wild-Card Certificates

If your organization already has a wild-card certificate from a certificate authority you will still need to create a CSR from IBM's Digital Certificate Manager; otherwise, the certificate will fail to import. Your vendor should provide a way to request a duplicate certificate, and the CSR is used there.

Creating your own certificates through your own CA

(not recommended for public Internet Access)

Once inside DCM, click Select Certificate Store. You are looking for the *SYSTEM certificate store. If it is not available proceed to Create a CA (Certificate Authority).

• Choose password (it is very important to remember this, as there may not be an easy way to reset this)

• Enter CA information – this should be readable information; it will display if the certificate is viewed by the user

• The create CA process will proceed to create a *SYSTEM certificate store if it does not exist

• Then, a Web Server Certificate will be created

• When creating the Web Server Certificate, the most important piece of information is the COMMON Name. This is the exact IP address or host name of the server for which SSL is being configured.

• The process will then proceed to choosing an application. You should stop here, since the application has not been created yet.

Installing a local CA certificate on the end-user PC:

This applies only if using a certificate issued from a local CA.

Click Install Local CA Certificate on Your PC. Select Copy and Paste CA Certificate.

Then, paste the data into a text file with a .cer extension.

Send this file to your users. Each user must open the file, install the certificate, and choose the appropriate store

Creating an Application

Regardless of what type of certificate you are using, you’ll need to create an ‘Application’ in the DCM. The application is simply an identifier that a certificate is associated with. The HTTP server will reference the application id, which in turn references the certificate.

To create an application, select Manage Applications, then Add Application, then select Server Application.

• Enter Application Id – this piece is referred to in your httpd.conf configuration file

• Enter Application Description

• Leave all other fields as their default values

Next, you must assign the certificate to the application. Select Manage Certificates, and then Assign Certificates. Select the certificate your created and click Assign to Applications.

Configuring the HTTP Server

Finally, you must uncomment the following lines from your httpd.conf file located in /www/profoundui/conf/ and enter your application id on the SSLAppName line:

You will most likely want to Change the port to 443 as well. This is the standard port used for SSL. You can do so on the Listen directive in http.conf.

If you wish to keep your existing non-SSL port working as it was before, but add SSL support on a second port, you can do so with a VirtualHost directive.  For example, to keep 8080 as non-SSL, but add port 8081 as SSL within the same HTTP server instance, you could do the following:

You may wish to keep the old port open but automatically redirect users to the SSL port. Users may have the old port bookmarked in their browsers. You can automatically redirect using a rule like the following:

This rule causes all requests from the non-SSL port, 8080, to be sent to the SSL port, 8081.

As with any change to httpd.conf, you will need to restart the PROFOUNDUI web server.

If you are allowing access to the IBM i from external locations, then you may also wish to disable certain components of Profound UI so that they aren't available in your SSL instance (e.g. Visual Designer).  More information on that can be found under Allowing External Access

Firewall

If you've added a new port to the IBM i, then your organization's firewall may not yet be configured to allow the new port's traffic to your IBM i. Work with your organization's network administrator to open the new port.

Preserving Rules During Upgrade of Profound UI

When upgrading an instance of Profound UI you are given an option to write the httpd.conf file, the IBM HTTP Server configuration. Choose no to preserve the SSL configuration.

When asked for the port number, you can leave the port to the non-SSL port even if you have two ports listening.

SSL with IBM i 7.4

Due to a bug in IBM i 7.4, customers may receive an Internal Server Error message when using SSL with Profound UI. 

To fix this error, please install PTF SI70862 (provided by IBM). You can find more information about this PTF here. 

Granting user permission to run SSL Applications

If you receive an error using SSL similar to:
”(GSKit) Access to the key database is not allowed” This is because the end-user does not have the authority to the files in the IFS that is needed by the Global Secure Toolkit (GSKit) in the operating system. This is the component in the Operating System that is used for SSL/TLS.

To solve this problem, grant authority as follows…
In the example, a group named PROFOUND is being given access to the files.
(Change PROFOUND to the proper group or user ID as needed)