Manual: Install openSEAL and Reference Application

Setup and Installation

This document provides step-by-step instructions for compiling, configuring and installing the openSEAL library, and the openSEAL reference application (features). It operates as both a Windows Service and Web application.

Before you start, System Requirements

The following instructions make certain assumptions about the installation environment. The instructions were put together based on a Windows XP Professional SP1 Compaq Evo N1000c, Pentium 4 1.7 Ghz with 512 MB memory. It is likely the instructions will be very different on a W2K machine. Additionally, the following assumptions are made:

  • Internet Information Server (IIS)
    Make sure IIS is installed on the host system. Look in the system Services. If you find World Wide Web Publishing service, IIS is installed. If not installed, open the Control Pannel, Choose "Add or Remove Programs" and them choose "Add/Remove Windows Components".  Check the box next to Internet Information Services (IIS) and choose "Next". The OS should now install IIS.
  • .NET Framework
    You must have a .version of the .NET Framework installed on the target host. These installations were tested with version both 1.0.3705 and 1.1.4322 (recommended).
  • (Optional but Recommended) NANT Opensource Build Tool
    NANT is a open source tool that the openSEAL team use to automate many of the build and configuration tasks. We strongly recommend that you use this too. Visit http://nant.sourceforge.net to download (new window).
  • (Optional) Relational Database
    A relational database either locally or accessed across the network. The reference application has currently been tested with Oracle 8.1.7 and Oracle 9i, SQL Server 2000. Testing and development with MySQL is currently underway.
  • (Optional) Message Server
    Some of the business tier functionality demonstrates the messaging capabilities.

Step 1. Download

Click here to download openSEAL & the openSEAL Reference Application.

The openSEAL library and Reference Application is distributed as a compressed archive. When uncompressed using standard tools (WinZip for example), a directory structure will be created in the extraction destination. Click here to see details of the openSEAL source directory structure.

Once you have downloaded and unzipped the file, read the README.txt file that is in the root of the directory structure you have just extracted.

Step 2. Setup the Environment Variables

The following instructions make certain assumptions about the installation environment. The instructions were put together based on a Windows XP Professional SP1 Compaq Evo N1000c, Pentium 4 1.7 Ghz with 512 MB memory. It is likely the instructions will be different on a W2K machine. Additionally, the following assumptions are made:

  • C# compiler added to environment path. The Nant build scripts assume that the csc.exe compiler is in the environment path. You may need to add to you path to perform builds successfully.
  • (Optional) We recommend adding the nant.exe executable to your path for simplicity.

Step 3. Compiling the Source

The openSEAL library is distributed as source code. In order to use the library, it must be compiled to a .NET assembly. The library is best compiled using the provided Nant scripts.

Setup the openSEAL Library Assembly

  1. Open a windows command shell (by typing cmd in the "Run" texbox for example), and navigate to the openSEAL script\build directory (using cd filepath).
  2. Type the following command to check that NANT is setup correctly:
    nant -buildfile:openseal.build -projecthelp
    You should see a list of NANT "targets". If you get an error message refer to Environment Variables section above. (Note: you can run this -projecthelp target any time to get a quick description of the targets available).
  3. To run the (one-time) setup target, type:
    nant -buildfile:openseal.build setup
    This adds the bin directories, and moves the logging assembly into them.
  4. To compile the openSEAL Library, type:
    nant -buildfile:openseal.build build
    This compiles the openSEAL library code into "openSEAL.dll" and puts this assembly into the bin directories.

Setup the Reference Application Assemblies

  1. Edit the configuration files, making sure that the paths correspond to the location of openSEAL in your file system.
  2. To compile the Reference Application Assembles, type:
    nant -buildfile:refapp.build build
    This compiles the 4 reference application assemblies into the required bin directories.

Step 4. Configuring IIS

