5
Configuring Form Services

5.1 Introduction

This chapter describes the steps you need to follow to configure your environment for Form Services. After installation is complete, you can use the information in this chapter to change your initial configuration or make modifications as your needs change.

This chapter contains the following sections:

• Configuring Your Web Server

• Customizing Environment Variables

• Customizing Configuration Files

• Reading the Servlet Error Log

• Setting Up the HTTPS Connection Mode

5.2 Configuring Your Web Server

Oracle9i Application Server installs and configures the Oracle HTTP Server as your Web server. No additional configuration is necessary.

The following paths are created

These virtual directories are specified in the 6iserver.conf file located in the <ORACLE_HOME>/6iserver directory.

5.3 Customizing Environment Variables

This section describes how to customize environment variables in Form Services.

On UNIX, you can set these environment variables in the forms60_server shell script, which is found in the <ORACLE_HOME>/6iserver directory. This way, all the environment variables needed for Form Services are automatically set up when you launch Form Services Listener using the following command line:

forms60_server start.

After you run the forms60_server startup script, ORACLE_HOME changes from its original setting to <ORACLE_HOME>/6iserver for use with Form Services.

On NT, you set environment variables in the registry under HKEY_LOCAL_MACHINE\software\oracle in the <ORACLE_HOME> corresponding to Forms 6i, as described in Section A.2, "Windows 95 and Windows NT Registry".

The environment variables for Form Services are as follows:

For example, you can define your environment variables as the following:

FORMS60_PATH=/<ORACLE_HOME>/6iserver/forms60
FORMS60_OUTPUT=/<ORACLE_HOME>/6iserver/tools/web60/temp
FORMS60_MAPPING=/dev60temp
FORMS60_MESSAGE_ENCRYPTION=TRUE
FORMS60_WALLET=/<ORACLE_HOME>/6iserver/forms60/wallet
FORMS60_HTTPS_NEGOTIATE_DOWN=FALSE

The virtual directory set by the FORMS60_MAPPING environment variable must correspond to the physical directory set by the FORMS60_OUTPUT environment variable.Note::

You will need administrator privileges to make these changes, and will need to restart the server for many of these configuration changes to take effect.

5.4 Description of Form Services Startup Parameters

The following parameters are used during Form Services startup:

• Port Parameter

• Mode Parameter

• Pool Parameter

• Log Parameter

On UNIX, you can modify these parameters by editing the forms60_server shell script found in the <ORACLE_HOME>/6iserver directory and modifying the following command:

f60ctl start

For example:

f60ctl start port=9001 mode=socket pool=5 log=/tmp/app.log

On NT, you can modify these parameters by specifying them on the command line. For example:

ifsrv60 start port=9001 mode=socket pool=5 log=c:\tmp\app.log

On NT, if Form Services are started as a service, modify parameters by adding them to the Start-up Parameters field of the Service Start-up property.

5.4.1 Port Parameter

Determines the port on which the server process is started. If you do not specify a port number when you start the Form Services process, the process starts on port 9001 by default. The port number on which you start the server process must match the serverPort number you specify in an application's HTML file, configuration parameters, or URL.

5.4.2 Mode Parameter

Determines whether the Form Services will run in socket mode (which uses a direct socket connection), HTTP mode (which can traverse firewalls), or HTTPS mode (which can traverse firewalls, and additionally uses SSL, secure sockets layer, for server authentication and message encryption). The default mode is socket. See Section 3.2, "Sockets, HTTP, or HTTPS" for a detailed description of each mode.

5.4.3 Pool Parameter

Determines the number of spare active connections that will be available for subsequent users. For example, if "pool" is set to 5, there will be 5 active spare connections.

5.4.4 Log Parameter

Generates a server log file when provided a path name and log file name, for example, log=/PathName/LogFileName.

5.5 Customizing Configuration Files

During the installation, the following configuration files were installed onto your system:

• FormsServlet.initArgs

• formsweb.cfg

• base.htm, basejini.htm, and baseie.htm

