openSEAL Installation Instructions

Index


1. Introduction
This document provides step-by-setp instructions for compiling, configuring and installing the openSEAL reference application to operate as both as both a Windows Service and Web application. The reference application is a representative set of functionality showing the bredth and depth of the openSEAL library.

The reference application demonstrates the following highlights of the openSEAL library:
  • XATransaction Support - The reference application follows a standard n-tier architecture. The business service of the reference application demonstrates the use of the openSEAL ResourceManager to participate in 2PC transactions using multiple managed resources (database and MSMQ specifically). This functionality is accomplished using all managed code and most importantly, without the use of any COM+ transactions.
  • MVC Web Tier Approach - The core of the openSEAL web tier design is a MVC (modle view controller) infrastructure similar in concept to Jakarta struts. While using the library does not require use of an MCV approach, the benefits are potentially significant if use properly.
  • Security Enhancements - The reference application uses several of the custom message sinks provided with the openSEAL library. These sinks provide enhanced security including encryption of data on the wire, thread impersonation propogation and message integrity checks using hashing.

2. Source Structure
The openSEAL library is distributed as a compressed archive. When uncompressed using standard tools (WinZip for example), a directory structure will be created in the extraction destination. The directory structure created will have the following nodes:

/OpenSEAL - the root directory for all things openSEAL
/bin - empty as part of the distribution, all source compiled  using the build scripts will be compiled to this directory
/config - storage area for the library configuration files; files will be moved from this directory to the appropriate directories as part of a script build
/doc - storage for generated documentation including ndoc-generated materials
/lib - third party libraries including log4j and nunit
/script - parent script directory
/build - holds all build scripts
/db - holds scripts for creating database tables used in the refapp
/misc - random perl scripts for simplified maintenance
/service - windows shell scrupts for managing services
/src - parent source directory
/org
/openseal
/chron - chron-like functionality
/config - configuration functionality
/container - functionality for providing service infrastructure including Win32 services
/db - database functionality
/exception - high-level exception hierarchy used throughout the library
/io - high-level IO functionality wrappers
/log - logging abstraction including a log4net implementation
/messaging - messaging functionality including MSMQ wrappers
/meta-inf - assembly attribute declarations
/remoting - remoting functionality provided by the library
/refapp - the reference application for the library
/business - the refapp business tier
/api - the public API for the business tier
/constant - constants for the business tier
/impl - the business tier implementation
/manager - business tier manager objects, coarse-grained functional units
/resource - managed resources used in the business tier
/db - refapp implementations of database functionality
/messaging - refapp implementations of messaging functionality
/meta-inf - assembly attributes for the business tier assemblies
/service - Win32 service implementation for the business service
/common - common functionality shared between tiers of the reference application
/meta-inf - assembly attributes for the common assembly
/security - security objects shared between tiers in the refapp
/service - common service access in the refapp
/api - the implementation for the common service API
/test - Nunit test suite for the refapp
/business - tests for the business tier specifically
/types - custom types for the refapp
/meta-inf - assembly attributes for the types in the refapp
/ui - user interface implementation for the refapp
/web
/constant - constants for the refapp
/meta-inf - assembly attributes for the refapp web application assembly
/param - refapp model implementaions
/request - request handler implementations for the refapp
/view - view implementations for the refapp
/control - ASP.NET control implementations for the refapp
/resource - functionality for managed resources, provides transactional management
/security - extended functionality for security in the library
/service - tier-specific functionality for general infrastructure
/test - tests for the library
/types - library custom types
/ui - user interface parent directory
/web
/command - command portion of the MVC architecture, general point of interaction with other tiers in an application
/constant - web tier constants
/control - controller functionality for moving a request to the appropriate command
/dispatch - functionality for routing request responses to a client
/error - error handling functionality in web applications
/module - optional http modules for use in a web application
/param - request parameter functionality
/security - web-specific security functionality
/service - web-specific implementation of container behavior
/view - base functionality for page rendering in a web application
/control - standard set of controls for building web apps
3.Environment Assumptions
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:



4. 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.

We recommend adding the nant.exe to your path for convenience. Nant is generally used from a windows command shell.


5. Configuring IIS
To configure the openSEAL reference application web tier, the following steps are recommended:

  1. 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 on the system. Choose Add or Remove Programs. Choose Add/Remove Windows Components.  Check the box next to Internet Information Services (IIS) .  Choose Next. The OS should install IIS. Double check that the Worls Wide Publishing service is now present on the system. If the service is not started, start it now.
  2. 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 IIS properties for Read, Execute and Run Scripts are checked.
  3. Configure the virtual directory. Open the properties view of the newlt created refapp virtual directory. 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.0.3705\aspnet_isapi.dll. Set the extension to '.openseal'. Select the 'All Verbs' option. 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.
  4. Other IIS configuration. Change the Application Protection level to High (isolated). Select the Directory Security tab. Select the Edit button. Uncheck the Integrated Windows authentication box. Select the OK button. Select the Documents tab. Remove all entries in the Default Document box. Add an entry for index.html. Select the Apply button. Select the OK button.


6. Installing the Business Service

7. Fins