Using SSL with the Robot Browser Interface

 

Use these instructions to configure the Robot Browser Interface portal server to send and receive information using Secure Sockets Layer (SSL). SSL technology encrypts (encodes) the communication between web browsers and the portal server. This encryption provides security against unwanted access to usernames, passwords, or other sensitive information. If you plan to provide access to the portal server via the Internet, we recommend using SSL to communicate with the portal server.

Before You Begin

Before you start the process to configure SSL, make sure that the portal server is not running.

Configuring SSL

1. Go to the directory where the portal server is installed.

2. Locate the directory where Java 5 or 6 is installed on your server (see the table below). Then, locate the executable file called keytool in the specified subdirectory.

   Environment	Location
   IBM i	V7R1: /QIBM/ProdData/OS400/Java400/ext V7R2: /QIBM/ProdData/OS400/Java400/ext
   Windows	\Program Files\Help Systems\Common Java\jvm\bin
   UNIX	Talk to your UNIX administrator. Or, view the startPortal.sh file to determine the location for JAVA_HOME.

3. Enter the full keytool command for your environment (see the table below).

   Environment	Location
   IBM i	You must first go into QSHELL (enter QSH on an IBM i command line). Then, change the the directory to where the keytool file is located for your OS. For example, for V7R1 or V7R2, you would use this command to change the directory: cd '/QIBM/prodData/OS400/Java400/ext' Finally, use the following command to generate the keys file: keytool –genkey –alias tomcat –keyalg RSA –keystore keys
   Windows	\Program Files\Help Systems\Common Java\jvm\bin\keytool -genkey -alias tomcat -keyalg RSA -keystore keys
   UNIX	/JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore keys Where: JAVA_HOME is the directory where Java 5 or 6 is installed.

4. When prompted for a password, enter a password and remember it.

   Note: If you’ve entered the keytool command incorrectly, you won’t receive the prompt to create a keystore password; you’ll receive an informational page instead. If that happens, try retyping the command, or from the root directory (/) enter the following command:

   keytool –genkey –alias tomcat –keyalg RSA –keystore keys

5. After you enter and confirm your keystore password, enter your company’s information and location at the various prompts (for a sample, see the table below). When you are finished, a file called keys should exist in the current directory. Make a note of the path to that file.

   Prompt	Response
   Enter keystore password:	MyPass
   What is your first and last name?	[Unknown]: First Name Last Name
   What is the name of your organizational unit?	[Unknown]: Information Technology
   What is the name of your organization?	[Unknown]: ACME Company
   What is the name of your City or Locality?	[Unknown]: Anytown
   What is the name of your State or Province?	[Unknown]: MN
   What is the two-letter country code for this unit?	[Unknown]: US
   Is CN=First Name Last Name, OU=Information Technology, O=ACME Company, L=Anytown, ST=MN, C=US correct?	[no]: yes
   Enter key password for	[Return if the same as the keystore password]: Press Return

6. Open the file server.xml so you can edit it. This file’s location depends on the directory where the portal server is installed (see the table below).

   Environment	Location
   IBM i	/helpsystems/portal/conf/server.xml
   Windows	\Program Files\Robot Browser Interface\conf\server.xml
   UNIX	/opt/helpsystems/conf/server.xml*

   * On UNIX systems, this is the usual location for the file. If the server.xml file is not located here and you cannot locate it, contact your UNIX administrator.

7. In the Connector block of the server.xml file, remove the beginning and ending comment tags () from the Connector port 8443 entry. Following is an example of what it should look like before and after you make this change:

   Before:
     

   After:
     
        maxThreads="150" scheme="https" secure="true"
        clientAuth="false" sslProtocol="TLS" />

8. In the Connector block you were working with in the previous step, add the path to the keys file that you created in step 5 and the keystore password you created in step 4. Following is an example of what it should look like:

     
         maxThreads="150" scheme="https" secure="true"
         clientAuth="false" sslProtocol="TLS"
         keystoreFile=”/QIBM/ProdData/OS400/Java400/ext/keys" keystorePass="MyPass" />

9. Save your changes and exit the server.xml file.

10. Start the portal server and try connecting to the portal using the following URL:

    https://someserver:8443

    Where someserver is the name or IP address of your portal server.

    Note: The URL must start with https, not http.

11. When you connect to the portal server for the first time, your web browser should display a site certificate dialog (see the examples). Click Yes or OK to display the Portal Login page.

    Note: Some versions of Netscape may ask a second question. Click Yes or OK.

    Example Certificate Dialog for Internet Explorer 6.0:

    [[

Disabling the Non-Secured Port

After you have SSL setup and working, you can disable the non-secured port, if you choose to.

1. Open the file server.xml so you can edit it. This file’s location depends on the directory where the portal server is installed (see the table below).

   Environment	Location
   IBM i	/helpsystems/portal/conf/server.xml
   Windows	\Program Files\Robot Browser Interface\conf\server.xml
   UNIX	/opt/helpsystems/conf/server.xml*

   * On UNIX systems, this is the usual location for the file. If the server.xml file is not located here and you cannot locate it, contact your UNIX administrator.

2. In the Connector of the server.xml file, add beginning and ending comment tags () around the block of code to disable the non-secured port 8008. Following is an example of what it should look like before and after you make this change:

   Before:
     
       maxThreads="150" connectionTimeout="20000"
       redirectPort="8443" />

   After:
     

Troubleshooting Tips

If you’re using your IBM Power Systems (System i, iSeries, AS/400) running IBM i (OS/400, i5/OS) for your web server, and receive the message “Page cannot be displayed error” after setting up SSL, try the following:

1. Ensure your web server is active by running the PORTSTCFG command from the command line. If not running, start the server by running the PORSTARTUP command on your IBM i. If it is running, go to the step 2.

2. Go to the non-secured URL (http://server_address:8008). If this does not display the signon screen, contact Technical Support.

   If it does display the signon screen, that means that the RBI setup is OK and there may be a problem with your Internet options.

SSL uses the TLS protocol when the web server is the IBM i. This needs to be activated in the Internet options of the web browser that is being used to access Robot Browser Interface. Where this setting is located will depend on what you are using for your Internet browser. Many times the error page that the browser software displays will list some things to look at to ensure the Internet options are correct. Follow the instructions to see if you can find where you define to use TLS.

If you are using Internet Explorer:

1. Open Internet Explorer.

2. Click Tools, and select Internet Options.

3. Click the Advanced tab and scroll down to the Security section.

4. Scroll down and ensure that the “Use TLS 1.0” box is checked. If not, check it and click Apply. Then, click OK.

5. Close and reopen Internet Explorer.

6. Type your portal information in the address bar and press Enter. Example (https://192.000.0.000:8443)

7. You may get a window stating you need to accept this certificate. Respond to this dialog and the Robot Browser Interface signon page displays.

Note: When defining SSL on a Windows machine, this didn't seem to be a problem. The Windows and UNIX environments use SSL differently.