When a user first starts a Web-enabled application (by clicking a link to the application's URL), the base HTML file is read by Forms Servlet or CGI. Any variables (%variablename%) in the base HTML file are replaced with the appropriate parameter values specified in the formsweb.cfg file, and from query parameters in the URL request (if any).

For servlet implementations, the baseHTML, baseHTMLJInitiator, and baseHTMLIE tags are replaced with the values specified in the FormsServlet.initArgs file.

You can modify the configuration files as your needs change.

5.5.1 FormsServlet.initArgs

This file is located at:

<ORACLE_HOME>\6iserver\apache\jserv\servlets\oracle\
forms\servlet\FormsServlet.initArgs

Edit this file only if you are using the servlet implementation. It contains the following parameters:

Do not reference any environment variables in the fully qualified path.Note:

On both UNIX and NT, specify fully qualified paths using the forward slash (/), and not the backslash (\).Note:

The parameter names are case sensitive in the FormsServlet.initArgs file.

5.5.2 formsweb.cfg

This file contains most of the servlet and CGI configuration parameter settings that you set during installation. You can modify these parameters, if needed.

Variables (%variablename%) in the base HTML file are replaced with the appropriate parameter values specified in the formsweb.cfg file and from query parameters in the URL request (if any).

We recommend that you enter configuration changes in the formsweb.cfg file, and use variables in the baseHTML file.

5.5.2.1 Creating special configurations in formsweb.cfg

You can create specific, named configurations in the formsweb.cfg file. These configurations can be requested in the end-user's query string of the URL used to run a form.

Create special configurations by adding the name of the configuration in brackets at the end of the formsweb.cfg file. Then, specify the parameters for this special configuration. (Specify only the parameters that you want to change.)

For example, to create a configuration to run forms in a separate browser window with a "generic" look and feel, add the following code to the formsweb.cfg file:

[sepwin] 
separateFrame=True 
lookandfeel=Generic 

The end-user would type the following URL to launch a form that uses the "sepwin" configuration:

http://server:port/servlet/f60servlet?config=sepwin

(for a servlet configuration)

http://myhost.mydomain.com/dev60cgi/ifcgi60.exe?config=sepwin

(for a CGI configuration)

See Section 5.5.2.3, "Default formsweb.cfg File" for other examples of special configurations.

5.5.2.2 Parameters in the formsweb.cfg File

<PARAM NAME="connectMode"  VALUE="%connectMode%">

5.5.2.3 Default formsweb.cfg File

The default formsweb.cfg file contains the following:

; Forms Web CGI Configuration File
; --------------------------------
; This file defines parameter values used by the Forms Web CGI

; ********************************
; PARAMETER VALUES USED BY DEFAULT
; ********************************
  ; SYSTEM PARAMETERS
  ; -----------------
  ; These have fixed names and give information required by the Forms 
  ; Web CGI in order to function.  They cannot be specified in the URL query 
  ; string.  But they can be overriden in a named configuration (see below).
baseHTML=d:\orant\forms60\server\base.htm
baseHTMLJInitiator=d:\orant\forms60\server\basejini.htm
baseHTMLie=d:\orant\forms60\server\baseie.htm
HTMLdelimiter=%
MetricsServerPort=9020
MetricsServerErrorURL=
  ; The next parameter specifies how to execute the Forms applet under 
  ; Microsoft Internet Explorer 5.0.  Put IE50=native if you want the
  ; Forms applet to run in the browser's native JVM.  
IE50=native
  ; USER PARAMETERS
  ; ---------------  
  ; These match variables (e.g. %form%) in the baseHTML file. Their values 
  ; may be overridden by specifying them in the URL query string
  ; (e.g. "http://myhost.mydomain.com/ifcgi60.exe?form=myform&width=700")
  ; or by overriding them in a specific, named configuration (see below)

  ; 1) Runform arguments:
form=test.fmx
otherparams=
userid=

  ; 2) HTML page title, attributes for the BODY tag, and HTML to add before and 
  ;    after the form:
pageTitle=Oracle Forms Server
HTMLbodyAttrs=
HTMLbeforeForm=<B>Hello</B>
HTMLafterForm=

  ; 3) Values for the Forms applet parameters:
width=650
height=500
separateFrame=false
splashScreen=no
    ; select default background by not specifying a value
background=
lookAndFeel=Oracle
colorScheme=teal
serverApp=default
serverPort=9000
serverHost=rlouis-lap
connectMode=Socket
archive=f60all.jar
archive_ie=f600all.cab
archive_jinit=f60all_jinit.jar

  ; 4) Parameters for JInitiator
    ; Page displayed to Netscape users to allow them to download JInitiator.  
    ; If you create your own version, set this parameter to point to it.
jinit_download_page=/jinitiator/us/jinit_download.htm
    ; Parameters related to the version of JInitiator.
jinit_classid=clsid:21157916-4d49-11d4-a3e0-00c04fa32518
jinit_exename=jinit.exe#Version=1,1,7,30
jinit_mimetype=application/x-jinit-applet;version=1.1.7.30

; ********************************
; SPECIFIC CONFIGURATIONS
; ********************************
;  You may define your own specific, named configurations (sets of parameters)
;  by adding special sections as illustrated in the following examples.  
;  Note that you need only specify the parameters you want to change.  The 
;  default values (defined above) will be used for all other parameters.
;  Use of a specific configuration can be requested by including the text 
;  "config=<your_config_name>" in the query string of the URL used to run
;  a form.  For example, to use the sepwin configuration, your could issue
;  a URL like "http://myhost.mydomain.com/ifcgi60.exe?config=sepwin".

; Example 1: configuration to run forms in a separate browser window with 
;            "generic" look and feel (include "config=sepwin" in the URL)
[sepwin]
separateWindow=True
lookandfeel=Generic

; Example 2: configuration affecting users of MicroSoft Internet Explorer 5.0.  
;            Forms applet will run under the browser's native JVM rather than 
;            using Oracle JInitiator.
[ie50native]
IE50=native

