Chapter 2   Architectural Configuration


iPlanet Trustbase Transaction Manager can be deployed over a variety of hardware configurations:

• It may be configured on single and clustered iPlanet Application Server installations

• It has a variety of configuration issues within the DMZ environment

• It can also be configured using Hardware Security Modules

iPlanet Application Server configuration

---

iPlanet Application Server may be used in a wide variety of configurations to support differing requirements for:

• Scalability

• Throughput

• Failover

The iPlanet Trustbase Transaction Manager has been designed to take advantage of these facilities and has been tested on two of the main configurations, these being:

• Single iPlanet Application Server

• Clustered iPlanet Application Servers

A single iPlanet Application Server is the most likely configuration option for low volume pre-operational Transaction Manager environment. This is considered a standard iPlanet Trustbase Transaction Manager installation and requires no specific configuration options other than those outlined in the iPlanet Application Server installation guide. The recommended settings for iPlanet Application Server are:

• Single KJS for each CPU on the host machine

• Minimum 8 and Maximum 64 Threads per KJS

The iPlanet Trustbase Transaction Manager is generally a CPU bound processing environment. This means that installing a greater number or faster CPU's will improve performance.

The iPlanet Trustbase Transaction Manager utilises Oracle databases extensively. Oracle itself is both CPU and disk intensive. If possible, Oracle should be located on a separate computer to the iPlanet Trustbase Transaction Manager installation.

Clustered iPlanet Application Server installations provide a means of improving Scalability, throughput and fail-over over a single iPlanet Application Server running the iPlanet Trustbase Transaction Manager. Prior to installing a clustered iPlanet Application Server the following items require consideration:

• Each Machine running iPlanet Application Server can have a nCipher HSM. This is a requirement for Identrus Compliance.

• A clustered iPlanet Application Server environment may provide slower response times in marginal loading conditions

  
  

  ---

  Note

  For further information about performance tuning and effective deployment consult: Oracle 8.1.7 Administrators Reference Manual Chapter 2 SQL tuning can also be found in the Oracle 8.1.7 programmers Guide Tuning Server Performance is discussed within the iPlanet Web Server 6.0 Administration Guide Application Deployment is discussed within the iPlanet Application Server 6.5 Administration and Deployment Guide

  ---

  
  

Using a DMZ

---

The general architectural model for deploying an iPlanet Trustbase Transaction Manager is to place the application server within a Demilitarised Zone (DMZ) created using a proxy machine between two firewalls. This configuration provides a means of ensuring that an outside user cannot directly access or modify the logic that forms the application in order to circumvent the authentication and authorisation requirements.

The DMZ primary firewall must offer two unauthorised open ports to support SSL access and SMTP access. These ports are generally:

• SSL - Port 443

• SMTP - Port 25

Behind this firewall is a single machine that runs the SSL proxy, the SMTP listener, and the iPlanet Web Server. The secondary firewall has three ports open configured for the DMZ machine only. These three ports are:

• iPlanet Application Server Directory Port 389

• iPlanet Web Server
  • HTTP - Port 80

  • Admin - Port 8888

• Oracle

  
  

  ---

  Note	Oracle uses many ports. Consult your Oracle DBA about this.

  ---

  
  

The HTTP port is used by the SSL and SMTP proxies to communicate to the iPlanet Web Server located behind the secondary firewall. Both the SSL and SMTP listeners use the Oracle port to store information about connections as well as receive their configuration. The architecture is shown below.

Figure 2-1    DMZ Architecture

Using this configuration the systems administrators may use the HTML based configuration screens without the need for SSL certificates. This does not circumvent the authentication mechanisms as the configuration management mechanisms are authenticated using a Username and Password based authentication mechanism.

---

Note	The default configuration is such that it all runs on one machine. When you install iPlanet Application Server 6.5 and iPlanet Web Server 6.0 it installs a directory server that has a default port of 389 and an administrator port of 8888.

---

Machine Installations

---

In some instances it may be necessary to install product component software on different machines. The following table summarises possible combinations:

Table 2-1    Acceptable Machine Installations

