Previous     Contents     DocHome     Index     Next     
iPlanet Web Server: Plug-in for Trustbase services 1.0 Installation, Configuration and Developer's Guide



Chapter 2   Installation


The plugin for the iplanet webserver comes in two pieces. The first piece of the plugin is termed the "Authentication Servlet". This piece's role is to perform the certificate status check that is the basis of the authentication scheme for the plugin. If the certificate status check is completed with satisfactory results a cookie is generated by the servlet and given to the browser. The second piece of the plugin is termed the "Cookie Authorisation". The role of this piece is to check that cookie's submitted as passports to secured area's of the webserver are deemed "valid". Thus the Authentication servlet performs the authentication task and the cookie authorisation performs the authorisation role. Finally there is a DSMS Java API library should you wish to integrate with existing systems. This document will detail how to install and configure both sections of the plugin.


Pre-requisites


The following Software and hardware peripherals must be installed prior to installing the iPlanet Web Server: Plug-in for Trustbase services:


HSM Configuration

HSMs are accessed through the PKCS#11 libraries shipped by HSM vendors. In order to use an HSM, the HSM must first be correctly configured for PKCS#11 operation, and then the iPlanet Web Server Plug-in must be configured to recognise the HSM.


Configuring the HSM

An HSM should be configured according to its vendor's instructions. A brief description of the process for nCipher HSMs is provided here, along with a reference to the vendor documentation


Configuring an nCipher HSM

  • Refer to the nCipher documentation for definition of terms and further instructions on Security Worlds and Operator Card Sets: Chapters 6 and 7 of the document found at http://active.ncipher.com/documentation/PKCS11/solaris-4.01/nforce.pdf are particularly enlightening

  • Install the nCipher PKCS #11 library usually into:
    /opt/nfast

  • The iPlanet Web Server Plug-in requires a 1 of N Operator Card Set to use an nCipher HSM in PKCS#11 mode. One Operator Card is required for each module in the HSM. Create such an Operator Card Set as specified in the nCipher documentation. The password used must be the same as the password configured in iPlanet Web Server: Plug-in for Trustbase services.

  • Create a new text file cknfastrc in the directory in which you installed the nCipher software, usually /opt/nfast, and add the lines:
    CKNFAST_NO_UNWRAP=1
    CKNFAST_LOADSHARING=1
    CKNFAST_NO_ACCELERATOR_SLOTS=1

    export CKNFAST_NO_UNWRAP CKNFAST_LOADSHARING CKNFAST_NO_ACCELERATOR_SLOTS

  • Check the installation using
    /opt/nfast/bin/ckcheckinst

  • In the following sections, where the vendor PKCS#11 library is referred to, take that reference to mean
    /opt/nfast/gcc/lib/libcknfast.so

  • Additionally, the name of the PKCS#11 token upon which private keys will be generated and stored is the name of the Operator Card Set created for use with the nCipher PKCS#11 interface


Configuring the iPlanet Web Server Plug-in

There are two steps to be taken in configuring the iPlanet Web Server Plug-in:

  • Identifying the HSM vendor's PKCS#11 library to the Plug-in PKCS#11 cryptographic services

  • Configuring the iPlanet Web Server: Plug-in for Trustbase services to use the HSM based PKCS#11 tokens for key storage. This may be done as part of the installation procedure, but the manual operation is detailed here to permit an HSM to be installed after installation


Identifying the vendor PKCS#11 libraries

  • Change to the directory.
    <iws_install_directory>/https-<servername_instance>/alias

  • If the file secmod.db does not exist in the alias directory create it as follows:
    <iws_install_directory>/bin/https/admin/bin/modutil
      -dbdir . -nocertdb -create

  • If modutil created a secmodule.db rather than a secmod.db, move the file
    mv secmodule.db secmod.db

  • Add the vendor PKCS#11 library to the database of PKCS#11 modules, using an appropriate module name, e.g. nFast for an nCipher nFast module
    <iws_install_directory>/bin/https/admin/bin/modutil
    -dbdir . -nocertdb
    -add <moduleName>
    -libfile <vendorPKCS#11Library>
    -mechanisms RSA:DSA

  • Check that the module was installed using
    <iws_install_directory>/bin/https/admin/bin/modutil
    -dbdir . -nocertdb -list

  • The output should look something like this
    Using database directory ....
    Listing of PKCS #11 Modules
    Listing of PKCS #11 Modules
    -----------------------------------------------------------
    1.<moduleName>
    library name: <vendorPKCS#11Library>
    slots: # slots attached
    status: loaded
    slot: ####-####-####-#
    token: <tokenName>
    slot: ####-####-####-#
    token: <anotherTokenName>
    ...
    2. Netscape Internal PKCS #11 Module
    slots: 2 slots attached
    status: loaded
    slot: Communicator Internal Cryptographic Services Version 4.0
    token: Communicator Generic Crypto Svcs
    slot: Communicator User Private Key and Certificate Services
    token: Communicator Certificate DB
    ----------------------------------------------------------


