Real Vision Software, Inc. Configuring an IBM i host for SSL These steps take you through configuring an IBM i host to run Secure Sockets Layer (SSL) as a self-signed Certificate Authority (CA). The Digital Certificate Manager (DCM) and IBM HTTP Server for i allow you to manage digital certificates for your network and use SSL to enable secure communications. Note: If not already installed, install the DCM (option 34 of the base operating system). For more information on DCM setup requirements, see the Information Center for your release at http://publib.boulder.ibm.com/eserver/ibmi.html. Procedure 1. These steps take you to the Web page for DCM: a. Open a browser on your PC and point it to URL: http://[your_isystem]:2001 Note: If you do not know the value for your_isystem, use the DSPNETA command to locate your system name. Note: You may need to start the HTTP admin server if it is not already started on the host using: strtcpsvr server(*http) httpsvr(*admin) b. Provide your host Userid and password to signon the Web page. You should now be at the Welcome to the IBM Systems Director Navigator for i page. c. Click the IBM i Tasks Page link on the Welcome page. d. Click the Digital Certificate Manager link. See Figure 1. e. Enter your userid and password again. f. You should now be at a Web page for the Digital Certificate Manager. See Figure 2. Note: You can also get to the DCM Web page by clicking the IBM i Management > Internet Configurations link on the left frame and then click on the Digital Certificate Manager link in the Internet Configurations page.
Figure 1 IBM i Tasks Screen / Figure 2 DCM Screen 2. Next, we create a Certificate Store of type *SYSTEM on the host, assuming it doesn't already have one. This is a file used to store and manage the certificates created in further steps. The Certificate Store file has its own associated password for controlling access to it: a. On the left frame, click the link Create New Certificate Store. b. Check *SYSTEM. If *SYSTEM is not shown, then there may already be a certificate store. In that case, go to the step on viewing and exporting the Certificate Authority certificate for the host. See Figure 3a. c. Click Continue. d. Check No - Do not create a certificate in the certificate store. Figure 3b e. Click Continue. f. Set Certificate store password: and Confirm password:. g. Click Continue. Figure 3c h. You should get the message: The certificate store has been created.
Figure 3a Create New Certificate Store Figure 3b Create New Certificate Store
Figure 3c Create New Certificate Store Figure 4 Successfully Created Certificate Store 3. Next, we create a CA certificate for the host: a. On the left frame, click the link Create a Certificate Authority (CA). b. Set Certificate store password: and Confirm password: to what you set up in the previous section when creating the Certificate Store. c. Set Certificate Authority (CA) name: to the lowercase value of your system.domain. For example: host001.dept2.corp123.com d. Set the required fields: Organization name, State or province, Country. e. Set the Validity period of Certificate Authority. This can be set to a maximum of "7300" days. f. You can now install the certificate in your browser by clicking on the Install certificate link. You may check all the boxes on "Trust this..." and then click OK. g. Click Continue to move to the Certificate Authority (CA) Policy Data page. h. Select No on Allow creation of user certificates: i. Set Validity period of certificates that are issued by this Certificate Authority (CA) (1-2000): to a value between "1" and "2000" days. j. Click Continue. k. Select all the applications that should include this Certificate Authority (CA) in the application Certificate Authority (CA) trust list. l. You should get the message: The applications you selected will trust this Certificate Authority (CA). m. Click Continue, to finish creating the CA. n. The Web page now shows Create an Object Signing Certificate. Click Cancel since this is not needed at this time. 4. Next, we view and export the CA certificate for the host: a. Click Select a Certificate Store button on the left frame. b. Select *SYSTEM c. Click Continue. d. Enter in the password for the certificate store. e. Click Manage Certificates > View Certificate link on the left frame. f. Select Certificate Authority (CA) - View a Certificate Authority (CA) certificate. g. Click Continue. h. Verify that you see LOCAL_CERTIFICATE _AUTHORITY_... listed. You can view it to verify what you have entered. 5. Export the CA certificate to a file in the IFS:
a. Click Manage Certificates > Export certificate links on the left frame. b. Select Certificate Authority (CA) - Export a Certificate Authority (CA) certificate to another certificate store or to a file for use on another system. c. Click Continue. d. Select LOCAL_CERTIFICATE _AUTHORITY_... e. Click Export button. f. Select File - Export to a file. You can then send the file to another system and import the certificate into an existing certificate store. g. Click Continue. h. Enter an IFS file name to export the certificate to, for example: /tmp/myhostca.cer Be sure to enter an IFS directory path that exists, otherwise the export will fail. i. Click Continue. j. You should see a message that your file has been exported to the IFS location. Note: This certificate file will be required locally on the PC for registering the certificate with the Rational Developer for Power client. The file should be transferred as a text file so that it is properly converted from EBCDIC to ASCII, and not transferred as a binary file. If you want to use the Remote Systems Explorer in Rational Developer for Power Systems Software to copy the file, you need to first set the File Transfer Mode for *.cer files to Text. To do this, select Window > Preferences, then select Remote Systems > Files and click Add... to add the file transfer mode for *.cer files. 6. Create a certificate on the host for the server applications to use: a. Select Create certificate link on the left frame. b. Select Server or client certificate. c. Click Continue. d. Select Local Certificate Authority (CA). e. Click Continue. f. Set Key Size: to the encryption size that you want. g. Give the certificate a label of your choosing. h. Give the certificate a common name of your choosing. i. Set the required fields: Organization name, State or province, Country. j. Click Continue. You should get a message saying the certificate has been created. k. Select all the applications to use this certificate. l. Click Continue. Expect a confirmation message that the applications you selected will use the certificate. m. Click OK. n. You are done with the host setup, and should now be able to connect over SSL after you setup the Rational Developer for Power Systems Software client for secure connections. 7. On your IBM i you must create an HTTP Instance that will handle the SSL requests. There are two ways to do this: 1) through the IBM Systems Director Navigator for I (what you just used to create the certificate authority and certificate); or 2) the easiest way is through RVI s Create Apache Configurations utility. Make sure you have the latest version of RVAWCNF dated 03/12/2015 or later. a. From an IBM i command line, type in the following and press ENTER: GO RVUTIL. See Figure 5. b. Take the option for Create Apache Configurations. See Figure 5. c. Fill in the fields for Instance Name, Port, and Library. Figure 5. d. Enter a N for Start Server because the instance will need to be registered to use SSL before starting it. Figure 5. e. Enter a Y for Use SSL. Figure 5. f. Press Function Key F9 to create the SSL instance.
Figure 5 Create Apache Instance Figure 6 Successful Creation 8. To use the SSL instance just created, it first has to be registered to use SSL. This must be done through the IBM Systems Director Navigator for i and is a one-time setup. See Enable Apache HTTP For SSL.
Enable Apache HTTP for SSLThis document shows how to enable an Apache HTTP server to use SSL on port 8881 and non-ssl on port 80.To enable port 443 to use SSL while port 80 is non-ssl, do the following (to have a potentially associated WebSphere Application Server accept port 443 read Rochester Support Center knowledgebase document N1013078, How to Enable Websphere Application Server to Accept SSL Connections from HTTP: ). Step 1: In the HTTP Admin in the IBM Web Administration for i5/os, go to your instance. The one in the following example is called MWSSL. After connecting the browser to port 2001 and logging on, select the HTTP servers tab, and then select the Server in question in the pull-down.
Step 2: In the left pane, go to Server Properties > General Server Configuration. Step 3: In the right pane, click the Add button under Server and IP addresses and ports to listen on. Then add port 443 under port 80. Leave the FRCA column disabled because FRCA does not work with SSL. Step 4: Click Continue. Step 5: Click Apply. Step 6: The next steps will create the Virtual Host for port 443 so that port 443 will be SSL-enabled and leave port 80 as non-ssl. In the left pane, go to Server Properties > Virtual Hosts.
Step 7: Click on the IP-based tab.
Step 8: Click on the Add button in the right pane under Virtual host containers. In the drop-down box under IP address or Hostname, click All IP addresses; this creates an asterisk (*) in the left box. For the Port, type 443 for the SSL port.
Step 9: Click Continue. Step 10: Click Apply. Step 11: The next steps will enable the Virtual Host container to be SSL-enabled. In the upper right of the browser in the Server Area box, click the drop-down arrow and select Virtual Host *:443. Step 12: In the left pane, click Security; in the right pane, click the SSL with Certificate Authentication tab.
Step 13: In the right pane, select Enabled for the SSL drop-down. Step 14: Next to Server certificate application name, click the drop-down arrow and select the appropriate name. By default, it is QIBM_HTTP_SERVER_"Instance Name"; for this example, it is QIBM_HTTP_SERVER_MWSSL. Step 15: Slide down in this same screen to the HTTPS_PORT environment variable and type 443 for your SSL port. Step 16: Click Apply. Step 17: Go to Digital Certificate Manager (http://systemname:2001/qibm/icss/cert/admin/qycucm1.ndm/main0) and sign on the *SYSTEM Store. Step 18: Click Work with server applications under Fast Path on the left menu. You will see your application ID; it is the same name as your SSLAppName from the HTTP configuration. In this sample it is QIBM_HTTP_SERVER_MWSSL.
Step 19: Select the button beside your Application, and then click the Work With Application button. Step 20: Click the Update Certificate Assignment button.
Step 21: Select the certificate that you want to assign to the application. Step 22: Click the Assign New Certificate button. Step 23: Go back into IBM Web Administration for i5/os and end and restart the instance. Note: The internet Web links referred to below are not actual links; they are only examples shown in the screen above. Step 24: After the instance is active, you can access port 80 using non-ssl. In this sample, the URL is http://rchask60/. Then you can also access port 443; by default, you do not need to specify port 443 because it is the well-known port for HTTP SSL: https://rchask60/.
If you use a port other than 443 for SSL, then you must specify it in the browser. For example, if you use port 449, then specify https://rchask60:449/. Appendix A contains the resulting configuration file after all of the above setup and enabling processes have been completed.
APPENDIX A LoadModule ibm_ssl_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVSSL.SRVPGM TraceEnable Off Options -ExecCGI -FollowSymLinks -SymLinksIfOwnerMatch -Includes -IncludesNoExec -Indexes -MultiViews LogFormat "%h %T %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined LogFormat "%{Cookie}n \"%r\" %t" cookie LogFormat "%{User-agent}i" agent LogFormat "%{Referer}i -> %U" referer LogFormat "%h %l %u %t \"%r\" %>s %b" common CustomLog /logs/access_log combined LogMaint /logs/access_log 7 0 LogMaint /logs/error_log 7 0 SetEnvIf "User-Agent" "Mozilla/2" nokeepalive SetEnvIf "User-Agent" "JDK/1\.0" force-response-1.0 SetEnvIf "User-Agent" "Java/1\.0" force-response-1.0 SetEnvIf "User-Agent" "RealPlayer 4\.0" force-response-1.0 SetEnvIf "User-Agent" "MSIE 4\.0b2;" nokeepalive SetEnvIf "User-Agent" "MSIE 4\.0b2;" force-response-1.0 <VirtualHost *:8881> ServerName rviprod </VirtualHost> SSLEngine On SSLAppName QIBM_HTTP_SERVER_RVIWEBSSL SetEnv HTTPS_PORT 8881 Listen *:8881 https NameVirtualHost 10.0.0.15:8881 CGIConvMode %%MIXED/MIXED%% <Location *> <LimitExcept GET HEAD OPTIONS TRACE POST> Order deny,allow Deny from all </LimitExcept> </Location> <Directory /IMAGE> Order allow,deny Allow from all </Directory> <Directory /OPTICAL> Order allow,deny Allow from all </Directory> <Directory /QDLS/IMAGE> Order allow,deny Allow from all </Directory> <Directory /QDLS/OPTICAL> Order allow,deny Allow from all </Directory> <Directory /QSYS.LIB/RVILIB80.LIB> Order allow,deny Allow from all Options +ExecCGI </Directory>
<Directory /cgibin> Order allow,deny Allow from all </Directory> AliasMatch ^/internet/(.*) /cgibin/$1 AliasMatch ^/INTERNET/(.*) /cgibin/$1 AliasMatch ^/QSYS\.LIB/RVILIB80\.LIB/(.*) /QSYS.LIB/RVILIB80.LIB/$1 AliasMatch ^/IMAGE/(.*) /IMAGE/$1 AliasMatch ^/OPTICAL/(.*) /OPTICAL/$1 AliasMatch ^/QDLS/IMAGE/(.*) /QDLS/IMAGE/$1 AliasMatch ^/QDLS/OPTICAL/(.*) /QDLS/OPTICAL/$1 ScriptAliasMatch ^/PGMS/(.*) /QSYS.LIB/RVILIB80.LIB/$1 ScriptAliasMatch ^/pgms/(.*) /QSYS.LIB/RVILIB80.LIB/$1 ScriptAliasMatch ^/H/(.*) /QSYS.LIB/RVILIB80.LIB/RVIMAIN.PGM/$1 <Location /internet/> Require valid-user AuthType Basic AuthName RVI PasswdFile %%SYSTEM%% UserID %%CLIENT%% </Location> <Location /INTERNET/> Require valid-user AuthType Basic AuthName RVI PasswdFile %%SYSTEM%% UserID %%CLIENT%% </Location> <Location /IMAGE/> Require valid-user AuthType Basic AuthName RVI PasswdFile %%SYSTEM%% UserID %%CLIENT%% </Location> <Location /OPTICAL/> Require valid-user AuthType Basic AuthName RVI PasswdFile %%SYSTEM%% UserID %%CLIENT%% </Location> <Location /pgms/> Require valid-user AuthType Basic AuthName RVI PasswdFile %%SYSTEM%% UserID %%CLIENT%% </Location> <Location /PGMS/> Require valid-user AuthType Basic AuthName RVI PasswdFile %%SYSTEM%% UserID %%CLIENT%% </Location> <Location /h/> Require valid-user
AuthType Basic AuthName RVI PasswdFile %%SYSTEM%% UserID %%CLIENT%% </Location> <Location /H/> Require valid-user AuthType Basic AuthName RVI PasswdFile %%SYSTEM%% UserID %%CLIENT%% </Location>