Product Component to be separated	Separate Machine Installation?	Considerations
iTTM separated from iAS	Not Possible	If iAS and iWS are installed on Separate machines make sure iTTM is installed with iAS
iWS separated from iAS	Yes	See Section on Configurator Plug-in http://docs.iplanet.com/docs/manuals/ias.html and also http://docs.sun.com/source/816-5788-10/app1.htm#13421 The webserver's documents directory must be made accessible by the iTTM installer. This accessibility only needs to be present when the installer is functioning ( i.e. it will need to be re-instated during upgrade or silent installs). When configuring URL rewrites magnus.conf and obj.conf need to be accessible to both machines
Oracle separated from iTTM	Yes	See Section on"Oracle Database Configuration," on page 79
SSL Proxy separated from iTTM	Yes	See Section "HTTP/HTTPS Proxy Implementation"
SMTP Proxy separated from iTTM	Yes	See "Configuring the SMTP Proxy Separately"
iAS with other Web Servers	Not Supported

HTTP/HTTPS Proxy Implementation

---

The standard out of the box configuration is illustrated in the diagram below. iTTM communicates directly with the outside world over an HTTP socket.

Figure 2-2    Standard iTTM installation

When the computer hosting the iTTM server has a direct connection to the outside world, malicious users may attack the server and gain access to its functionality. To prevent this, a firewall can be installed that blocks access except via a known channel (e.g. only HTTP inbound access on port 80). To provide a further level of protection, a proxy server may be implemented outside the firewall. This accepts and creates connections on behalf of the server, communicating over a channel that only it has access to.

Figure 2-3    Proxy with single firewall

A further layer of security may now be put in place by placing the proxy behind a second firewall. This has the effect of stopping the proxy from receiving unwanted requests.

Figure 2-4    Proxy with two firewalls

This has sometimes been referred to as a DMZ (demilitarised zone). In most deployments inbound and outbound requests will be handled by separate proxies on separate machines. In the case of inbound proxies, the proxy intercepts requests to the iTTM server and forwards them to the iTTM server along a secure channel.

Figure 2-5    Example Inbound Proxy

Since iTTM sees an inbound request as identical to either the proxy or the Identrus root or Bank, no iTTM settings need be changed for inbound proxies.

HTTPS Tunnelling

