6
SSL Support in Oracle9iAS Discoverer

This chapter explains how to configure Discoverer Plus and Discoverer Viewer to work with the Secure Sockets Layer (SSL) protocol.

The topics include:

• Getting more information

• SSL and Discoverer

• What is SSL and why should I use it?

• How does SSL work?

• About Public Key Encryption Technology

• SSL authentication and certificates

• What steps do I need to follow?

• Configuring Discoverer Plus to use SSL

• Configuring Discoverer Viewer using HTTPS

6.1 Getting more information

This chapter contains edited extracts from the Visibroker SSL Pack 3.3 Programmer's Guide.

For more information about Visibroker's SSL features, refer to the Borland Inprise Corporation Internet site at:

http://www.borland.com/techpubs/books/addons/vbssl/vbssl33/
index.html

6.2 SSL and Discoverer

Discoverer Plus and Discoverer Viewer can be configured to use the SSL protocol:

• In Discoverer Viewer, SSL support is provided using the SSL capabilities of the Oracle HTTP Server powered by Apache.

• In Discoverer Plus, SSL support is provided using the SSL capabilities of the HTTP Server and Visibroker Gatekeeper. With Discoverer Plus, you can encrypt the data between the client and Visibroker Gatekeeper when the client is outside the Server's firewall.

6.3 What is SSL and why should I use it?

The SSL (Secure Sockets Layer) protocol is an industry standard protocol to establish secure connections between clients and servers. The SSL protocol enables sensitive data to be transmitted over an insecure network, such as the Internet, by providing the following security features:

• Authentication: A client can determine a server's identity and be certain that the server is not an impostor. Optionally, a server can also authenticate the identity of its client applications.

• Privacy: Data passed between the client and server is encrypted so that if a third party intercepts their messages, the third party will not be able to unscramble the data.

• Integrity: The recipient of encrypted data will know if a third party has corrupted or modified that data.

When SSL is enabled, a closed padlock ( ) or other equivalent symbol (browser dependent) appears in the browser's status bar, and the web page's URL starts with "https://" instead of "http://".

6.4 How does SSL work?

SSL provides a secure communications channel between two parties by providing several security services at the transport layer level using a combination of public key and symmetric key technology. Usually these parties are a web browser and a web (HTTP) server. However, since SSL operates at the transport layer, it is application independent. Protocols such as Telnet, FTP (File Transfer Protocol) and HTTP (HyperText Transfer Protocol) can therefore be layered on top of it.

6.5 About Public Key Encryption Technology

Public key encryption uses two different keys to encrypt and decrypt messages, a public key and a (secret) private key. The two keys are used such that a message encrypted with a private key can only be decrypted with the corresponding public key, and a message encrypted with a public key can only be decrypted with the corresponding private key.

6.6 SSL authentication and certificates

Before establishing a secure connection, the server (and optionally the client) is authenticated. This is to make sure that one is communicating with the correct server. Authentication is done through digital certificates, or public-key certificates. Certificates used in SSL are defined by an ITU (International Telecommunications Union) standard called X.509, (see figure below).

To prove that the server is the legitimate owner of the certificate, SSL requires that certificates are digitally signed by a trusted Certificate Authority (CA), for example VeriSign, Inc. You can think of a certificate as a passport and the Certificate Authority as a government passport office. You trust that the government passport office has verified the identity of the passport holder before issuing a passport to him or her.

Figure 6-1 Certificates being verfied by the Certificate Authority

6.7 What steps do I need to follow?

6.7.1 To configure SSL with Discoverer Plus

1. Follow the steps in Section 6.8, "Configuring Discoverer Plus to use SSL".

2. Make sure that you have the jar file x509cert.jar installed on your client machines. Follow the steps in Section 6.8.6, "Installing the x509cert.jar file".

3. Make sure that you have the required DLL files, see Section 6.8.7, "Installing the required Dynamic Link Library files (DLLs)".

4. Enable SSL in your Discoverer start pages by following the steps in Section 6.8.8, "Enabling SSL in Discoverer Plus start pages".

6.7.2 To configure SSL with Discoverer Viewer

1. Follow the steps in Section 6.9, "Configuring Discoverer Viewer using HTTPS".

2. Enable SSL in your Discoverer pages using the HTTPS protocol, see Section 6.9.5, "Enabling SSL in Discoverer Viewer".

   Note: Discoverer Viewer uses HTTP and HTTPS protocols that are firewall compliant and do not require Visibroker Gatekeeper.