Configuring the iPlanet Web Server Plug-in to use a PKCS#11 token

  • If the iPlanet Web Server Plug-in was configured at install time to use a PKCS#11 token, and the correct token name was chosen, then no further steps need be taken, and the Web Server Plug-in will use the HSM for key generation and storage

  • If the iPlanet Web Server Plug-in was not installed to use a specific PKCS#11 token, or the token name was specified incorrectly, then these actions should be followed.

  • This process must be performed after plug-in installation but before certificate application.

  • For iWS4.1 Change directory to
    cd <iws_install_directory>/docs/servlet

  • for iWS6.0 Change Directory to

    cd <iwstps_install_directory>/WEB-INF/lib

  • Edit the file
    ../jssconfig/trustbase/security/jsstokenkeystore

  • Change the key.token property line contained therein thus:
    key.token=<tokenName>

  • Save the file, leaving other lines untouched

  • Restart the iPlanet Web Server, which is now configured to use the PKCS#11 token with the given name for key generation and storage operations


Preparing to Configure Your Web Server

For adminstrative convenience, you can install more than one Webserver instance. You should consult the WebServer guide on how to do this:

Under such circumstances all other steps of the installation procedure would need to be repeated for each instance.

Figure 2-1    Configuring more than one Web Server Instance


Certificate Overview

Three kinds of certificates are needed for the Identrus Scheme:

  1. Application Authorisation Certificates

    • Relying Participant Certificate[C5]. This is normally the Relying Participant Bank. This certificate is used for Verification purposes.

    • Identrus Root Certificate[C4]. This is normally the Identrus root itself and under such circumstances any Identrus member running applications under the Web Server can be validated.

  2. Certificates for Certificate Status Checks

    • The Signing Certificate [C3]- This certificate is used by the webserver plugin to sign all its identrus transactions to the authoritative entity. During installation you will need to give this certificate a nick name.

  3. Certificates for Transport Authentication and Integrity

    •    The SSL Server Certificate [C1]- This is the certificate that is used by the webserver as its server certificate. It offers this certificate to clients wishing to make SSL Connections. This certificate is not given a nick name by you during the installation process because the webserver will name it - The name it uses by default is "Server-Cert".

    •    The SSL Client Certificate [C2]- This certificate is used by the webserver plugin to make SSL connections with the bank or other authoritative entity. During installation you will need to give this certificate a nick name.


Web Server Configuration Overview

The steps required to get the webserver ready for installation of the plugin are as follows :

  1. Install the webserver. You may use the in built JDK of the webserver. If you want to use the plugin to authorise users during login and not just as a DSMS you will need to provide the webserver with a directory server. This directory server can either be registered at installation time or later in the "Global Settings" Tab of the administration server.

  2. Initialise the Trust Database - This can be accomplished by starting on the "Servers" Tab of the administration server and clicking manage on your server. Then by clicking on the "Security" Tab for your server. Then by clicking the "Create Database" button and entering the password you want to give the database. Take Note Of This Password You Will Need It Later.

  3. Change the Database access permission's - This is required because the database is created by the administration server which is normally run as root and the database is accessed by the webserver instance which is normally run as nobody. Thus you need to change the access permissions. The Database files are stored in a directory underneath the webserver install directory called alias. Change the permissions to read/write/execute for everyone on all the files.

  4. Apply For Your Certificates - You need to apply for three Certificates for your webserver, these certificates are an SSLServer certificate , and SSLClient Certificate , and an Object Signing Certificate. Each certificate should be requested by using the "Request Certificate" button on the same page as the "Create Database" button. For Each certificate you must fill in the required details the "Key Pair File Password" is the password you noted in step 2.

  5. Install Your Certificates - You need to add the certificates you have applied for into the database. Once you have the PEM format replies to your requests, you can use the "Install Certificate" button which is on the same page as the "Request Certificate" button. All three certificates you received should be entered with the type "This Server" , the "Key Pair File Password" is the password you noted in step 2. The first certificate - The SSLServer certificate should not be given a name in the "Certificate name" field. However the other two certificates should be given individual names.


    Note Make a note of these names. You will need them later


    I

  6. Install the Identrus Chain Certificates - You need to add the certificates that complete the trust chain between the certificates you requested and the Identrus Root. You must install all the certificates including the Identrus Root. You can do this using the same page "Install Certificate" youwill need to use the type "Trusted Certificate Authority".

  7. Secure Your Webserver - By enabling SSL and configuring it to require a client certificate. This can be accomplished by starting on the "Servers" Tab of the administration server and clicking manage on your server. Then by clicking the "Preferences" Tab of your webserver. Then by clicking the "Encryption On/Off button", You can then select encryption on and save your changes. Now Click on the "Encryption Preferences" button and enable "Require Client Certificate".

  8. You need to add a client certificate for DSMSDemo


Configuring iPlanet Web Server