In the case of Outbound proxies iTTM acts as the SSL Client and utilises the proxy as a `tunnel' to the outside. When proxying, it is important to know which machine is the trusted client. If the iTTM is the trusted client then all SSL client certificates must come from iTTM and the proxy will not be able to decode the contents of the messages. In this situation SSL tunnelling is used to pass the encrypted communications packets through the proxy. In this case iTTM needs to know where to send requests.

Figure 2-6    Example Outbound Proxy

For outbound proxies the following parameters need to be added in the section [XURLHttps] within:

/opt/ittm/myhost/tbase.properties

For example:

[XURLHttps]

proxyhost=myhost.mycompany.com

proxyport=1312

notunnelling=false

Note that this section already exists in tbase.properties and as such should be modified rather than created from scratch.

HTTPS Forwarding

In the case that the proxy is the trusted client then SSL certificates must be stored on the proxy machine. iTTM will then communicate with the proxy on an encrypted channel and the communication is connected to a secure channel at the proxy. In such circumstances, tbase.properties should be modified as follows:

[XURLhttps]

proxyhost=myhost.mycompany.com

proxyport=1312

notunnelling=true

Note that this section already exists in tbase.properties and as such should be modified rather than created from scratch.

Default Settings

The following default settings are used if they are not explicitly set:

proxyport=443

notunnelling=false

Configuring the SMTP Proxy Separately

---

In some situations it may be more convenient to place the SMTP proxy on a separate machine.

Figure 2-7    DMZ Architecture for separating the SMTP Proxy

Using this configuration the systems administrators need to do the following.Configure nCipher Security world so that the nCipher boxes share the nCipher security world. A separate script is needed to ensure the appropriate iPlanet Trustbase Transaction Manager software is on both machines by performing the following steps:

1. Create a tar of a completed single machine install by typing tar -cvf Trustbase.tar Trustbase from the installation directory (/app)

2. Unpack this tar file on the computer you wish to run the proxy on. Unpack it into the same install directory structure as the original computer. (e.g /app). Do not install iPlanet Trustbase Transaction Manager, iPlanet Web Server or iPlanet Application Server on this new machine.

3. Enter the directory <new_install directory>/ittm and rename the directory that is named after the hostname of the computer and ensure it is the same as the new host. If the <new_install_directory> is different, edit the file <new_install_directory>/ittm/Scripts.setenv and change the directories names in TBASE_INSTALL and TBASE_HOME to refer to the <new_install_directory>

4. Edit the script <new_install_directory>/ittm/Scripts/runsmtpproxy to change the localhost to the machine hostname where iPlanet Trustbase Transaction Manager has been installed, as illustrated below:

   #!/bin/sh . ./setcp ulimit -n 128 echo $$ > pids/runsmtpproxy.pid cd $TBASE_INSTALL exec java uk.co.jcp.tbaseimpl.smtp.server.SmtpServer -debug 6 -url http://myhost.mycompany.com/NASApp/TbaseSmime/SmimeServlet -timeout 120000

5. To start the proxy on its own, enter this new hostname directory <new_install directory>/ittm/Scripts. Run the ./runsmtpproxy script.

6. On the host that is now no longer running the SMTP proxy, edit the script in <install directory>/ittm/Scripts entitled ./starttbase and remove the reference to the SMTP Proxy. You will want to do the same with the ./stoptbase script.

iAS and iWS on separate machines

---

As the iWS is on a separate machine, during installation of iTTM, the installer will not be able to locate the iWS docs directory. In this case, supply an empty directory of your choice and follow these steps after installation of iTTM:

1. tar -cvfh docs.tar <temp-dir> the temporary docs directory

2. ftp to the iWS host and place the docs.tar in /opt/iws6/docs

3. on the iWS host, untar the docs.tar with tar -xvf docs.tar

You should also consult the Section on Configurator Plug-in
http://docs.sun.com/source/816-5788-10/app1.htm#13421

URL Rewrites with iAS and iWS on separate machines

---

When deploying iTTM using the iAS and iWS on separate machines, the

following should be kept in mind:

1. The URL Re-writing has to be done for the Web Server (magnus.conf &

obj.conf ). However the tb-urlrewrite.so file is located in the iAS installation

/opt/ittm/current/Config/WebserverSetup/JWS/plugins/tb_url_rewri te.so

therefore you need to FTP this into

/opt/iws6/plugins/lib

2. Care should be taken in referencing the TC (either in AIA or using

/etc/hosts file), such that the entry is through the iWS machine

LDAPS

---

The webconnector is the portion of iAS which intercepts servlet requests to the webserver. This sits on the same machine as the webserver and communicates with an LDAP directory to obtain information such as the location of the application server and names to be interpreted as servlet requests. In some circumstances, it may be desirable to encode communications between the LDAP directory server and the webconnector. This is accomplished by setting up an SSL communication channel to the LDAP server.

This is known as LDAPS. For further background reading about this, you should consult:

1. Setting up SSL in LDAP

http://docs.sun.com/source/816-5606-10/ssl.htm#996824

2. To Configure Registry Entries consult iPlanet Application Server Administration Guide

http://docs.sun.com/source/816-5784-10/adconfig.htm#25855

3. iPlanet Directory Server Administration Guide

http://docs.sun.com/source/816-5606-10/index.html

4. Webless installs

   http://docs.sun.com/source/816-5788-10/app1.htm#13421

   In environments where security is important, often iAS is run behind a firewall, with iWS sat on a machine outside the firewall or in the DMZ. In the setup, the webconnector component must talk to the directory server for some of its configuration and, since it is outside the firewall, it may be desirable to make this communication secure. Out of the box, iAS does not support secure LDAP transaction. However, iTTM supplies a patch which may be installed to provide LDAPS for the webconnector only.

1. Separate iWS and iAS. See chapter in iAS manual on Webless Installs

   http://docs.sun.com/source/816-5788-10/app1.htm#13421

2. The version of the application server supplied with iTTM does not support LDAPS out of the box. A patch is provided to enable LDAPS with iAS6.5 To install the upgrade untar the patch and copy the libraries provided in ias/gxlib to your ias install.

   cd /opt/ittm/current/Config/WebserverSetup/patches

   tar xvf ldaps_ias6_5.tar

   cp ldaps_ias6_5/ias/gxlib/*.so /opt/ias6/ias/gxlib

   rm -r ldaps_ias6_5

   Note: these .so files need to be put in the /opt/ias6/ias/gxlib of the machine that has the Webserver & Connector.

3. Setup the directory Server for LDAPS
   1. Configure the directory server on the iAS machine for SSL

   2. Consult iPlanet Directory Server Administration Guide

   http://docs.sun.com/source/816-5606-10

   1. To install a certificate, use the certificate manager from the iDS administration console. This will allow you to request a certificate from your CA. This should be marked as usable by an SSL Server

   2. You will also need to install the trusted CA cert chain in the CA Certificate section of the console.

   3. After you have installed your certificate, turn on encryption by clicking the Enable SSL checkbox in the Encryption tab. We currently do not support Client Authentication so select any Client Authentication option except "required"

   4. Ensure that you have an SSL3.0 cipher selected rather than TLS.

4. Checking LDAPS.
   1. To check that LDAPS is setup correctly use Netscape Navigator. This has built in LDAP and LDAPS support.

   2. Go to the Location box on the tool bar and type in a URL of the following form. we illustrate a default example where myhost.mycompany.com is the DNS/IP of your directory server and port 389 is the unencrypted port number.

      ldap://myhost.mycompany.com:389/

   3. You should be talking to the unencrypted port here just to confirm that the directory server is up and running. If everything is as it should be, we will get a display of the directory server details. If you cannot connect, check all of your settings and/or try restarting the directory server

   4. To test secure communication, we need to inform Netscape to accept the SSL certificate as trusted. Go to your CA and import its certificate to your Netscape browser. Now try the following URL structure

      ldaps://myhost.mycompany.com:636/

   5. If the connection is working correctly then the directory server details should be displayed.

5. To configure the webconnector for secure LDAP connection, the iAS registry must be edited using kregedit. The following values must be added or modified
   1. Integer:

      SOFTWARE/iPlanet/Application Server/GDS/Backends/LDAP/<name_of_backend>/secure = 1

   2. String:

      SOFTWARE/iPlanet/Application Server/GDS/Backends/LDAP/<name_of_backend>/0/Host=<hostname of iAS machine>

      SOFTWARE/iPlanet/Application Server/GDS/Backends/LDAP/<name_of_backend>/0/Port=<Encrypted port of iAS machine>

      SOFTWARE/iPlanet/Application Server/6.5/CSSO/HTTPAPI/GXIP=<IPAddress of iAS machine>

   kregedit can be invoked by typing the command:

   ./opt/ias6/ias/bin/kregedit

   These settings are illustrated below

Figure 2-8    LDAPS settings

Figure 2-9    More LDAPS settings

Security can be turned off merely by setting the key secure = 0 and setting the port back to 389 i.e.

SOFTWARE/iPlanet/Application Server/GDS/Backends/LDAP/<name_of_backend>/secure = 0

SOFTWARE/iPlanet/Application Server/GDS/Backends/LDAP/<name_of_backend>/0/Port=<Unencrypted port of iAS machine>

6. Finally, install the CA certificate (as used in step 4) into the web server certificate database.

7. Now restart the web server and check the error log. This should inform you that LDAPS is enabled and that the LDAP connection is successful.

Technical Note on LDAP

The LDAP client does not support TLS, your LDAP server must use SSLv3.0

kregedit does not have LDAPS support. Therefore, once LDAPS is turned on, kregedit will no longer run. This can be dealt with by editing ias/registry/reg.dat and replacing the port value with the unencrypted port (389) & setting the secure value = 0 kregedit will now work again. Make your changes using kregedit and then change the port and security back to the secure version.