Chapter 1   Installation


Installing the iPlanet Portal Server Plug-in for the Identrus System requires a complete Portal Server Installation as a pre-requisite. This chapter runs through the installation procedure that then follows to enable users of the identrus system to use NetMail Lite. The chapter covers:

• Pre-requisites

• Installation procedure

• HSM Configuration

• Post Installation procedure

• Software Uninstallation

Pre-requisites

---

The following Software and hardware peripherals must be installed prior to installing the iPlanet Portal Server Plug-in for the Identrus System:

• iPlanet` Portal Server 3.0 SP2 and its email application NetMail Lite. e.g. http://www.iplanet.com/downloads/patches/2012.html

• iPlanet` Certificate Management Server (Optional) (See for instance http://www.iplanet.com/downloads/download/2042.html)

• A SmartCard, such as a credit card, which will be issued to you by a thirty party vendor. An Identrus compatible SmartCard is a mandatory requirement. iPlanet Portal Server Plugin for the Identrus Network V2.0 is currently compatible with the GemPlus SmartCards GemSAFE IS 16000. See http://www.gemplus.com/app/banking/gemsafe_is_mkt.htm

• A SmartCard Reader with browser plug-in, which will be issued to you by a third party vendor. An Identrus compatible SmartCard Reader is a mandatory requirement. iPlanet Portal Server Plugin for the Identrus Network V2.0 is currently compatible with the GemPlus Card Readers GemPC430 and GemPC410 see http://www.gemplus.com/products/hardware/index.htm

• GEMSafe Enterprise Workstation 1.0 software is compatible with iPlanet Portal Server Plugin for the Identrus Network V2.0 see http://www.gemplus.com/products/software/gemsafe/index.html

• The Netscape Navigator v4.7x or above. Internet Explorer 4.0 and Internet Explorer 5.0. These should be configured automatically with the software that comes with your SmartCard and SmartCard Reader.

• The Client browser is compatible with GemPlus SmartCard and the Portal Server Plug-in as such the following operating systems are supported: Windows NT 4.0 Service Pack 5 see http://www.microsoft.com/ntserver/nts/downloads/recommended/sp5/allsp5.asp or alternatively Windows 98 see http://www.microsoft.com/Windows98/

• The Hardware Security Module, CAFast (see http://www.ncipher.com), to accelerate cryptographic operations and securely store keys. This is an administrator requirement for Identrus member banks and does not require user intervention. Note CAFast is also referred to as nFast.

• In order to run iPlanet Portal Server Plug-in for the Identrus System you must have a relationship with a bank or an authority that is capable of acting as either an OCSP Responder or connected to the Identrus Network.

• Java 2 Standard Edition (1.2.2_06 Localized) Production Release for the Solaris Operating Environment. iPlanet Portal Server V3.0 consists of a Web Server and a Gateway (see http://docs.iplanet.com/docs/manuals/portal/30/install/overview.htm). The Gateway and the web server typically reside on separate machines. The gateway restricts access to the web server. The mere act of placing the gateway and web server on separate machines ensures that they will be running in separate VM's. Typical setup: (1) only the gateway can "see" the web server. (2) The gateway only has access to the web server and cannot see the same "world" as the web server. (3) Clients can only access facilities provided by the web server via the Gateway. (4) Clients cannot access the web server. If the gateway and server are put on separate machines then no pre-requisite is required since this is done during Portal installation and configuration. If the gateway and server are put on the same machine, e.g. for testing and development purposes, then the instructions below must be applied. (1) Download Java from http://www.sun.com/software/solaris/java/download.html (2) This should be installed separately on two different areas within the same machine. Under such circumstances, JAVA_HOME needs to be adjusted within the scripts ipsgateway and ipsserver to reflect this (for an example illustrating this see Chapter 4 Deploying Applications).

• Oracle 8.0.5 and JDBC` for Oracle 8.1.5 http://www.oracle.com/java/jdbc/html/jdbc.html

Installation procedure

---

You need to follow the guidelines defined in the iPlanet` Portal Server 3.0 Installation Guide. Before installing the iPlanet Portal Server Plug-in for the Identrus System, a fresh install of the Portal Server is required. Note the location of its installation, as this will be required when running the subsequent scripts:

• Login as root and from the shell prompt type the following:

  domainname

• If the above command returns nothing then type domainname <domain_name>. For example

  domainname uk.sun.com

• Go to the root directory of the installation CD- rom for example:

  cd /dev/cdrom

• The portal server must be running (See the iPlanet portal Server Documentation for details).

• Execute the installation script by typing the following command:

  ./ipspininstall

• If you have installed the Portal Server in the default location /opt then you can accept the defaults for the iPlanet Portal Server Plug-in for the Identrus System installation. Otherwise you must supply the location of the portal server installation and iPlanet Web Server Installation.

• The figure below illustrates a typical installation.

Figure 1-1    Example Installation Script

• As detailed in the prerequisite section of this document you must obtain the Oracle JDBC Drivers (typically oracle-jdbc-815.zip). Place this file into the following location.

  <portal_install_directory>/SUNWips/lib

• Set the classpath in the Portal Web Server directory by editing the file (to reflect Oracle filename oracle-jdbc-815.zip ):

  /opt/netscape/server4/https-hailstorm/config/jvm12.conf

• Ensure you have database access, taking note of the login id's and configuration. Then to set up the tables required by the portal server plug-in you will also need to run the SQL script

  <portal_install_directory>/SUNWpin/sql/OracleCertStore.sql

• You can also remove tables and data using the script:

  <portal_install_directory>/SUNWpin/sql/Drop_OracleCertStore.sql

• Your iPlanet Portal Server Plug-in for the Identrus System has now been successfully installed. Please consult the Post Installation section on how to start and stop the Portal Server (see section headed "Post Installation procedure").

• You can verify the installation by running the Sample CSC program from your browser. See the section headed "Running the sample program"

• Please consult the next section for details on HSM Configuration.

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 Portal 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 Portal 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 Portal Server Plug-in for the Identrus System (see "Administrator Login Procedure")

• 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 Portal Server Plug-in

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

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

• Configuring the iPlanet Portal Server Plug-in 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. If the .netscape directory does not exist, create it

  <portal_install_directory>/https-<servername>/config/.netscape

• If the file secmod.db does not exist in the .netscape directory create it as follows:

  <portal_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

  <portal_install_directory>/bin/https/admin/bin/modutil -dbdir . -nocertdb -add <moduleName> -libfile <vendorPKCS#11Library> -mechanisms RSA:DSA

• Check that the module was installed using

  <portal_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 Portal Server Plug-in to use a PKCS#11 token

• If the iPlanet Portal 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 Portal Server Plug-in will use the HSM for key generation and storage

• If the iPlanet Portal 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

• Change directory to

  cd <portal_install_directory>/lib

• remove any existing directory named jssconfig

  rm -rf jssconfig

• Unpack the jssconfig.tar archive

  tar xvf jssconfig.tar

• Edit the file

  <portal_install_directory>/lib/jssconfig/trustbase/security/jsstok enkeystore

• Change the key.token property line contained therein thus:

  key.token=<tokenName>

• Save the file, leaving other lines untouched

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

Post Installation procedure

---

After ensuring you have followed the installation and HSM configuration steps, the Portal Server must be shut down and restarted. Please ensure you start and stop the Portal Server using the specially installed plug-in scripts:

<portal_install_directory>/SUNWips/bin/SUNWpinStart <portal_install_directory>/SUNWips/bin/SUNWpinStop

---

Note	This does not start the gateway. This is normally achieved by typing the following commands:

---

<portal_install_directory>/SUNWips/bin/ipsgateway start <portal_install_directory>/SUNWips/bin/ipsgateway stop

However Please refer to the Portal Server Documentation for details on how to start and stop the Portal gateway.

http://docs.iplanet.com/docs/manuals/portal/30/install/server_i.htm

Software Uninstallation

---

To remove the iPlanet Portal Server Plug-in for the Identrus System but maintain the Portal Server installation perform the following steps:

• Ensure the Portal Server is running

• Login as root

• Execute the following command

  pkgrm SUNWpinsdskss

• Shut down and restart the Portal Server. Consult the Portal Server documentation to do this.

To remove iPlanet Portal Server consult

http://docs.iplanet.com/docs/manuals/portal/30/install