To configure the openSEAL reference application web tier, the following steps are recommended:

  1. Start WWW Service
    Double check that the World Wide Publishing service is present on the system (see System Requirements above). If the service is not started, start it now.
  2. Create "refapp" virtual directory
    Create a new virtual directory in IIS named "refapp". When asked to choose a directory, navigate to the root openSEAL directory on the local filesystem and choose the webroot/refapp directory. Make sure the options for "Read", "Execute" and "Run Scripts" are checked.
  3. Configure the newly created virtual directory
    Again in the properties of the "refapp", change the "Application Protection" level to "High (isolated)". This runs the virtual directory as a separate process. Select the "Directory Security" tab, click the "Edit" button. Uncheck the "Integrated Windows authentication" box and click the "OK" button. Select the "Documents" tab and add an entry for "index.html". Click the Apply and then the OK button.
  4. (1 time only) Configure the openseal extension mapping
    You may have already done this if you set up a previous version of openSEAL. Open the properties view of the "refapp" virtual directory and select the "Configuration" button. Select the "Add" button to add a new extension for the reference application. For the executable browse to the aspnet_isapi.dll. On a standard  .NET installation, this will be something like:
    C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\aspnet_isapi.dll
    Set the extension to ".openseal". Select the "All Verbs" option and unselect the 'Check that file exists' option. Select the OK button. (Note that there is a well-known IIS bug here, you may have to tab or click back in the Executable text field before IIS will enable the "OK" button.) Select "OK" again to close the "Application Configuration" section.

Step 5. Editing Configuration Files

There are 3 configuration files that you should review and possibly edit in order for the reference application to work correctly. (For comprehensive details of editing config files, see the User Manual).

Editing the Windows Service Config File

  1. The openSEAL_refapp_business_service.exe.config is located in the bin directory. Open it in a text editor and check the following values.
  2. Locate the section that configures remoting (<system.runtime.remoting>). Check that the path to the encryption private host key is correct (e.g. host_key= "c:\\projects\\openSEAL\\cvsroot\\OpenSEAL\\config\\refapp_host").
  3. Locate the <openseal.config> section. Check that the path to the remoting config self references this service config file (e.g. the value for the key refapp_remoting_config_file).
  4. Locate the <log4net> section. Check that the value for the file key is the path to where you would like the log file to write.

Editing the Web.config File

  1. The Web.config is located in the webroot\bin directory. Open it in a text editor and check the following values.
  2. Locate the section that configures remoting (<system.runtime.remoting>). Check that the path to the encryption public host key is correct (e.g. host_key= "c:\\projects\\openSEAL\\cvsroot\\OpenSEAL\\config\\refapp_host.pub").
  3. Locate the <openseal.config> section. Check that the path to the remoting config self references this Web.config file (e.g. the value for the key refapp_remoting_config_file).
  4. Locate the <log4net> section. Check that the value for the file key is the path to where you would like the log file to write.

Step 6. Installing & Starting the Services

Installing & Starting the Windows Service

  1. (Optional) You will need to uninstall the reference app that you previously installed for older versions of openSEAL:
    nant -buildfile:refapp.build uninstall_bas_winsvc
  2. To install the reference application services as a Windows Service, type:
    nant -buildfile:refapp.build install_bas_winsvc
    You should now be able to see both "openSEAL Refapp Win32 Business BAS" and "openSEAL Refapp Win32 Schedule BAS" in your computers list of Services (Control Panel > Administrative Tools > Services).
  3. To start the above Windows Services, you can either manually start the "openSEAL Refapp Win32 Schedule BAS" in the Services window (which will start the Business one too), or in you windows shell type:
    nant -buildfile:refapp.build start_bas_winsvc
    One way to check that this worked it to review your computers Event Viewer. You should see 2 "info" messages stating that the reference app is online and that it started successfully. If you have one or less, then chances are there is something wrong with the setup. If this is the case, double check the messages you recieved in the windows shell and use these to diagnose the problem.

Starting the WWW Service

  1. To start the WWW Service, type:
    nant -buildfile:refapp.build start_w3svc

Thats it!

You have now completed the openSEAL and Reference Application setup. In order to run the reference application:

  1. Open your Web Browser and navigate to your web server, for instance:
    http://localhost/refapp/
  2. You will see the logon page. Log onto the app by clicking on the link and typing either "admin/admin" or "test/test" for the username and password. The first time you log on you will experience a delay as ASPX pages compile.

Good luck with openSEAL and please let us know what you think by emailing the User Mailing List openseal-users.