Configuring HTTPS for OAT (Windows)

When HTTPS is enabled, messages from OAT clients are encrypted before they are sent to the OAT web server. Encryption prevents unauthorized users from listening over the line and stealing sensitive information. When HTTPS is enabled, OAT clients can also authenticate with the OAT host so that unauthorized users cannot deceive the OAT clients with false web servers.

When you install OAT with the IBM Informix Client Software Development Kit (Client SDK), the installation program provides the necessary software to run OAT, including pre-configured Apache, PHP, and PDO_informix. On Windows, you must replace the Apache web server that is installed with OAT with an Apache web server that is enabled for the mod_ssl module. This module is required to enable HTTPS.

Replacing the OAT Apache web server

To replace the OAT Apache web server:

1. Download the Apache HTTP Server from the Apache website: httpd.apache.org. Select the latest available Apache 2.2.x version of the Win32 Binary including OpenSSL 0.9.8t (MSI Installer).
2. Stop the OAT Apache web server. The Start menu includes an OAT menu item: IBM OpenAdmin Tool for Informix. You can stop the OAT Apache web server from there by clicking Stop Apache Service for OpenAdmin Tool. Also, make sure that the Apache Monitor is not running on your system tray.
3. Rename the OAT Apache_2.2.22 directory to Apache_2.2.22_noSSL to create a backup copy of the Apache binary files. Some configuration files from this Apache directory are used in later steps.
4. Run the Apache MSI installer. Do a typical installation and set the installation directory to /oat/installation/directory/Apache_2.2.22.
   Important: Make the directory name Apache_2.2.22 even if you are installing a newer version of Apache. The OAT installation and its services are configured to use the directory name Apache_2.2.22. They do not work if the new Apache installation has a different directory name.
5. Edit the Apache configuration file: /oat/installation/directory/Apache_2.2.22/conf/httpd.conf. Add or uncomment the following lines in this httpd.conf file:

   LoadModule php5_module
   "c:\oat\installation\dir\PHP_5.2.4\php5apache2_2.dll"
   LoadModule ssl_module modules/mod_ssl.so
   AddType application/x-httpd-php .php
   PhpIniDir 'c:\oat\installation\dir\PHP_5.2.4'

6. In the httpd.conf file, update the following line: Listen 80 (or Listen 8080). This line indicates the port number for the OAT web server. Replace 80 or 8080 with the same port number as the original OAT Apache web server that is installed with OAT.
7. In the httpd.conf file, update the following line: ServerName www.example.com:80. This line indicates the name and the port that the server uses to identify itself. Replace this line with the entire ServerName line from the original OAT Apache configuration file c:\oat\installation\dir\Apache_2.2.22_noSSL\conf\httpd.conf.
8. In the httpd.conf file, update the following line: DirectoryIndex index.html. This line sets the files that Apache serves if a directory is requested. Change this line to: DirectoryIndex index.html index.php.
9. In the original OAT Apache configuration file c:\oat\installation\dir\Apache_2.2.22_noSSL\conf\httpd.conf, locate this line: setenv INFORMIXDIR. This line sets the INFORMIXDIR variable in the Apache environment for OAT. To set the variable for the new Apache web server, copy the line to the httpd.conf file for the new Apache web server. You can put the line at the end of the file.
10. Copy the entire directory c:\oat\installation\dir\Apache_2.2.22_noSSL\htdocs\openadmin\ to c:\oat\installation\dir\Apache_2.2.22\htdocs\openadmin\. All the OAT source code is in this directory.
11. Run the following commands in a command prompt to make sure that the PHP Apache handler and the mod_ssl modules are properly loaded:

    cd c:\oat\installation\dir\Apache_2.2.22\bin\
    httpd.exe –M

    This command displays a list of Apache modules. Confirm that php5_module and ssl_module are on the list. Now your new web server should be properly setup for OAT.