6.8 Configuring Discoverer Plus to use SSL

6.8.1 How does Discoverer Plus support SSL?

To provide support for SSL, Discoverer Plus uses Visibroker Gatekeeper (for more information about Visibroker Gatekeeper, refer to Section 7.5.1, "What is Visibroker Gatekeeper?").

Discoverer Plus supports the SSL mode of communication only for clients that are outside the server's firewall and therefore connect to Discoverer Server components through Visibroker Gatekeeper. Clients in the intranet (i.e. inside the Server's firewall) do not use SSL when communicating with the Discoverer Server components.

You have to configure Visibroker Gatekeeper to use SSL with Discoverer Plus.

6.8.2 How do I configure Visibroker Gatekeeper to use SSL?

To configure Visibroker Gatekeeper to use SSL, follow these steps:

1. Install Visibroker Gatekeeper on either your HTTP server machine or a different machine, depending on your firewall configuration, (see Section 6.8.3, "Installing Visibroker Gatekeeper to work with SSL").

2. Obtain SSL certificates from a Certificate Authority (see Section 6.8.4, "Getting SSL certificates").

   If you have already obtained certificates for your enterprise or organization, these can be reused with Visibroker Gatekeeper.

3. When you have obtained SSL certificates from the Certificate Authority, install these certificates on Visibroker Gatekeeper (see Section 6.8.5, "Installing SSL certificates").

NOTE: If you have SSL certificates installed on your Gatekeeper, you cannot use the URL parameter ORBalwaysTunnel=yes, (see also "How to use a specific connection method").

6.8.3 Installing Visibroker Gatekeeper to work with SSL

SSL support in Discoverer works through single and multiple firewalls.