The Web server must be installed and running

  1. (See the iPlanet Web Server Documentation for details on how to install .

    1. iWS 4.1

http://docs.iplanet.com/docs/manuals/fasttrak/41/ig/contents.htm

    1. iWS 6.0

http://docs.iplanet.com/docs/manuals/enterprise/50/ig/contents.htm

  1. We now Illustrate this for iWS4.1. The steps for iWS 6.0 are similar. To Configure Securely:

    1. Open the Admin Web Server at http://hailstorm.uk.sun.com:4444

Figure 2-2   

Opening the Administrator Web Server Screen

    1. Select <manage>



    2. Select security

    3. choose a password and select ok



    4. Select <Manage Certificates>

    5. Select <request certificate>

Figure 2-3   

Request Server Certificate

    1. fill in form and collect request

    2. Give it to your BankCA who will send you a PEM format response

    3. Select <Install Certificate>

Figure 2-4    Install Server Certificate

    1. Select <this Server> for [C1],[C2],[C3] <Trusted Certificate Authority> for [C4] and [C5]

    2. Select <Message text>

    3. Select <Add Certificate>

Figure 2-5   

Add Server Certificate

    1. Repeat for all three certs [C1,C2, C3]

    2. Add Identrus Root Certificate from your CA[C4]

    3. Add RPCA from your CA [C5]

    4. To check that all certificates are present and correct

      • Select <Security>

      • Select <Manage Certificates>

    5. To Secure your Webserver

    6. Select <preferences>

    7. select <encryption on/off>

    8. Select <on>

Figure 2-6   

Set Encyption

    1. Select <ok> followed by <Save Changes>

    2. Select <encryption preferences>

Figure 2-7   

Encryption Settings

    1. Select <Require Client Certificate> = "Yes"

    2. Select <ok><Save Change>

    3. Start the server up again

    4. the server should now be secure

    5. Type https://hailstorm.uk.sun.com:4445 to verify

    6. You may need to get a SSL Client cert for the RPCA [C5]


Installing the Plug-in

You will have been provided with a single compressed tar file which contains the installation of the plugin. The compressed tar file which is normally called iwstps.tar.Z should be copied to a directory of your choice and then unpacked. If you are using the c-shell an example as to how unpack the compressed tar file would be :


gzip -c -d iwstps-1.0.tar.gz | ( mkdir iwstps; cd iwtps ; tar xvf - )


Once you have unpacked the distribution it will have created several directories below the one you are currently in. The scripts directory contains the install scripts and data they need. The errors directory contains html files that the plugin will use when in operation. It also contains an applet that performs some of the required smart card interactions. The bin and lib directories contain the actual program code that represent the plugin.

Figure 2-8    Example Unzipped iwspts directory for iWS4.1



iWS 4.1 Plug-in for Trustbase Services Installation Overview

Before installing the plugin you should have several pieces of information that it will require ready to hand. The information that the plugin will need is as follows. It should be noted that the defaults that are named for explanatory purposes and are not used by the install process.


  • The webserver install directory This is the full path to the webserver install directory. This directory is by default /usr/netscape/server4. The directory should contain the startconsole program and several subdirectories.

  • The webserver label name : This is the full label name you have given to the instance of the webserver you want to install the plugin for. The label name is typically https-machine-domainname so it may look something like https-ragnarok-uk.sun.com.

  • The full path to the webserver documents directory : This should be the full pathname to the webserver instance's documents directory. This is by default /usr/netscape/server4/docs.

  • The full path to the webserver servlet directory : This should the full pathname to the webserver instance's servlet directory. This is by default /usr/netscape/server4/docs/servlet. Although it is important to note that this directory is not created when you install the webserver.

  • The keystore password : This is the password you gave when you created the keystore database.

  • The nick name of your server's signing certificate : This is the nick name of the certificate you wish the webserver to use when signing outgoing identrus transactions. This will be the nick name of the certificate you requested for object signing.

  • The nick name of your server's SSL Signing certificate : This is the nick name of the certificate you wish the webserver to use when connecting as a client in SSL connections. This will be the nick name of the certificate you requested for SSL client usage.

  • The domain within which the server operates : This is for the authorisation system - it controls how wide the domain for the cookie authorisation is and it must be wide enough to include this host. Thus it must be at least one step above this host , eg if your host is called blizzard.uk.sun.com the domain must be at least uk.sun.com or wider.

  • The nick name of the verification certificate : This is the nick name of the certificate you wish to use as an authoritative root certificate or "Trust Anchor". In this case the Identrus Root.

  • The following LDAP settings, obtained from <Global Settings>

    • The fully qualified hostname of your LDAP database server : This is the hostname and domain name of the machine that has the LDAP database that store the user profiles that the webserver uses.

    • The port number that your LDAP database is running on : This is the port number that the LDAP database is listening on.

    • The Base DN of your LDAP Database : This is the base DN for user searches of your LDAP database.


iWS 6.0 Plug-in for Trustbase Services Installation Overview

Before installing the plugin you should have several pieces of information that it will require ready to hand. The information that the plugin will need is as follows. It should be noted that the defaults that are named for explanatory purposes and are not used by the install process.


  • The webserver install directory This is the full path to the webserver install directory. This directory is by default /usr/netscape/server4. The directory should contain the startconsole program and several subdirectories.

  • The webserver instance name : This is the name of the instance of the webserver you wish to install the plug-in for. By default this is <machine_name>.<domain_name>

  • The Deployment Directory : This is the full path tothe directory you wish to employ the plug-in application to.

  • The Virtual Server Name : Allows you to serve different domains with the same Web Server. This, by default, would be the https-<instance-name>

  • The keystore password : This is the password you gave when you created the keystore database.

  • The nick name of your server's signing certificate : This is the nick name of the certificate you wish the webserver to use when signing outgoing identrus transactions. This will be the nick name of the certificate you requested for object signing.

  • The nick name of your server's SSL Signing certificate : This is the nick name of the certificate you wish the webserver to use when connecting as a client in SSL connections. This will be the nick name of the certificate you requested for SSL client usage.

  • The domain within which the server operates : This is for the authorisation system - it controls how wide the domain for the cookie authorisation is and it must be wide enough to include this host. Thus it must be at least one step above this host , eg if your host is called blizzard.uk.sun.com the domain must be at least uk.sun.com or wider.

  • The nick name of the verification certificate : This is the nick name of the certificate you wish to use as an authoritative root certificate or "Trust Anchor". In this case the Identrus Root.

  • The following LDAP settings, obtained from <Global Settings>

    • The fully qualified hostname of your LDAP database server : This is the hostname and domain name of the machine that has the LDAP database that store the user profiles that the webserver uses.

    • The port number that your LDAP database is running on : This is the port number that the LDAP database is listening on.

    • The Base DN of your LDAP Database : This is the base DN for user searches of your LDAP database.


Performing the iWS4.1 Plug-in for Trustbase Services Installation

Once you have gathered all the information you are ready to proceed with the installation. Inside the scripts directory you unpacked earlier there is a script called "install". If you run this script it will ask you all the questions detailed above. Once the questions have been answered the script will proceed to copy all the binaries required and change the configuration files for the plugin's operation. Example of what might happen during installation is shown below. Bold type is used to indicate user typed instructions. In the cases where nothing appears to be typed by user it means the user just pressed return and accepted the proposed default.

ragnarok# cd <install_dir>/iwspts/build/scripts

ragnarok# ./install

Where is your iPlanet WebServer installation located?

/iplanet/webserver3/server4

What is the instance of your WebServer eg https-ragnarok-PKI ?

https-ragnarok.UK.Sun.COM

What is the full path to the documents directory you wish to use ? [ /iplanet/webserver3/server4/docs ] /iplanet/webserver3/server4/docs

What is the full path to the servlet directory you wish to use ? [ /iplanet/webserver3/server4/docs/servlet ]

What is your keystore password ? password

What is the domain name within which this webserver operates ?

uk.sun.com

What is the nick name server's signing cert ? [ Server-Cert ]

What is the nick name server's SSL signing cert ? [ Server-Cert ]

What is the nick name of the cert you wish to verify responses with ? Identrus Root (Development)

What is the fully qualified hostname of your LDAP database server ? ragnarok.uk.sun.com

What is the port number of your LDAP database server ?

10000

What is the base DN of your LDAP database ? o=sun.com

These are the parameters that you input

[1] The server location is [ /iplanet/webserver3/server4 ]

[2] The server label is [ https-ragnarok.UK.Sun.COM ]

[3] The documents path is [ /iplanet/webserver3/server4/docs ]

[4] The servlet path is [ /iplanet/webserver3/server4/docs/servlet ]

[5] The keystore password is [ password ]

[6] The signing certificate nick name is [ Server-Cert ]

[7] The SSL signing certificate nick name is [ Server-Cert ]

[8] The domain name within which this webserver operates [ uk.sun.com ]

[9] The verification certificate nick name is [ Identrus Root (Development) ]

[10] The hostname of your LDAP database server is [ ragnarok.uk.sun.com ]

[11] The port number of your LDAP database server is [ 10000 ]

[12] The base DN of your LDAP datbase is [ o=sun.com ]

if these are acceptable hit [0] otherwise hit the number of the parameter you wish to change or hit [e] to leave the installation

0

domain name - niscafe.uk.sun.com host name - ragnarok when you wish to install the cookiechecker shared object please add the contents of the file /iplanet/webserver3/server4/https-ragnarok.UK.Sun.COM/config/obj .conf.cookie to the /iplanet/webserver3/server4/https-ragnarok.UK.Sun.COM/config/obj .conf file


Performing the iWS 6.0 plug-in for Trustbase Services installation

Where is your iPlanet WebServer installation located?

/iplanet/webserver6.FCS/server6

What is the name of the instance your WebServer instance ?

ragnarok.uk.sun.com

What is the instance's virtual server called ? [ default ]

What is the full path to the directory you wish to deploy the application to ? [ /iplanet/webserver6.FCS/server6/deploy ]

What is your keystore password ?

password

What is the domain name within which this webserver operates ?

uk.sun.com

What is the nick name server's signing cert ? [ Server-Cert ]

What is the nick name server's SSL signing cert ? [ Server-Cert ]

What is the nick name of the cert you wish to verify responses with ?

Identrus Root (Development)

What is the fully qualified hostname of your LDAP database server ? [ ragnarok ]

What is the port number of your LDAP database server ? [ 389 ]

10000

What is the base DN of your LDAP database ?

o=sun.com

These are the parameters that you input

[1] The server location is [ /iplanet/webserver6.FCS/server6 ]

[2] The server instance is [ ragnarok.uk.sun.com ]

[3] The virtual server id is [ https-ragnarok.uk.sun.com ]

[4] The deployment directory [ /iplanet/webserver6.FCS/server6/deploy ]

[5] The keystore password is [ password ]

[6] The signing certificate nick name is [ Server-Cert ]

[7] The SSL signing certificate nick name is [ Server-Cert ]

[8] The domain name within which this webserver operates [ uk.sun.com ]

[9] The verification certificate nick name is [ Identrus Root (Development) ]

[10] The hostname of your LDAP database server is [ ragnarok ]

[11] The port number of your LDAP database server is [ 10000 ]

[12] The base DN of your LDAP datbase is [ o=sun.com ]

if these are acceptable hit [0] otherwise hit the number of the parameter you wish to change or hit [e] to leave the installation

0

The directory /iplanet/webserver6.FCS/server6/deploy does not exist

Do you want to create it ?

y

Creating directory

/iplanet/webserver6.FCS/server6/deploy

domain name - uk.sun.com

host name - ragnarok

Web application deploy successful

when you wish to install the cookiechecker shared object please add the contents of the file /iplanet/webserver6.FCS/server6/https-ragnarok.uk.sun.com/config /obj.conf.cookie to the /iplanet/webserver6.FCS/server6/https-ragnarok.uk.sun.com/config /obj.conf file


Activating the Identrus Login Protection (iWS 4.1)

You cannot utilise the identrus login protection system without having a user community ldap database. In order to protect an area of the webserver from access through an identrus certificate status check you need to take a few final steps in configuration. First you need to add the lines that have been written to the file obj.conf.cookie to your obj.conf file. These files are located in the webserver instance's config directory which is determined by combining the install directory with the instance label. Which in the install example above would be /iplanet/webserver3/server4/https-ragnarok.UK.Sun.COM/config. The lines with the first word as "Init" should be placed after the last Init line and the line with "PathCheck" should be placed before the first "PathCheck" line. An example altered file follows with the lines in question highlighted.


# Sun Netscape Alliance - obj.conf

# You can edit this file, but comments and formatting changes

# might be lost when the admin server makes changes.

Init fn="flex-init" access="/iplanet/webserver3/server4/https-ragnarok.UK.Sun.COM/lo gs/access" format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"

Init fn="load-types" mime-types="mime.types"

Init fn="load-modules" shlib="/iplanet/webserver3/server4/bin/https/lib/libNSServletPlu gin.so" funcs="NSServletEarlyInit,NSServletLateInit,NSServletNameTrans,N SServletService" shlib_flags="(global|now)"

Init fn="NSServletEarlyInit" EarlyInit="yes"

Init fn="NSServletLateInit" LateInit="yes"

**----> Init fn="load-modules" funcs="identrus-cookie-init" shlib="/iplanet/webserver3/server4/bin/https/lib/cookiechecker.so"

**-----> Init fn="acl-register-module" module="identrus" func="identrus-cookie-init"

<Object name="default">

NameTrans fn="NSServletNameTrans" name="servlet"

NameTrans fn="pfx2dir" from="/servlet" dir="/iplanet/webserver3/server4/docs/servlet" name="ServletByExt"

NameTrans fn="pfx2dir" from="/ns-icons" dir="/iplanet/webserver3/server4/ns-icons" name="es-internal"

NameTrans fn="pfx2dir" from="/mc-icons" dir="/iplanet/webserver3/server4/ns-icons" name="es-internal"

NameTrans fn="pfx2dir" from="/help" dir="/iplanet/webserver3/server4/manual/https/ug" name="es-internal"

NameTrans fn="pfx2dir" from="/manual" dir="/iplanet/webserver3/server4/manual/https" name="es-internal"

NameTrans fn="document-root" root="/iplanet/webserver3/server4/docs"

**---->PathCheck fn="get-client-cert" dorequest="1"

PathCheck fn="unix-uri-clean"

PathCheck fn="check-acl" acl="default"

PathCheck fn="find-pathinfo"

PathCheck fn="find-index" index-names="index.html,home.html"

ObjectType fn="type-by-extension"

ObjectType fn="force-type" type="text/plain"

Service method="(GET|HEAD)" type="magnus-internal/imagemap" fn="imagemap"

Service method="(GET|HEAD)" type="magnus-internal/directory" fn="index-common"

Service fn="NSServletService" type="magnus-internal/jsp"

Service method="(GET|HEAD)" type="*~magnus-internal/*" fn="send-file"

AddLog fn="flex-log" name="access"

</Object>

<Object name="cgi">

ObjectType fn="force-type" type="magnus-internal/cgi"

Service fn="send-cgi"

</Object>

<Object name="servlet">

ObjectType fn="force-type" type="text/html"

Service fn="NSServletService"

</Object>

<Object name="jsp092">

ObjectType fn="type-by-extension"

ObjectType fn="change-type" type="magnus-internal/jsp092" if-type="magnus-internal/jsp"

Service fn="NSServletService" type="magnus-internal/jsp092"

</Object>

<Object name="ServletByExt">

ObjectType fn="force-type" type="magnus-internal/servlet"

Service type="magnus-internal/servlet" fn="NSServletService"

</Object>

<Object name="es-internal">

PathCheck fn="check-acl" acl="es-internal"

</Object>

<Object name="jsp">

Service fn="NSServletService"

</Object>


Activating the Identrus Login Protection (iWS 6.0)

Two files need to be edited


obj.conf

NameTrans fn="pfx2dir" from="/servlet" dir="/iplanet/webserver6.CPI/server6/docs/servlet" name="ServletByExt"

NameTrans fn="pfx2dir" from="/jsp.092" dir="/iplanet/webserver6.CPI/server6/docs/jsp.092" name="jsp092"

NameTrans fn=pfx2dir from=/mc-icons dir="/iplanet/webserver6.CPI/server6/ns-icons" name="es-internal"

NameTrans fn="pfx2dir" from="/manual" dir="/iplanet/webserver6.CPI/server6/manual/https" name="es-internal"

NameTrans fn=document-root root="$docroot"

**---->PathCheck fn="get-client-cert" dorequest="1"

PathCheck fn=unix-uri-clean

PathCheck fn="check-acl" acl="default"

PathCheck fn=find-pathinfo

PathCheck fn=find-index index-names="index.html,home.html"

ObjectType fn=type-by-extension

ObjectType fn=force-type type=text/plain

Service type="magnus-internal/jsp" fn="NSServletService"

Service method=(GET|HEAD) type=magnus-internal/imagemap fn=imagemap

Service method=(GET|HEAD) type=magnus-internal/directory fn=index-common

Service method=(GET|HEAD) type=*~magnus-internal/* fn=send-file

AddLog fn=flex-log name="access"

</Object>

<Object name=cgi>

ObjectType fn=force-type type=magnus-internal/cgi

Service fn=send-cgi user="$user" group="$group" chroot="$chroot" dir="$dir" nice="$nice"

</Object>

<Object name="servlet">

ObjectType fn=force-type type=text/html

Service fn="NSServletService"

</Object>

<Object name="jsp092">

ObjectType fn="type-by-extension"

ObjectType fn="change-type" type="magnus-internal/jsp092" if-type="magnus-internal/jsp"

Service fn="NSServletService" type="magnus-internal/jsp092"

</Object>

<Object name="ServletByExt">

ObjectType fn=force-type type=magnus-internal/servlet

Service type="magnus-internal/servlet" fn="NSServletService"

</Object>

<Object name="es-internal">

PathCheck fn="check-acl" acl="es-internal"

</Object>

magnus.conf

#ServerRoot /iplanet/webserver6.CPI/server6/https-ragnarok.uk.sun.com

ServerID https-ragnarok.uk.sun.com

ServerName ragnarok.uk.sun.com

ErrorLog /iplanet/webserver6.CPI/server6/https-ragnarok.uk.sun.com/logs/e rrors

PidLog /iplanet/webserver6.CPI/server6/https-ragnarok.uk.sun.com/logs/p id

User nobody

MtaHost localhost

DNS off

Security off

ClientLanguage en

AdminLanguage en

DefaultLanguage en

RqThrottle 128

StackSize 131072

CGIWaitPid on

TempDir /tmp/https-ragnarok.uk.sun.com-8e0cef20

Init fn=flex-init access="$accesslog" format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"

Init fn=load-types mime-types=mime.types

Init fn="load-modules" shlib="/iplanet/webserver6.CPI/server6/bin/https/lib/libNSServle tPlugin.so" funcs="NSServletEarlyInit,NSServletLateInit,NSServletNameTrans,N SServletService" shlib_flags="(global|now)"

Init fn="NSServletEarlyInit" EarlyInit=yes

Init fn="NSServletLateInit" LateInit=yes

**---->Init fn="load-modules" funcs="identrus-cookie-init" shlib="/iplanet/webserver4.1SP1.FCS/server4/bin/https/lib/cookiechecker.so"

**---->Init fn="acl-register-module" module="identrus" func="identrus-cookie-init"


Protecting An Area Using Identrus Method.

Now that you have completed the installation of the "Identrus" access control method you can use it just like any other access control method. Using access control methods is well detailed in the webserver administrators guide See for instance

Here is an overview of the main steps found in the iWS Administration Guides:

  1. Access The administration server screens and <Manage> Your webserver.

  2. Click on the <Restrict Access> button on the administration screen which in the lower left hand corner of the screen.

Figure 2-9    Custom Error Page

  1. Click the browse button on the <Pick A Resource> section and select the area of the webserver you wish to protect.

  2. Then click the <Edit Access Control Button>.

  3. Create your Access Control List - in the user/group field if you click on the <anyone> field a requestor will appear - in that requestor you can choose which users and groups to protect from or allow, you can also specify the authentication which in this case is "identrus".

  4. Also when protecting an area you must use a custom error page installed by the plugin called /errors/certificate.html as illustrated on the previous page.


Configuring Identrus with LDAP

When using the "identrus" security method the LDAP user community database is consulted to check for the existence of the user that is trying to login. Furthermore the user's entry is checked to see if it contains the identity certificate that was submitted during the login phase. If the identity certificate is not present in the LDAP record then the user is not allowed to login to the system. In a default installation the user's identity certificate must be placed in the "usersmimecertificate" element in the record. However you can change this element by altering the "authservlet.properties" file. The section you need to alter is the DataProvider Section and the entry is:

LdapDatabase.Property=CertificiateElement=usersmimecertificate

If the entry is not already present then just add it with whatever value for "usersmimecertificate" you require.

The location of the authservlet.properties is different on iWS 4.1 and iWS 6.0 -

iWS 4.1 :

<iws_install_dir>/https-<instance_name>/config.

iWS 6.0 :

<iwstps_install_dir>/config.


What happens during Installation (iWS 4.1)

The install script copies files to the relevant directories within the Web Server. How this is done can be found in:

<install_directory>/build/scripts/install


Binaries.

The binaries are copied into the required locations. This means that the jar files are copied into to the servlet directory you selected during your installation. The shared libraries including the custom Access Control library - the "Cookie Authorisation" are copied in the bin/https/lib directory under your webservers install directory that you indicated during the install.


Text and resources

The html files , associated images and smart card applets are copied into the documents directory that you specified during your installation - they are all placed underneath an errors subdirectory.



Web Server Configuration Files


The webserver configuration files are created or altered as required they all reside in the webserver instance's config directory. The webserver instance directory is created by combining the webserver install directory that you specified on installation with webserver instance label that you also specified during installation. The files that are involved are :

authservlet.properties : This file controls the authentication servlet behaviour and the cookie authorisation shared object behaviour. The settings inside this file are detailed in the configuration section of this document.

jvm12.conf : This file controls the jvm configuration that runs the servlet engine. The classpath must be changed in order to place the servlet and other associated classes onto it. Do not try to change teh classpath from the Configuration Screen <Configure JVM Attributes>. Make these changes directlry to the file jvm12.conf.

servlet.properties This file controls the registration of servlet's on this instance of the webserver. This file is altered to register the adapter class for the authentication servlet. It is also altered to allow the authentication servlet to find the authservlet.properties file.

rules.properties This file controls registration of the virtual servlet paths. This file is altered to allow references to /AuthenticationServletAdapter. Because of the restrictions placed on the webserver JVM this servlet must operate through a virtual servlet path.

jsstokenkeystore.properties The JSS security system must also be configured. This means that the jarfile jssconfig is unpacked during installation - since this jarfile is located inside the servlet directory you specified during installation it will be placed on the classpath. The file jsstokenkeystore.properties which was part of the jar file is then altered to reflect the correct path to the webserver instances database. The full path to alter jsstokenkeystore.properties file is thus <servlet_directory>/jssconfig/trustbase/security/jsstokenkeystore.properties



What Happens During Installation (iWS 6.0)


The install script copies files to relevant directories , alters configuration files to suit the local configuration and deploy's the application using wdeploy. How this is done can be found at :

<install_directory>/build/scripts/install


  • Binaries ( Shared Objects ).

    The shared objects that are required for the plugin's operation are copied into the webserver's library directory <webserver_install_dir>/bin/https/lib this includes the replacement of the libnss3.so with the plugins own version. The current version of libnss3.so is backed up with the name libnss3.original.so.


  • Web Deployment.

    All text resources and java jar's are then placed in their appropriate places by using "wdeploy" - the plugin install script uses the webserver's own version.


  • Application Configuration.

    The application is then configured to the local specification. The configuration files for the application are stored in the <deployment_dir>/config directory. The application files that are altered are :

    Authservlet.properties : This file controls all aspects of the Authentication Process.

    Dsmsdemo.properties : This is the installation verification utility.

    Web-apps.xml : The web deployment file is altered so that the applications can find their configuration files.

    iWS 6.0 files that are altered are :

    Jvm12.conf : This controls the JVM of the webserver and it is altered to include the classes directory of the deployment.


Post Installation procedure

After ensuring you have followed the installation and HSM configuration steps, the Web Server must be shut down and restarted.


Software Reinstallation



iWS 4.1 Reinstall

  1. Consult

    http://docs.iplanet.com/docs/manuals/fasttrak/41/ig/unix.htm

  2. Remove all Web Server instances.

  3. Reinstall the Web Server and all its configured instances.

  4. Reinstall the Plugin


iWS 6.0 Reinstall

  1. Consult

    http://docs.iplanet.com/docs/manuals/enterprise/50/ig/unix.htm

    In this case it is possible to uninstall the iPlanet Web Server Plugin for Trustbase Services without removing all Web Server Instances. When the plugin is installed on iWS 6.0 it uses the answers to the questions you give at install time to configure the plugin but it actually uses "wdeploy" to deploy the application, this means that if you with to uninstall the plugin the simplest way is to use the wdeploy delete option. The uri that the application is deployed is /DSMS so an example of the command would be


    wdeploy delete -u /DSMS -i ragnarok.uk.sun.com -v https-ragnarok.uk.sun.com hard


    During installation the plugin also installs a copy of libnss3.so into the webserver's library directory, this can be replaced if you wish with the original copy that is left there - it is given the name libnss3.original.so. The library directory location is <webserver_install_dir>/bin/https/lib.


Verifying the Installation

Verifying an installation or configuration can be performed by:

  1. Placing a certificate in your database store so that the Demo can find the certificate to be checked

  2. Setting the classpath and running the Java servlet demo DSMSDemo.java

  3. Loading the DSMS Client Web page that instigates a DSMS Certificate Status check from the Identrus root.


Setting the Classpath (iWS 4.1)

The following shell script illustrates how to set the classpath

#!/bin/sh

# This script is provided for convenience as an example

# of how you might set up your environment for

# This script needs to be run from its directory location

# as the paths it sets depend on it being in a given place.

PATH_TO_LS=/bin/ls

PATH_TO_CAT=/bin/cat

PATH_TO_RM=/bin/rm

IWS_SERVER_HOME=/iplanet/webserver4.1SP1.FCS/server4

CURRENTDIR=`pwd`

LD_LIBRARY_PATH=$IWS_SERVER_HOME/bin/https/lib

$PATH_TO_LS $CURRENTDIR > /tmp/liblist

for x in `$PATH_TO_CAT /tmp/liblist`

do

CLASSPATH=$CLASSPATH:$CURRENTDIR/$x

done

$PATH_TO_RM /tmp/liblist

export CLASSPATH

export LD_LIBRARY_PATH


Setting the Classpath (iWS 6.0)

The following illustrate how to set the classpath

#!/bin/sh

# This script is provided for convenience as an example

# of how you might set up your environment for

# building and running tools dependant on the dsms

# This script needs to be run from its directory location

# as the paths it sets depend on it being in a given place.

PATH_TO_LS=/bin/ls

PATH_TO_CAT=/bin/cat

PATH_TO_RM=/bin/rm

IWS_SERVER_HOME=/iplanet/webserver6.CPI/server6

CURRENTDIR=`pwd`

LD_LIBRARY_PATH=$IWS_SERVER_HOME/bin/https/lib

$PATH_TO_LS $CURRENTDIR/WEB-INF/lib > /tmp/liblist

for x in `$PATH_TO_CAT /tmp/liblist`

do

CLASSPATH=$CLASSPATH:$CURRENTDIR/WEB-INF/lib/$x

done

CLASSPATH=$CURRENTDIR/WEB-INF/classes:$CLASSPATH

$PATH_TO_RM /tmp/liblist

export CLASSPATH

export LD_LIBRARY_PATH


Running the Demo Servlet

The following steps need to be followed to run the demo

  1. Put RPCA certificate that you wish to have checked in the database

  2. Create your own version of <install_directory>/build/example/DSMSDemo.sh and add the password the certificate purpose Id of the Identrus root, the SSL sigining certificate, the root RPCA and the Certificate name as illustrated below

    #!/bin/sh

    . ./cp.sh

    java com.iplanet.trustbase.identrus.dsms.DSMSDemo password Server-Cert\

    Server-Cert "Identrus Root (Development)" firestormcert


Running the Client Demo

  1. Load the Web Server by typing

    1. iWS4.1

    http://<machine_name>:<Port>/errors/dsmsdemo.html

    1. iWS6.0

    http://machine_name>;<Port>/DSMS/errors/dsmsdemo.html

Figure 2-10    Logon to the WebServer DSMSDemo

  1. CSC check should come back with the following message

Figure 2-11    CSC status check completed

The configuration of the Web Server insatnce that you have installed has now been verifyed.


Previous     Contents     DocHome     Index     Next     
Copyright © 2001 Sun Microsystems, Inc.

Last Updated September 24, 2001