12. On the Start menu, click IBM OpenAdmin Tool for Informix and then click Start Apache Service for OpenAdmin Tool. You can access OAT by using your web browser. The web server has mod_ssl enabled, but HTTPS is not switched on yet.

Creating an encryption key

Keys are used in encryption and decryption. They usually come in pairs, the public key and private key. Public keys are used to encrypt messages and private keys are used to decrypt messages. A certificate is a document that authenticates a web server. A web server with HTTPS enabled has a certificate, signed by a trusted certificate authority, to verify the web server. After a web server is enabled for HTTPS, clients choose whether to establish a normal connection or a secure connection to the web server. To establish a normal connection, the client types http://web server_url in their web browser. To establish a secure connection, the client types https://web server_url.

To generate private and public key pairs and the certificate, you use the openssl executable file in the bin directory of the new Apache web server installation.

When you run the command to generate the private key, you are prompted to enter a passphrase to protect your private key. On Windows, Apache does not support a passphrase for a private key, so you must remove the passphrase as explained in the next steps.

To create a private key:

1. To generate a private key, run the following command on the computer where the new Apache web server is installed:

   openssl genrsa -des3 -out privkey.pem 2048

2. To remove the pass phrase, run the following command:

   openssl rsa -in privkey.pem -out privkey_nopassphrase.pem

An unencrypted version of the private key is created in the privkey_nopassphrase.pem file. Store this file in a secure location because it contains your private key in an unencrypted form. When you generate the certificate, this file is used to generate the associated public key, which is included in the certificate.

Creating a certificate

After you create the private key, create a certificate to authenticate the identity of the web server. To create a certificate, you generate a certificate signing request and send the certificate signing request to a trusted certificate authority. The authority issues a certificate.

openssl req -new -key privkey_nopassphrase.pem -out cert.csr

For more information about certificate signing requests, contact your certificate authority.

Alternatively, you can create a self-signed certificate without working through a certificate authority although self-signed certificates are not recommended.

openssl req -new -x509 -key privkey_nopassphrase.pem -out cacert.pem -days 1095

OpenSSL prompts you for your information. The certificate is stored in the cacert.pem file. This file is displayed to web clients to verify your identity. It also includes the public key for web clients, so that they can encrypt communication.

For more information about encryption keys, see the OpenSSL documentation.

Configuring Apache to enable HTTPS

To enable HTTPS, update the Apache configuration file and the Apache SSL configuration file:

1. Locate the Apache configuration file. The path includes the Apache version, for example:

   /oat/installation/directory/Apache_2.2.22/conf/httpd.conf

2. In the Apache configuration file, remove the comment from this line: #Include conf/extra/httpd-ssl.conf.

   This line is commented out by default. When the comment is removed, the Apache SSL configuration file is included in the httpd.conf file.

3. Locate the Apache SSL configuration file. The path includes the Apache version, for example:

   /oat/installation/directory/Apache_2.2.22/conf/extra/httpd-ssl.conf

4. In the Apache SSL configuration file, verify that the SSL port number is set to an available port.

   HTTPS requires a separate SSL port. By default, the SSL port number is set to 443. If this port is not available, change the SSL port in the Listen directive and the Virtual Host section.

5. In the Apache SSL configuration file, verify that the SSLCertificateKeyFile directive indicates the correct location of the private key file that you created: privkey_nopassphrase.pem
6. Verify that the SSLCertificateFile directive indicates the correct location of the certificate file that you created: cacert.pem.
7. Optional: To control which ciphers the web server accepts, edit the SSLCipherSuite directive. For information about the SSLCipherSuite directive, see the Apache mod_ssl documentation.

For more information about HTTPS configurations, see the Apache website: www.apache.org.

Testing the configuration

You must restart the web server for the HTTPS changes to take effect. Restart the web server by using apachemonitor.exe or the Start menu shortcuts.

After you restart the web server, open OAT in a web browser by using this URL: https://hostname:ssl_portnumber/openadmin. You are prompted to view and accept the certificate for the OAT web server before the OAT login page is displayed.