• When using single firewalls, you can run Visibroker Gatekeeper on any port. If you run Visibroker Gatekeeper on port 443 (the standard SSL port) you do not have to open your firewall (known as `drilling a hole' in a firewall) for SSL communication. If you run Visibroker Gatekeeper on port other than 443, you must open your firewall on this port for SSL communication

• When using multiple firewalls, you should run Visibroker Gatekeeper on port 443.

NOTE: If you by running Visibroker Gatekeeper on port 443, (by convention, the standard SSL port), SSL proxies must only allow communication to port 443 also.

To enable SSL in Discoverer, you must configure Visibroker Gatekeeper to use SSL. When configuring Visibroker Gatekeeper, you have two options:

1. If your HTTP server is not using port 443 for SSL communication, you can install and run Visibroker Gatekeeper on the HTTP server machine. Then, configure the Visibroker Gatekeeper Exterior Port to 443.

   See Section 7.10.2, "Running Visibroker Gatekeeper on the HTTP Server" and Section 7.10.5, "Changing the default Visibroker Gatekeeper port".

2. If your HTTP server is using port 443 for SSL communication, you must install Visibroker Gatekeeper on a different machine. Then, configure the Visibroker Gatekeeper Exterior Port to 443.

   See Section 7.10.3, "Running Visibroker Gatekeeper on a different Server" and Section 7.10.5, "Changing the default Visibroker Gatekeeper port".

6.8.4 Getting SSL certificates

NOTE: You can omit this step if you already have SSL certificates for your enterprise.

Discoverer Plus provides the vbcertrq tool to automate the certificate request process. After specifying the required information, the vbcertrq tool generates three files:

• a certificate request file

• a file containing the values for the certificate request

• a file containing the private key.

After you have generated the files, you should submit the certificate request to a Certificate Authority (CA). The procedure for submitting your certificate request to a CA is determined by the certificate authority you are using. If you are using a CA that is internal to your organization, contact your system administrator for instructions. If you are using a commercial CA, contact them for instructions on submitting your certificate request.

To run the vbcertrq tool:

1. Type vbcertrq at an MS-DOS command line prompt or double-click the vbcertrq tool icon in Windows Explorer.

   The Certificate Request Tool dialog appears.

Figure 6-2 Certificate Request Tool dialog

2. Specify the certificate information (see Section 6.8.4.1, "Specifying the certificate information").

3. Specify the password (see Section 6.8.4.2, "Specifying private key passwords").

4. Specify the key size (see Section 6.8.4.4, "Specifying key size").

5. Specify the output file name (see Section 6.8.4.3, "Specifying output file name").

6. Click the Generate Certificate Request button to create the certificate request file, certificate request values file, and the private key file, (see also Getting SSL certificates).

6.8.4.1 Specifying the certificate information

The certificate information is used to create your unique name. Required information is shown in red in the vbcertrq tool dialog. Specify the following information:

• Common-Name (Required): Either the name of an individual or a hostname, depending on whether the certificate is intended for a person or a server. When using certificates with the Gatekeeper, this value is typically the hostname of the machine on which the Gatekeeper runs.

• Organization (Required): The organization or company to which the certificate recipient belongs.

• Country (Required): The name of the country in which the certificate recipient resides.

• Email (Optional): The email address of the certificate recipient or the person to contact for more information about this user.

• Phone (Optional): The user's telephone number.

• Organization Unit (Optional): The user's department name.

• Locality/City (Optional): The city in which the user resides.

• State/Province (Optional): The state in which the user resides. Enter the full name of the state or province. Do not use abbreviations. For example, enter `California', not `CA'.

6.8.4.2 Specifying private key passwords

You are required to specify a password that will be used to encrypt your private key. You will need to supply this password before you use your private key. The password prevents unauthorized use of your private key.

Your password is case-sensitive and can contain any character you can type on a keyboard. The password can be from six to 99 characters long. As with all passwords, avoid choosing common words that are susceptible to dictionary-style attacks. Passwords that contain numbers, blanks, and other characters are more secure than common words or phrases.

To specify the private key password, fill in the following fields:

• Type Password: A password to encrypt the private key. It can be any mix of alphanumeric characters.

• Confirm Password: Retype the password to confirm it.

6.8.4.3 Specifying output file name

The names of the three files generated by the vbcertrq tool are based on what you specify in the Output File Name field. For example, if you specify mycertreq in the file, the following files are created:

• mycertreq contains the certificate request

• mycertreq########, where ######## is a unique sequence of numbers, contains the values of the fields in the certificate request

• mycertreqKEY contains the private key in password encrypted PKCS #8 format

6.8.4.4 Specifying key size

You can specify the number of bits your key will contain in the Key Size field. The greater the number of bits in your private key, the greater the security of your encrypted data. You can specify any size between 360 and 2048 bits.

NOTE: United States federal export regulations limit keys that are used in exported software to 512 bits.

6.8.4.5 Using an S/MIME certificate chain

Certificate authorities are able to provide your certificate chain in a number of formats. Visibroker Gatekeeper expects the commonly used format of separate X.509 certificates. If you have a certificate chain in an S/MIME (PKCS #7) format, you must separate the certificates before they can be used with Visibroker Gatekeeper.

To separate S/MIME certificates:

1. Navigate to the <ORACLE_806_HOME>\vbroker\ssleay directory and type the following at the command prompt to break the certificate chain file into its certificates

   > ssleay pkcs7 -print_certs -inform DER -in cert-chain-file -out cert-file
   

The output file contains a list of one or more certificates and your private key. Each certificate is delimited with the following statements:

-----BEGIN CERTIFICATE-----

-----END CERTIFICATE-----

If there is more than one certificate, the first one is yours and each subsequent certificate represents a certificate authority up to a root (such as Thawte).

6.8.5 Installing SSL certificates

When you have all the necessary certificates, you need to install the certificates (starting with your certificate to the root certificate authority) on Visibroker Gatekeeper.

1. Run gkconfig.exe from <ORACLE_HOME>\vbroker\bin.

2. Choose File | Open and open the file <iSUITES_HOME>\apache\apache\htdocs\Discwb4\applet\gatekeeper.properties.

3. Click on the SSL tab to display the SSL configuration details, (see Figure 6-3 below).

Figure 6-3 Gatekeeper Configuration Manager SSL tab

4. Check the Enable SSL on Exterior check box.

   The SSL Certificate, SSL Private Key, and SSL Key Password properties become active, and SSL active indicators (also known as "mufflers") on the Visibroker Gatekeeper configuration model show where SSL is enabled, (see Figure 6-4 below).

Figure 6-4 Gatekeeper Configuration Manager with `SSL enabled in Exterior'

Key to Figure 6-4.

a - SSL active indicators on the exterior connection indicating where SSL is enabled.

b - Note also that the Exterior Port (configured on the Exterior tab in the Gatekeeper Configuration Manager) has been set to 443, which is the standard SSL port.

5. Click Add.

   An Open dialog box appears.

6. Navigate to the file containing an SSL certificate.

7. Select the SSL certificate file, and then click Open.

   The full path name of the file appears in the SSL Certificate box.

8. Repeat Steps 5 to 7, as necessary, to build a certificate chain.

   You can specify one or more certificate files. There is one certificate per file. However, you can specify a list of certificate files. The list acts as a chain of certificates. You must start the chain with Visibroker Gatekeeper's certificate followed by the issuer's certificate and continue, if there are more, up to the root.

9. Click the Browse button beside the SSL Private Key field to specify an SSL private key (required for Visibroker Gatekeeper's SSL adapters to operate successfully).

   An Open dialog box appears.

10. In the Gatekeeper Configuration Manager SSL tab, click Browse.

    An Open dialog box appears.

11. Navigate to the file containing the SSL private key.

12. Select the file and click Open.

    The full path name for the file appears in the SSL Private Key box, setting the private key for the exterior SSL adapters.

13. In the SSL Key Password box, type in the SSL key password.

    If your SSL private key is encrypted, enter a password for the private key for the exterior and interior SSL adapters. If you used the vbcertreq tool to generate a certificate request, you specified this password there.

    An asterisk appears for each character of the password you enter. The password itself does not appear in the SSL Key Password box.

    Note: SSL key passwords are stored in plain text in the file gatekeeper.properties. Therefore, this file should only be accessible to authorized users.

14. Choose File | Save.

15. Choose File | Exit.

6.8.6 Installing the x509cert.jar file

To use SSL, Discoverer client machines must have the jar file x509cert.jar installed.

To install x509cert.jar on Windows NT clients, follow these steps:

1. Copy the x509cert.jar file from the <iSUITES_HOME>\apache\apache\htdocs\discwb4\util directory on the HTTP server machine to the \Program Files\Oracle\JInitiator 1.1.7.30\lib directory on the client machines.

   Note that you can download the above file from http://server.com/discwb4/util/x509cert.jar.

To install x509cert.jar on UNIX clients, follow these steps:

1. Copy the x509cert.jar file from the <iSUITES_HOME>\apache\apache\htdocs\discwb4\util directory on the HTTP server machine to the <Java-Plugin>/lib/ directory on the client machines (where <Java-Plugin> is the directory in which the Sun Java plugin is installed).

Note that you can download the above file from http://server.com/discwb4/util/x509cert.jar.

6.8.7 Installing the required Dynamic Link Library files (DLLs)

To use an SSL enabled ORB on Windows NT clients, client machines must have the DLL files vbj30ssl.dll and/or vbrnissl.dll installed. To install the DLL files, follow these steps:

1. Copy one or both of the following files from the specified directory on the HTTP server machine to the \winnt directory on the client machines:
   • <iSUITES_HOME>\apache\apache\htdocs\discwb4\util\vbj30ssl.dll - for JInitiator users.

   • <iSUITES_HOME>\apache\apache\htdocs\discwb4\util\vbrnissl.dll - for Internet Explorer users.

To use an SSL enabled ORB on UNIX clients, client machines must have the file libvbj30ssl.so. To install this file, follow these steps:

1. Copy the libvbj30ssl.so file from the <iSUITES_HOME>/Apache/Apache/htdocs/discwb4/util directory on the HTTP server machine to the <Java-Plugin>/lib/ directory on the client machines (where <Java-Plugin> is the directory in which the Sun Java plugin is installed).

Note that you can download the above files from http://server.com/discwb4/util/vbj30ssl.dll and http://server.com/discwb4/util/vbrnissl.dll respectively.

6.8.8 Enabling SSL in Discoverer Plus start pages

To enable SSL in a Discoverer start page, add the following URL parameter to the URL for the start page:

ORBenableSSL=yes

For example:

http://server.com/discwb4/html/english/welcome.htm?ORBenableSSL=yes

NOTE: If you have multiple URL parameters in the same URL, separate the URL parameters with the ampersand character `&'.

For example:

http://server.com/discwb4/html/english/welcome.htm?ORBenableSSL=yes&ORBalway
sProxy=yes

NOTE: You cannot use the URL parameters ORBenableSSL and ORBalwaysTunnel at the same time.

6.8.9 Using SSL inside firewalls

By default, SSL support works only for clients outside your firewall. You can enable SSL inside firewalls by setting these URL parameters as follows:

• ORBalwaysProxy=yes - connect using IIOP Proxying (see also "How to use a specific connection method").

• ORBenableSSL=yes - enable SSL when requesting the URL.

NOTE: When using SSL inside firewalls, there is no restriction on the SSL port.

6.9 Configuring Discoverer Viewer using HTTPS

To make sure that your Discoverer Viewer documents are secure, and to get your browser to acknowledge a "secure" page, follow these steps:

• Install SSL certificates on your HTTP Server and enable SSL for Discoverer Viewer Servlets. For more information, refer to the Oracle9i Application Server Installation Guide.

• Edit the following files to set up HTTPS:
  • the httpd.conf file (see "Editing the httpd.conf file to set up HTTPS")

  • the disco4iviewer.properties file (see "Editing the disco4iviewer.properties file to set up HTTPS" )

  • the disco4iv.xml file (see "Editing the disco4iv.xml file to set up HTTPS")

  • the viewer_config.xml file (see "Editing the viewer_config.xml file to set up HTTPS")

6.9.1 Editing the httpd.conf file to set up HTTPS

Make changes to the httpd.conf file as follows:

1. Open the httpd.conf file for editing.

   The httpd.conf file is located in <iSUITES_HOME>\apache\apache\conf.

2. Add the following line in the Aliases section of the file to specify the location of the disco4iv directory (if the line does not exist already):

   Alias /disco4ivfiles/ "<iSUITES_HOME>\apache\apache\htdocs\disco4iv/"
   
   

   where:

   • disco4ivfiles is any name you choose

   • <iSUITES_HOME> is the location in which Oracle9i Application Server components are installed

For example:

(httpd.conf)

# Aliases: Add here as many aliases as you need (with no limit). The format is 
# Alias fakename realname
#
# Note that if you include a trailing / on fakename then the server will
# require it to be present in the URL.  So "/icons" isn't aliased in this
# example, only "/icons/"..
#
Alias /icons/ "D:\apache\icons/" 

Alias /disco4ivfiles/ "D:\iAS_Home\apache\apache\htdocs\disco4iv/"

6.9.2 Editing the disco4iviewer.properties file to set up HTTPS

Make changes to the disco4iviewer.properties file as follows:

1. Open the disco4iviewer.properties file for editing.

   The disco4iviewer.properties file is located in <iSUITES_HOME>\apache\jserv\servlets.

2. Change the path to the disco4iv.xml file from the HTTP protocol to the FILE protocol.

   For example:

   (disco4iviewer.properties - Before change)

servlet.Viewer.initArgs=config=http://mywebserver.company.com/disco4iv/html/disco4iv.xml

servlet.viewer.initArgs=config=http://mywebserver.company.com/disco4iv/html/disco4iv.xml

(disco4iviewer.properties - After change)

servlet.Viewer.initArgs=config=file:///D:\iAS_Home\apache\apache\htdocs\disco4iv\html\disco4iv.xml

servlet.viewer.initArgs=config=file:///D:\iAS_Home\apache\apache\htdocs\disco4iv\html\disco4iv.xml

6.9.3 Editing the disco4iv.xml file to set up HTTPS

Make changes to the disco4iv.xml file as follows:

1. Open the disco4iv.xml file for editing.

   The disco4iv.xml file is located in <iSUITES_HOME>\apache\apache\htdocs\disco4iv\html.

2. Change the xsl_path argument to include the FILE protocol and the full path to the disco4iv.xsl file.

   NOTE: When determining the xsl_path argument, the FILE protocol not the HTTPS protocol is used (see example below).

   For example:

   (disco4iv.xml - Before change)

<argument name="xsl_path" type="href">disco4iv.xsl</argument>

(disco4iv.xml - After change)

<argument name="xsl_path" type="href">file:///D:\iAS_Home\apache\apache\htdocs\disco4iv\html\disco4iv.xsl
</argument>

6.9.4 Editing the viewer_config.xml file to set up HTTPS

Make changes to the viewer_config.xml file as follows:

1. Open the viewer_config.xml file for editing.

   The viewer_config.xml file is located in <iSUITES_HOME>\apache\apache\htdocs\disco4iv\html.

2. Change the value of the base_dir attribute of the configuration element to the full secure path to the disco4iv.xsl file.

   For example:

   (viewer_config.xml - Before change)

<configuration application="discoverer_viewer"
base_dir="." image_dir="images">

(viewer_config.xml - After change)

<configuration application="discoverer_viewer"
base_dir="https://mywebserver.company.com/disco4ivfiles/html/"
image_dir="images">

6.9.5 Enabling SSL in Discoverer Viewer

To enable SSL in Discoverer Viewer URLs, prefix URLs with https, rather than http.

For example:

https://company.com/Discoverer4i/Viewer/<Viewer parameters>