; Example 3: configuration forcing use of the base.htm base HTML file in all 
;            cases (means applet-style tags will always be generated and 
;            JInitiator will never be used).  
[applet]
baseHTMLJInitiator=

5.5.3 base.htm, basejini.htm, and baseie.htm

Three base HTML files are created for your system by the Oracle Universal Installer during Form Services installation and configuration. In most cases, you will not need to modify these files.

When a user first starts a Web-enabled application (by clicking a link to the application's URL), a base HTML file is read by Forms Servlet or CGI.

Any variables (%variablename%) in the base HTML file are replaced with the appropriate parameter values specified in the formsweb.cfg file described in Section 5.5.2, "formsweb.cfg", and from query parameters in the URL request (if any).

For servlet implementations, the baseHTML, baseHTMLJInitiator, and baseHTMLIE tags are replaced with the values specified in the FormsServlet.initArgs file described in Section 5.5.1, "FormsServlet.initArgs".

Then, the base HTML file is downloaded to the user's Web browser.

Any base HTML variables that you want to modify can be changed by modifying the corresponding parameter values in the FormsServlet.initArgs file described in Section 5.5.1, "FormsServlet.initArgs" and in the formsweb.cfg file, described in Section 5.5.2, "formsweb.cfg".

The following base HTML starter files are available in the <ORACLE_HOME>/6iserver/forms60/server directory:

• basejini.htm: This is a base HTML file containing the tags required to run the Forms applet using Oracle JInitiator. It is suitable for browsers (only on Windows platforms) certified by Oracle to work in this manner (and which do not work using standard APPLET tags). See Section 5.5.3.4, "Default basejini.htm File" for an example. Also, see Appendix B, "Client Browser Support" for more information about JInitiator settings.

• base.htm: This is a base HTML file containing the APPLET tags required to run the Forms applet in the AppletViewer, or in any Web browser certified by Oracle whose native JVM is certified with Forms. See Section 5.5.3.3, "Default base.htm File" for an example. Also, see Appendix B, "Client Browser Support" for more information about native JVM and AppletViewer settings.

• baseie.htm: This is a base HTML file containing the Internet Explorer 5 tags required to use native JVM in Internet Explorer 5. See Section 5.5.3.5, "Default baseie.htm File" for an example. Also, see Appendix B, "Client Browser Support" for more information about Internet Explorer and native JVM.

If you decide to create a new base HTML file:

1. Copy the basejini.htm or base.htm starter file, which is located in the <ORACLE_HOME>/6iserver/forms60/server directory.

2. Rename the file, for example, order.htm.

3. Add or modify any text that is visible to the user (for example text contained within <TITLE> and <BODY> tags).

4. Modify the parameters as needed. We recommend that you use variables in the base HTML file, and specify the actual values in the FormsServlet.initArgs and formsweb.cfg files, as described in Section 5.5.1, "FormsServlet.initArgs" and Section 5.5.2, "formsweb.cfg".

5. Place the new base HTML file in any directory. Update the baseHTML, baseHTMLJInitiator, or baseHTMLIE parameter in the FormsServlet.initArgs and formsweb.cfg files to contain the base HTML file's full physical path location.

5.5.3.1 Parameters and variables in the base HTML file

If you do not want to use a parameter tag that is provided in the base.htm or basejini.htm file, delete it from the file.

<PARAM NAME="connectMode"  VALUE="%connectMode%">

<PARAM NAME="cabbase"  VALUE="%archive_ie%">

5.5.3.2 Usage Notes

• You can use a variable value anywhere in the base HTML file. Variables are specified as a name enclosed in a special delimiter. (The default delimiter is %.) For example, you could have the following line in your HTML file:
  ARCHIVE="%Archive%"
  You then must assign a value to %Archive% either in the formsweb.cfg file (or in the URL query string).
  All variables must receive values at runtime. If a variable does not receive a value, Form Services cannot build an HTML file to pass back to the user's Web browser, resulting in an error.

  To streamline performance, use only one Web server as a source for JAR file downloads. This will prevent multiple downloads of the same files from different servers.

5.5.3.3 Default base.htm File

<HTML> 
<!-- FILE: base.htm (Forms Server)                        --> 

<!-- This is the default base HTML file for running a form on the   --> 
<!-- web using APPLET-style tags to include the Forms applet.       --> 
<!-- This file will be REPLACED if you reinstall "Forms Web CGI and --> 
<!-- cartridge", so you are advised to make your own version if you --> 
<!-- want to make any modifications.  You should then set the       --> 
<!-- baseHTML parameter in the Forms web CGI configuration file     --> 
<!-- (formsweb.cfg) to point to your new file instead of this one.  --> 

<!-- IMPORTANT NOTE: default values for all the variables which     --> 
<!-- appear below (delimited by the percent character) are defined  --> 
<!-- in the formsweb.cfg file. It is preferable to make changes in  --> 
<!-- that file where possible, and leave this one untouched.        --> 

<HEAD><TITLE>%pageTitle%</TITLE></HEAD> 

<BODY %HTMLbodyAttrs%> 
%HTMLbeforeForm% 

<!-- Forms applet definition (start) --> 
<APPLET CODEBASE="/forms60java/" 
        CODE="oracle.forms.engine.Main" 
        ARCHIVE="%archive%" 
        WIDTH="%Width%" 
        HEIGHT="%Height%"> 

<PARAM NAME="serverPort" VALUE="%serverPort%"> 
<PARAM NAME="serverHost" VALUE="%serverHost%"> 
<PARAM NAME="connectMode" VALUE="%connectMode%"> 
<PARAM NAME="serverArgs" 
       VALUE="module=%form% userid=%userid% %otherParams%"> 
<PARAM NAME="separateFrame" VALUE="%separateFrame%"> 
<PARAM NAME="splashScreen"  VALUE="%splashScreen%"> 
<PARAM NAME="background"  VALUE="%background%"> 
<PARAM NAME="lookAndFeel"  VALUE="%lookAndFeel%"> 
<PARAM NAME="colorScheme"  VALUE="%colorScheme%"> 
<PARAM NAME="serverApp" VALUE="%serverApp%"> 

</APPLET> 
<!-- Forms applet definition (end) --> 

%HTMLafterForm% 

</BODY> 
</HTML> 

5.5.3.4 Default basejini.htm File

<HTML>
<!-- FILE: basejini.htm (Oracle Developer Forms)                    -->

<!-- This is the default base HTML file for running a form on the   -->
<!-- web using JInitiator-style tags to include the Forms applet.   -->
<!-- This file will be REPLACED if you reinstall "Forms Web CGI and -->
<!-- cartridge", so you are advised to make your own version if you -->
<!-- want to make any modifications.  You should then set the       -->
<!-- baseHTML parameter in the Forms web CGI configuration file     -->
<!-- (formsweb.cfg) to point to your new file instead of this one.  -->

<!-- IMPORTANT NOTE: default values for all the variables which     -->
<!-- appear below (delimited by the percent character) are defined  -->
<!-- in the formsweb.cfg file. It is preferable to make changes in  -->
<!-- that file where possible, and leave this one untouched.        -->

<HEAD><TITLE>%pageTitle%</TITLE></HEAD>

<BODY %HTMLbodyAttrs%>
%HTMLbeforeForm%

<!-- Forms applet definition (start) -->
<OBJECT classid="%jinit_classid%"
        codebase="/jinitiator/%jinit_exename%"
        WIDTH="%Width%"
        HEIGHT="%Height%"
        HSPACE="0"
        VSPACE="0">
<PARAM NAME="TYPE"       VALUE="%jinit_mimetype%">
<PARAM NAME="CODEBASE"   VALUE="/forms60java/">
<PARAM NAME="CODE"       VALUE="oracle.forms.engine.Main" >
<PARAM NAME="ARCHIVE"    VALUE="%archive%" > 

<PARAM NAME="serverPort" VALUE="%serverPort%">
<PARAM NAME="serverHost" VALUE="%serverHost%">
<PARAM NAME="connectMode" VALUE="%connectMode%">
<PARAM NAME="serverArgs" 
       VALUE="module=%form% userid=%userid% %otherParams%">
<PARAM NAME="separateFrame" VALUE="%separateFrame%">
<PARAM NAME="splashScreen"  VALUE="%splashScreen%">
<PARAM NAME="background"  VALUE="%background%">
<PARAM NAME="lookAndFeel"  VALUE="%lookAndFeel%">
<PARAM NAME="colorScheme"  VALUE="%colorScheme%">
<PARAM NAME="serverApp" VALUE="%serverApp%">
<COMMENT> 
<EMBED SRC="" PLUGINSPAGE="%jinit_download_page%" 
        TYPE="%jinit_mimetype%" 
        java_codebase="/forms60java/" 
        java_code="oracle.forms.engine.Main" 
        java_archive="%archive%" 
        WIDTH="%Width%"
        HEIGHT="%Height%" 
        HSPACE="0"
        VSPACE="0"

        serverPort="%serverPort%"
        serverHost="%serverHost%"
        connectMode="%connectMode%"
        serverArgs="module=%form% userid=%userid% %otherparams%"
        separateFrame="%separateFrame%"
        splashScreen="%splashScreen%"
        background="%background%"
        lookAndFeel="%lookAndFeel%"
        colorScheme="%colorScheme%"
        serverApp="%serverApp%"
>
<NOEMBED> 
</COMMENT> 
</NOEMBED></EMBED> 
</OBJECT>
<!-- Forms applet definition (end) -->

%HTMLafterForm%

</BODY>
</HTML>

5.5.3.5 Default baseie.htm File

<HTML>
<!-- FILE: base.htm (Oracle Developer Forms)                        -->

<!-- This is the default base HTML file for running a form on the   -->
<!-- web using APPLET-style tags to include the Forms applet.       -->
<!-- This file will be REPLACED if you reinstall "Forms Web CGI and -->
<!-- cartridge", so you are advised to make your own version if you -->
<!-- want to make any modifications.  You should then set the       -->
<!-- baseHTML parameter in the Forms web CGI configuration file     -->
<!-- (formsweb.cfg) to point to your new file instead of this one.  -->

<!-- IMPORTANT NOTE: default values for all the variables which     -->
<!-- appear below (delimited by the percent character) are defined  -->
<!-- in the formsweb.cfg file. It is preferable to make changes in  -->
<!-- that file where possible, and leave this one untouched.        -->

<HEAD><TITLE>%pageTitle%</TITLE></HEAD>

<BODY %HTMLbodyAttrs%>
%HTMLbeforeForm%

<!-- Forms applet definition (start) -->
<APPLET CODEBASE="/forms60java/"
        CODE="oracle.forms.engine.Main"
        WIDTH="%Width%"
        HEIGHT="%Height%">

<PARAM NAME="cabbase" VALUE="%archive_ie%">
<PARAM NAME="serverPort" VALUE="%serverPort%">
<PARAM NAME="serverHost" VALUE="%serverHost%">
<PARAM NAME="connectMode" VALUE="%connectMode%">
<PARAM NAME="serverArgs" 
       VALUE="module=%form% userid=%userid% %otherParams%">
<PARAM NAME="separateFrame" VALUE="%separateFrame%">
<PARAM NAME="splashScreen"  VALUE="%splashScreen%">
<PARAM NAME="background"  VALUE="%background%">
<PARAM NAME="lookAndFeel"  VALUE="%lookAndFeel%">
<PARAM NAME="colorScheme"  VALUE="%colorScheme%">
<PARAM NAME="serverApp" VALUE="%serverApp%">

</APPLET>
<!-- Forms applet definition (end) -->

%HTMLafterForm%

</BODY>
</HTML>

5.6 Reading the Servlet Error Log

If you are using the Forms Servlet implementation, any configuration errors in the formsweb.cfg and FormsServlet.initArgs files are logged to the jserv.log file. This file is located in <ORACLE_HOME>/apache/Jserv/logs.

5.7 Setting Up the HTTPS Connection Mode

The HTTPS connection mode uses HTTP for communications in order to traverse firewalls. In addition, Form Services uses SSL as a transport protocol to provide privacy, integrity, and server authentication. See Section 3.2.3, "HTTPS" for a description of this communications mode.

To use the HTTPS mode, you need to:

• On your web server: If end-user browsers are using Internet Explorer with native JVM, configure the web server to use SSL, which requires the use of a certificate on the web server. The steps to do this vary for different web servers, so see your web server documentation for details. If end-user browsers are using Internet Explorer with native JVM, users must download the initial Forms startup HTML page in HTTPS mode. (This step is optional for Oracle JInitiator.)

• On Form Services:
  • Customize HTTPS Environment Variables

  • Depending on client configurations, use one of the following sets of steps:
    Create Wallets and Request Certificates, or
    Create Wallets and Request Certificates That Are Not Trusted by JInitiator by Default

See the client browser descriptions that follow to determine which steps to use.

• For client browsers: Depending on the client browsers being used, you may need to take steps to ensure that certificates installed on the web server and Form Services are trusted by the client browser.
  If your client browsers are using Internet Explorer 5 with native JVM to display forms, use the steps described in Create Wallets and Request Certificates.
  If your client browsers are using Oracle JInitiator to display forms, the following CAs and certificates are trusted by JInitiator by default. If you are using one of the following certificates, use the steps described in Create Wallets and Request Certificates:
  • VeriSign, Inc. - Class 1, 2, 3 Public Primary Certification Authority

  • RSA Data Security Inc. - Secure Server Authority

  • GTE CyberTrust Solutions Inc.- CyberTrust Global Root

  • GTE Corporation.- CyberTrust Root

  If your client browsers are using Oracle JInitiator and you did not use one of the certificates listed above, use the steps described in Create Wallets and Request Certificates That Are Not Trusted by JInitiator by Default.

For client browsers using AppletViewer, the HTTPS connection mode is not supported.Note:

Oracle Wallet Manager must be installed on Form Services to use the HTTPS connection mode and on all Form Services machines that will provide server authentication.

5.7.1 Customize HTTPS Environment Variables

Two environment variables associated with HTTPS mode are set during Form Services installation. Check that these environment variables are set to meet your security needs, and change them, if needed, on all Form Services machines running in HTTPS mode. See Section 5.3, "Customizing Environment Variables" for information on how to change environment variables.

5.7.2 Create Wallets and Request Certificates

Public-key cryptography requires, among other things, certificates. A user certificate is issued by a third party, called a certificate authority (CA). The certificate is obtained in a secure manner and does not need to be validated for its authenticity each time it is accessed.

In the case of Form Services and a client using HTTPS mode, the client validates that Form Services is who it claims to be by verifying the server's certificate. You use Oracle Wallet Manager to create wallets and request certificates.

After installing Oracle Wallet Manager on Form Services, you must do the following to obtain a certificate:

• Create a Wallet

• Create a Certificate Request

• Send the Certificate Request

• Import the Certificate

• Set Auto Login to ON

The following sections provide an overview of how to complete the above steps in Oracle Wallet Manager. See the Oracle Wallet Manager documentation for details.

If you have multiple Form Services machines, you can request a unique certificate for each machine, or you can use the same certificate on all machines. Contact the CA for any licensing restrictions.

• To use a unique certificate on each machine, perform all of the procedures in this section on each Form Services machine running in HTTPS mode.

• To use the same certificate on all machines, perform all of the procedures in this section on one of the Form Services machines to create a wallet that contains a certificate. Then, copy the wallet file, ewallet.der, to the other Form Services machines running in HTTPS mode. Copy the file to the directory specified in the FORMS60_WALLET environment variable. Finally, be sure that Auto Login is set to ON on all machines, as described in Set Auto Login to ON.

5.7.2.1 Create a Wallet

On UNIX, run owm, which is located in the <ORACLE_HOME>/6iserver/bin directory.

On NT, run the Oracle Wallet Manager by clicking on Start Programs Oracle for Windows NT Oracle Wallet Manager.

Create a wallet as follows:

1. Click Wallet New from the menu bar. The New Wallet dialog box is displayed.

2. Type a password in the Wallet Password field.

3. Retype that password in the Confirm Password field.

4. Click OK to continue. A message appears, and informs you that a new empty wallet has been created, and prompts you to decide whether you want to create a certificate request.

5. Click Yes, and see the next section.

5.7.2.2 Create a Certificate Request

Create a certificate request as follows:

1. Type the following information in the Certificate Request dialog box:
   • Common Name: Type the name of the certificate identity in First name Last name format. For example you could use the name of the server administrator.

   • Organizational Unit: Type the name of the organizational unit, for example, Finance.

   • Organization: Type the name of the organization, for example, XYZ Corp.

   • Locality/City: Type a city or locality.

   • State/Province: Type a state or province. Do not use abbreviations such as CA for California.

   • Country: Click the drop down list to view a list of country abbreviations. Click to select the country in which the organization is located.

   • Key Size: Click the drop down box to view a list of key sizes to use when creating the public/private key pair.

   • Advanced: Click Advanced to view the Advanced Certificate Request dialog panel. Use this field to edit or customize the distinguished name (DN).

2. Click OK. An Oracle Wallet Manager message box informs you that a certificate request was successfully created.

3. Save the wallet to the disk now or at any other time by clicking on Wallet Save. You will be prompted for a directory name.

5.7.2.3 Send the Certificate Request

There are many ways to send the certificate request to one of the trusted CAs. The most common way is to cut and paste the certificate request from Oracle Wallet Manager into the CA's certificate request form on the web. You can also copy the certificate request text from the body of the Oracle Wallet Manager message box, paste it into an e-mail message, and send the request to the certificate authority if they accept requests in that format.

Then, return to the Oracle Wallet Manager window, and click OK. An Oracle Wallet Manager message box informs you that a certificate request was successfully created.

5.7.2.4 Import the Certificate

After you receive the certificate that you requested from the CA, you must import it into the wallet that you created. You can import it in one of two ways:

• Paste the certificate from an e-mail that you receive from the certificate authority.

• Import the certificate from a file.

To paste the certificate:

1. From the menu bar, click Operations Import User Certificate. The Import User Certificate dialog box opens.

2. Click the Paste the Certificate radio button, and click OK. An Import User Certificate dialog box opens with the following message: "Please provide a base64 format certificate and paste it below".

3. Copy the certificate from the body of the e-mail you received.

4. Paste the certificate into the window, and click OK. A message at the bottom of the window informs you that the certificate was successfully installed.

5. Click OK. You are returned to the Oracle Wallet Manager main panel, and the certificate is displayed at the bottom of the User Certificates tree.

6. Save the wallet to the disk now or at any other time by clicking on Wallet Save.

To import a file that contains the certificate:

1. From the menu bar, click Operations Import User Certificate. The Import User Certificate dialog box opens.

2. Type the path or folder name of the certificate location.

3. Click to select the name of the certificate file, for example, cert.txt.

4. Click OK. A message at the bottom of the window informs you that the certificate was successfully imported into the wallet.

5. Click OK to close the dialog box. You are returned to the Oracle Wallet Manager main panel, and the certificate is displayed at the bottom of the User Certificates tree.

6. Save the wallet to the disk now or at any other time by clicking on Wallet Save.

5.7.2.5 Set Auto Login to ON

The Oracle Wallet Manager Auto Login feature automatically opens a copy of the wallet. This allows

server authentication to occur without having to provide a password for the wallet. To set Auto Login to ON:

1. Click Wallet from the menu bar.

2. Click the check box next to the Auto Login menu item. This will create a file called cwallet.sso. This file is machine-dependent, and cannot be copied from one machine to another.

3. A message at the bottom of the window displays "Autologin enabled".

The check box next to the Auto Login menu item can be toggled on and off. Click the check box again to clear the check mark. This will disable autologin.Note:

Auto Login must be set to ON for all Form Services machines that will provide server authentication.

5.7.3 Create Wallets and Request Certificates That Are Not Trusted by JInitiator by Default

In this section, the VeriSign Trial Certificate is used as an example of a certificate that is not trusted by JInitiator default.Note:

This section applies to a scenario where you plan to use certificates on the web server and Form Services that are not trusted by Oracle JInitiator by default. The following CAs and certificates are trusted by Oracle JInitiator:

• VeriSign, Inc. - Class 1, 2, 3 Public Primary Certification Authority

• RSA Data Security Inc. - Secure Server Authority

• GTE CyberTrust Solutions Inc.- CyberTrust Global Root

• GTE Corporation.- CyberTrust Root

If you are using one of the certificates listed above, use the steps in Create Wallets and Request Certificates.

Public-key cryptography requires, among other things, certificates. A user certificate is issued by a third party, called a certificate authority (CA). The certificate is obtained in a secure manner and does not need to be validated for its authenticity each time it is accessed.

In the case of Form Services and a client using HTTPS mode, the client validates that Form Services is who it claims to be by verifying the server's certificate. You use Oracle Wallet Manager to create wallets and request certificates.

After installing Oracle Wallet Manager on Form Services, you must do the following to obtain a certificate:

• Create a Wallet

• Create a Certificate Request

• Send the Certificate Request

• Install the VeriSign Trial CA Root Certificate on Client Machines

• Import the Certificate

• Set Auto Login to ON

If you have multiple Form Services machines, you can request a unique certificate for each machine, or you can use the same certificate on all machines.

• To use a unique certificate on each machine, perform all of the procedures in this section on each Form Services machine running in HTTPS mode.

• To use the same certificate on all machines, perform all of the procedures in this section on one of the Form Services machines to create a wallet that contains a certificate. Then, copy the wallet file, ewallet.der, to the other Form Services machines running in HTTPS mode. Copy the file to the directory specified in the FORMS60_WALLET environment variable. Finally, be sure that Auto Login is set to ON on all machines, as described in Set Auto Login to ON.

5.7.3.1 Create a Wallet

On UNIX, run owm, which is located in the <ORACLE_HOME>/6iserver/bin directory.

On NT, run the Oracle Wallet Manager by clicking on Start Programs Oracle for Windows NT Oracle Wallet Manager.

Create a wallet as follows:

1. Click Wallet New from the menu bar. The New Wallet dialog box is displayed.

2. Type a password in the Wallet Password field.

3. Retype that password in the Confirm Password field.

4. Click OK to continue. A message appears, and informs you that a new empty wallet has been created, and prompts you to decide whether you want to create a certificate request.

5. Click Yes, and see the next section.

5.7.3.2 Create a Certificate Request

Create a certificate request as follows:

1. Type the following information in the Certificate Request dialog box:
   • Common Name: Type the name of the certificate identity in First name Last name format. For example you could use the name of the server administrator.

   • Organizational Unit: Type the name of the organizational unit, for example, Finance.

   • Organization: Type the name of the organization, for example, XYZ Corp.

   • Locality/City: Type a city or locality.

   • State/Province: Type a state or province. Do not use abbreviations such as CA for California.

   • Country: Click the drop down list to view a list of country abbreviations. Click to select the country in which the organization is located.

   • Key Size: Click the drop down box to view a list of key sizes to use when creating the public/private key pair.

   • Advanced: Click Advanced to view the Advanced Certificate Request dialog panel. Use this field to edit or customize the distinguished name (DN).

2. Click OK. An Oracle Wallet Manager message box informs you that a certificate request was successfully created.

3. Save the wallet to the disk now or at any other time by clicking on Wallet Save. You will be prompted for a directory name.

5.7.3.3 Send the Certificate Request

There are many ways to send the certificate request to the CA. The most common way is to cut and paste the certificate request from Oracle Wallet Manager into the CA's certificate request form on the web. You can also copy the certificate request text from the body of the Oracle Wallet Manager message box, paste it into an e-mail message, and send the request to the certificate authority if they accept requests in that format.

We are using the Trial Server Certificate from VeriSign as an example in these steps:

1. Using your browser, go to www.verisign.com.

2. Search for "Trial Server Certificate" if you do not see a link on the home page.

3. VeriSign's web site lists five steps that you need to perform. Start by performing the first three steps:
   • Step 1: Generate CSR. You have already completed this step using Oracle Wallet Manager.

   • Step 2: Submit CSR. Cut and paste the certificate request information from Oracle Wallet Manager into the Enter CSR information field of VeriSign's Trial Server Certificate web page.

   • Step 3: Complete Application. Enter the Technical Contact Information, such as the e-mail address where the certificate should be sent, into the VeriSign Trial Server Certificate web page.

4. Now, return to the Oracle Wallet Manager window, and click OK. An Oracle Wallet Manager message box informs you that a certificate request was successfully created.

5. You will complete the final two steps, listed below, in the sections that follow:
   • Step 4: Install Test CA Root. We will do this in the next section.

   • Step 5: Install your Test Server ID. We will do this in the next section.

5.7.3.4 Install the VeriSign Trial CA Root Certificate on Client Machines

You will need to use Internet Explorer 5.0 to install the CA root certificate and export it as a Base64 encoded X.509(.CER) file, which can be read by Oracle Wallet Manager. (Unfortunately, you cannot use Netscape because it does not allow the export of the root certificates to a file.)

1. Using Internet Explorer 5.0, go to http://www.verisign.com/server/trial/welcome/caroot.html.

2. Follow the instructions, and download the CA root certificate into your browser.

3. Click on Tools Internet Options Content and Certificates.

4. When the Certificate Manager displays, make sure the Intended Purpose option is set to All, and click Trusted Root Certification Authorities.

5. Select the certificate that has the value For VeriSign authorized testing only... in the Issued to column.

6. Click Export Next, and select Base64 encoded X.509(.CER).

7. Save it as vrsnca.cer.

8. Return to Oracle Wallet Manager.

9. Click Operations Import Trusted Certificate.

10. Click Select a file that contains the certificate.

11. Open the file vrsnca.cer that you just saved.

12. Be sure you see For VeriSign authorized testing only listed among the Trusted Certificates.

13. Export all trusted certificates by clicking Operations Export All Trusted Certificates.

14. Save it as vrsndb.txt.

15. On the client machine, replace the certdb.txt of Jinitiator with the new version by making a backup copy of \Program Files\Oracle\Jinitiator\lib\security\certdb.txt. Then, copy vrsndb.txt onto \Program Files\Oracle\Jinitiator\lib\security\certdb.txt. This step updates the list of CAs that are trusted by the client.

5.7.3.5 Import the Certificate

After VeriSign processes your request, you will receive an email from VeriSign containing the certificate which looks something like this:

-----BEGIN CERTIFICATE-----
MIICETCCAXqgAwIBAgICAkkwDQYJKoZIhvcNAQEEBQAwazELMAkGA1UEBhMCVV
Mx
DzANBgNVBAoTBk9yYWNsZTEoMCYGA1UECxMfRW50ZXJwcmlzZSBBcHBsaWNhdG
lv
biBTZXJ2aWNlczEhMB8GA1UEAxMYRUFTUUEgQ2VydGlmaWNhdGUgU2VydmVyMB
4X
DTk5MDcyNjE3MzkyNloXDTAwMDEyMjE3MzkyNlowPTELMAkGA1UEBhMCVVMxDz
A
BgNVBAoTBm9yYWNsZTEOMAwGA1UECxMFZm9ybXMxDTALBgNVBAMTBGFtYXIw
-----END CERTIFICATE-----

After you receive the certificate, you must import it into the wallet that you created. You can import it in one of two ways:

• Paste the certificate from an e-mail that you receive from the certificate authority.

• Import the certificate from a file.

To paste the certificate:

1. From the Oracle Wallet Manager menu bar, click Operations Import User Certificate. The Import User Certificate dialog box opens.

2. Click the Paste the Certificate radio button, and click OK. An Import User Certificate dialog box opens with the following message: "Please provide a base64 format certificate and paste it below".

3. Copy the certificate from the body of the e-mail you received or the web page.

4. Paste the certificate into the window, and click OK. A message at the bottom of the window informs you that the certificate was successfully installed.

5. Click OK. You are returned to the Oracle Wallet Manager main panel, and the certificate is displayed at the bottom of the User Certificates tree.

6. Save the wallet to the disk now or at any other time by clicking on Wallet Save.

To import a file that contains the certificate:

1. From the menu bar, click Operations Import User Certificate.

2. Type the path of the certificate location in the Import User Certificate dialog box.

3. Click to select the name of the certificate file, for example, cert.txt.

4. Click OK. A message at the bottom of the window informs you that the certificate was successfully imported into the wallet.

5. Click OK to close the dialog box. You are returned to the Oracle Wallet Manager main panel, and the certificate is displayed at the bottom of the User Certificates tree.

6. Save the wallet to the disk now or at any other time by clicking on Wallet Save.

5.7.3.6 Set Auto Login to ON

The Oracle Wallet Manager Auto Login feature automatically opens a copy of the wallet. This allows

server authentication to occur without having to provide a password for the wallet. To set Auto Login to ON:

1. Click Wallet from the menu bar.

2. Click the check box next to the Auto Login menu item. This will create a file called cwallet.sso. This file is machine-dependent, and cannot be copied from one machine to another.

3. A message at the bottom of the window displays "Autologin enabled".

The check box next to the Auto Login menu item can be toggled on and off. Click the check box again to clear the check mark. This will disable autologin.Note:

Auto Login must be set to ON for all Form Services machines that will provide server authentication.

5.8 What's Next

After completing the configuration of Form Services, you can deploy your applications to the Web. Refer to Chapter 6, "Deploying Forms to the Web" for more detailed information.