Apache 1.3 Web Agent

Cams web agents are integrated into web and application servers to protect the resources that they provide. When a user's web browser makes a request to a web or application server, the Cams web agent asks a Cams policy server if access is granted or denied. The Cams web agent enforces the response, possibly prompting the user for authentication if required.

This document provides instructions on how to install and configure the Cams Apache 1.3 web agent, which is an Apache version 1.3 module available for the following operating systems and hardware architectures:

• RedHat Linux 9 for AMD/Intel x86
• RedHat Linux 8 for AMD/Intel x86
• RedHat Linux 7 for AMD/Intel x86
• Solaris 7 for sparc
• Solaris 8 for sparc
• Solaris 9 for sparc
• SUSE Linux Server 8 for AMD/Intel x86
• SUSE Linux Server 7 for AMD/Intel x86

If you need support for another operating system or hardware architecture, please contact Cafésoft support.

NOTE: For known issues with the Cams Apache 1.3 web agent, see ReleaseNotes.html found in the root directory of the Cams Apache web agent distribution.

Installation

These instructions guide you through the installation of Cams Apache 1.3 web agent on a system with Apache 1.3.x already installed. If Apache is not yet installed, you must first do so. You must also download the Cams Apache web agent. You can choose between the EAPI and non-EAPI versions. EAPI is the Apache's Extended API required by mod_ssl. If your Apache web server was compiled with EAPI, you need to use cams-webagent-apache13-linux-i386-eapi-2.0.X.tar.gz. If not, use cams-webagent-apache13-linux-i386-2.0.X.tar.gz. To see the options used when your Apache server was compiled, enter:

httpd -V

Confirming Availability of OpenSSL

The Cams Apache web agent requires the installation of OpenSSL libraries on your system to encrypt sensitive values sent to the Cams policy server. If you are using the EAPI version of Apache, OpenSSL is already installed on your system. However, if you are NOT using the EAPI version of Apache and OpenSSL is not installed, you will need to do so before proceeding. Please consult the documentation that came with your operating system distribution for installation instructions.

The following command can be used from a Unix command shell to look for existing OpenSSL libraries:

ls -laF /usr/lib/libssl*

If OpenSSL is installed, you should see a listing that looks something like this:

If OpenSSL is not installed in directory /usr/lib, it may be installed in directory /lib. In that case, try the following command:

ls -laF /lib/libssl*

NOTE: On some Unix/Linux installations, /lib is a symbolic link to /usr/lib, so they essentially represent the same directory.

Although OpenSSL version 0.9.7 is recommended, patched copies of 0.9.6 may also be used. Appropriate symbolic links will be setup by the Cams Apache 1.3 installation script if required.

OpenSSL also includes a cryptography library that is needed by the Cams Apache 1.3 web agent. The cryptography library version must be the same as the SSL library version. The following command can be used to confirm its availability:

ls -laF /usr/lib/libcrypto*

or

ls -laF /lib/libcrypto*

If the OpenSSL cryptography library is installed, you should see a listing that looks something like this:

lrwxrwxrwx 1 root other 18 Jan 28 16:40 /usr/lib/libcrypto.so -> libcrypto.so.0.9.7*
-rwxr-xr-x 1 root other 1311816 Feb 10 13:59 /usr/lib/libcrypto.so.0.9.7*

Unpacking Distribution Files

These instructions assume you are using the Linux/EAPI version. Substitute the appropriate file name for your operarting system and hardware architecture. You'll need to copy cams-webagent-apache13-linux-i386-eapi-2.0.X.tar.gz to a temporary directory on the target host. You must login as root and navigate to the directory where you copied the cams-webagent-apache13-linux-i386-eapi-2.0.X.tar.gz file and unpack it into the temporary directory.

cd /tmp
gunzip cams-webagent-apache13-linux-i386-eapi-2.0.X.tar.gz
tar xvf cams-webagent-apache13-linux-i386-eapi-2.0.X.tar

Change directories to the directory cams-webagent-apache13-linux-i386-eapi-2.0.X. The files shown in Figure 1 should have been extracted from the distribution.

<!-- Cams Apache web agent documentation and license -->
README.txt
LICENSE
ReleaseNotes.html
install-webagent.sh

<!-- Cams Apache web agent cgi-bin files -->
cgi-bin/cams-denied.sh
cgi-bin/cams-error.sh
cgi-bin/cams-login.sh
cgi-bin/cams-webagent-test.sh

<!-- Cams Apache 1.3 web agent configuration files -->
conf/cams-webagent.conf  
conf/webagent.properties
conf/access-control.properties

<!-- Cams Apache 1.3 web agent libraries (NOTE: Some file names may differ) -->
lib/mod_cams_apache13.so
lib/libcams.so.0
lib/libcamsclient_mt_cams_1_0.so.0
lib/libcams-common.so.0
lib/libcscore.so.0
lib/libcscrypto.so.0.9.6
lib/libcscrypto.so.0.9.7
lib/libapr-0.so.0.9.4

The target directories into which these files are copied may be a function of both the versions of Unix/Linux and Apache you are using. For example, the RedHat Linux 7.x RPM installs:

/etc/httpd/conf - the Apache configuration files
/etc/httpd/modules - the Apache modules
/var/www/cgi-bin - the Apache cgi-bin scripts
/var/www/html - the web pages

However, the standard Apache installation uses directories:

/usr/local/apache/conf - the Apache configuration files
/usr/local/apache/libexec - the Apache modules
/usr/local/apache/cgi-bin - the cgi-bin scripts
/usr/local/apache/htdocs - the web pages

Running the Installation Script

The installation script attempts to find the directories listed above, sometimes with your help. It then removes or backs up any previous Cams Apache web agent files it finds and copies the new files to the target locations you specify. If you want to run the installation script, do it now and skip to the Web Agent Configuration section:

cd /tmp/cams-webagent-apache13-linux-i386-eapi-2.0.X/
./install-webagent.sh

Follow the prompts to provide required information.

Web Agent Configuration

The Cams Apache web agent is configured in the cams-webagent.conf file. However, you'll also need to edit Apache's httpd.conf file and integrate Cams login, error, and denied shell pages.

NOTE: To secure resources on your Apache web server, you'll also need to configure a Cams security domain. See the Cams Policy Server Configuration section in this document for more information.

Editing cams-webagent.conf

Open the cams-webagent.conf file in a text editor. The file contains comments to help you understand the property values that you may need to change, as shown in Table 1.

Table 1 - Values you may need to edit in cams-webagent.conf

The other properties in this file configure debug and the Cams message protocol. You should not change the message protocol values unless instructed to do so by Cafésoft support.

Editing httpd.conf

You are now ready to edit Apache's httpd.conf file. Before proceeding, make sure that Apache is correctly working on the installation system by starting the Apache server and browsing to a test page. If not, see the Apache documentation for troubleshooting. Before making changes to httpd.conf, you should backup your existing file.

The integration of the Cams Apache web agent module requires the addition of commands to load the module. Open the /etc/httpd/conf/httpd.conf file in a text editor and navigate to the Dynamic Shared Object (DSO) Support section where the modules are loaded. Then, add the following lines at the end of the module loading section:

#
# Load Cams Apache web agent module
#
LoadModule cams_apache13_module modules/mod_cams_apache13.so

The next secition is typically where you add the modules. At the end of this section, add the following lines:

#
# Add Cams Apache web agent module and configuration file
#
AddModule CamsApache13WebAgent.c
CamsWebAgentConfigFile /etc/httpd/conf/cams-webagent.conf

Example 1 shows and typical configuration from httpd.conf included with RedHat 7.3. The inserted lines are in red.

#
# Dynamic Shared Object (DSO) Support
#
# To be able to use the functionality of a module which was built as a DSO you
# have to place corresponding `LoadModule' lines at this location so the
# directives contained in it are actually available _before_ they are used.
# Please read the file http://httpd.apache.org/docs/dso.html for more
# details about the DSO mechanism and run `httpd -l' for the list of already
# built-in (statically linked and thus always available) modules in your httpd
# binary.
#
# Note: The order in which modules are loaded is important.  Don't change
# the order below without expert advice.
#
# Example:
# LoadModule foo_module modules/mod_foo.so

...

<IfDefine HAVE_PUT>
LoadModule put_module modules/mod_put.so
</IfDefine>
<IfDefine HAVE_PYTHON>
LoadModule python_module modules/mod_python.so
</IfDefine>
#
# Load Cams Apache web agent module
#
LoadModule cams_apache13_module modules/mod_cams_apache13.so

...

<IfDefine HAVE_SSL>
AddModule mod_ssl.c
</IfDefine>
<IfDefine HAVE_PUT>
AddModule mod_put.c
</IfDefine>
<IfDefine HAVE_PYTHON>
AddModule mod_python.c
</IfDefine>

#
# Add Cams Apache web agent module. Set the absolute paths to the
# configuration file.
#
AddModule CamsApache13WebAgent.c
CamsWebAgentConfigFile /etc/httpd/conf/cams-webagent.conf

...

Provided you have already configured a Cams security domain, you should now be ready to test this Cams Apache 1.3 web agent installation. A self-documented test page is provided in the cgi-bin directory that you can use for testing.

NOTE: Due to the large number of Apache modules, testing all combinations of module loading is impossible. If you experience difficulty loading the Cams Apache web agent module, try changing the module loading order.

WARNING: To avoid security policy conflicts, you should disable Apache security specified in httpd.conf for all resources that are protected by Cams.

Securing Directories and Files

If you have not done so already, you should secure important Apache configuration and log directories and files which may contain Apache SSL certificates, configuration files containing passwords or secret keys, and log files containing sensitive information.

In most cases, the Apache 1.3.x web server process is started under root ownership and creates child processes that run as another user, like apache or nobody. Generally, the original process opens and reads configuration files and sockets, then forks a child process to handle requests. Each child process inherits the open file descriptors created by the parent process, so they are able to write to logs files, sockets, etc. The configuration file APACHE_HOME/conf/cams-webagent.conf file is read by mod_cams_apache13 within the parent process and the log file APACHE_HOME/logs/cams-webagent.log is also created by the Apache parent process and inherited by children.

In the instructions that follow, it is assumed that the Apache server is executed by root on your Linux/UNIX system. This example assumes that:

1. Apache is installed at /etc/httpd
2. The Apache configuration directory is at: /etc/httpd/conf
3. The Apache log directory is at: /etc/httpd/logs
4. That you are logged in as root.

As is the case with any command that root executes, you must take care that it is protected from modification by non-root users. Not only must the files themselves be writable only by root, but so must the directories, and parents of all directories. It is assumed that /, /etc, and /etc/httpd are only modifiable by root. When you install the Apache server, you should ensure that it is similarly protected.

The following steps secure the directories and files relevant to Cams in the Apache environment:

Step 1 - Change directories to the Apache server installation directory

cd /etc/httpd

Step 2 - Set user and group ownership of all files and directories

chown root conf
chgrp root conf
chown root conf/cams-webagent.conf
chgrp root conf/cams-webagent.conf
chown root logs
chgrp root logs

This command sets user and group ownership to root.

NOTE: You may consider setting the ownership of all files within the Apache installation tree to root using the following command:

chown -R root .
chgrp -R root .

Step 3 - Set directory permissions

chmod 700 conf
chmod 700 logs

This command gives read/write/execute permissions only for the owner (root). No other users or groups are given permissions on these directories, so they will unable to view or modify their contents.

Step 4 - Set file permissions

chmod 600 conf/cams-webagent.conf
chmod 600 logs/cams-webagent.log (Use only if this file exists)

These commands gives them read/write permissions for the owner (root). No other users or groups are given permission to read or write these files.

Step 5 - Set Apache startup/shutdown script umask

To further secure your Apache server/Cams web agent installation, you may consider setting file creation permissions so that only root may read/write log files. This is desireable if log files (like the cams-webagent.log file) contain sensitive DEBUG-level information or to avoid hackers from replacing log files or setting up symbolic links that can redirect the contents of log files.

Under Unix, newly created files (e.g., Apache log files) are given default permissions which are a combination of: 666 (read/write permission for everybody) and the currently-set file creation mask (called the umask). The umask is combined with permission 666 to take away permissions that might otherwise be granted. By setting the umask value for the shell that executes Apache, log files that are created can be given a default permission 600, which enables the owner (root) to read/write to them, but denies permissions to all other users.

Generally, Unix user accounts setup a default umask of 022, which results in newly created file permissions of 644. This permission value still enable group and world users to read a file, which is not desireable with sensitive log files. Using umask value 077 will cause newly created files to be given the desired permissions 600.

If the Apache web server is started using the shell script at:

/etc/init.d/httpd

You can set the umask for the associated shell by inserting a command at the top of the script as shown in Example 2.

#!/bin/sh
#
# Startup script for the Apache Web Server
#
# chkconfig: - 85 15
# description: Apache is a World Wide Web server.  It is used to serve \
#              HTML files and CGI.
# processname: httpd
# pidfile: /var/run/httpd.pid
# config: /etc/httpd/conf/access.conf
# config: /etc/httpd/conf/httpd.conf
# config: /etc/httpd/conf/srm.conf

# Source function library.
. /etc/rc.d/init.d/functions

# This will prevent initlog from swallowing up a pass-phrase prompt if
# mod_ssl needs a pass-phrase from the user.
INITLOG_ARGS=""

# Path to the apachectl script, server binary, and short-form for messages.
apachectl=/usr/sbin/apachectl
httpd=/usr/sbin/httpd
prog=httpd
RETVAL=0

umask 077

...

To test these file and directory permissions:

1. If the Unix system hosting Cams supports normal user accounts, try logging in as a normal user.
2. Try to list the contents of /usr/local/cams (permission should be denied)
3. Try changing directories to /usr/local/cams (permission should be denied)
4. Try creating a test file in /usr/local/cams/test.txt using a text editor (permission should be denied)
5. To test file creation permissions, login as root. If file /user/local/cams/logs/cams-webagent.log exists, remove it. Then start the Apache web server and confirm that files created in the logs directory have permission: 600.

Scripts

The distribution cgi-bin directory includes four sample Bourne/Bash shell scripts:

• cams-webagent-test.sh - enables lazy and proactive authentication and access control testing, displays context sensitive information for authenticated users
• cams-denied.sh - displays an access denied page if access to a resource request is denied
• cams-error.sh - displays an error page if an authentication or resource request error occurs
• cams-login.sh - displays a login page if a protected resource request is made and the user's identity is not known

cams-webagent-test.sh

You should browse to cams-webagent-test.sh to understand how to configure and use it for testing. The page is posted to the URI specified by the cams.login.uri property in cams-webagent.conf along with the following form name/value pairs:

• cams_cb_username - the username
• cams_cb_password - the user password
• cams_security_domain - the login security domain
• cams_login_config - the security domain's login-config-entry to use
• cams_original_url - The URL to redirect to after successful authentication and authorization

When you click the submit button, the Cams Apache web agent intercepts the POST to the cams.login.uri and sends the request to a Cams policy server. The request includes the security domain and a login-config-entry, which a Cams policy server will use to attempt login. If you successfully authenticate and are authorized (depending upon how you configure the security domain), the browser is redirected to the cams_orginal_url and user specific information is displayed by cams-webagent-test.sh.

cams-login.sh

When you request a protected resource that requires authentication and Cams doesn't know your user identity, the Cams Apache web agent displays a login page as specified by the login-parameters in a security domain's login-config.xml file. The login page is identical to cams-index.sh, except that the hidden values are dynamically populated as shown in Example 3.

WARNING: You must correctly configure the login-parameters in the security domain's login-config.xml file or the login page will not be displayed. See the Cams Administrator's Guide - Login Configuration for more information on configuring login-parameters in login-config.xml.

<!-- Populate hidden fields from their request parameters -->
<input type=hidden name=\"securityDomain\" value=\"${QS_SECURITY_DOMAIN}\">
<input type=hidden name=\"loginConfig\"    value=\"${QS_LOGIN_CONFIG}\">
<input type=hidden name=\"originalUrl\"    value=\"${QS_ORIGINAL_URL}\">

The difference between cams-webagent-test.sh and cams-login.sh are that you arrive at the former lazy authentication login page after requesting a resource for which your identity is unknown to the Cams policy server. Because of the resource request, Cams knows the security domain and login-config-entry to which the resource belongs (and, of course, the original URL).

cams-denied.sh

If you are denied access to a resource protected by Cams, the page specified by the cams.denied.url property in cams-webagent.conf is displayed. Example 4 shows a script that displays dynamic messages.

#
#---    Parse the QUERY_STRING into standard variables
#
doParseQueryString ()
{
  #---    Parse into name=value pairs
  for pair in `echo -e ${QUERY_STRING//&/'\n'}`
  do
    #---    Parse the name and value
    name=`echo ${pair} | cut -d'=' -f1`
    value=`echo ${pair} | cut -d'=' -f2`

    #--- Decode + to space, Hex values into character values
    #--- Assign expected query parameters to global variables
    tmp=`echo ${name} | sed -e 's/+/ /g' | sed -e 's/%/\\\x/g'`
    decodedName=`printf "${tmp}"`
    if [ "${decodedName}" = "message" ] ; then
      tmp=`echo ${value} | sed -e 's/+/ /g' | sed -e 's/%/\\\x/g'`
      QS_MESSAGE=`printf "${tmp}"`
    fi
    done
}

cams-error.sh Example

If an error occurs, Cams displays the page specified by the cams.error.url property in cams-webagent.conf. Example 5 shows a script that displays dynamic messages.

#
#---    Parse the QUERY_STRING into standard variables
#
doParseQueryString ()
{
  #---    Parse into name=value pairs
  for pair in `echo -e ${QUERY_STRING//&/'\n'}`
  do
    #---    Parse the name and value
    name=`echo ${pair} | cut -d'=' -f1`
    value=`echo ${pair} | cut -d'=' -f2`

    #--- Decode + to space, Hex values into character values
    #--- Assign expected query parameters to global variables
    tmp=`echo ${name} | sed -e 's/+/ /g' | sed -e 's/%/\\\x/g'`
    decodedName=`printf "${tmp}"`
    if [ "${decodedName}" = "message" ] ; then
      tmp=`echo ${value} | sed -e 's/+/ /g' | sed -e 's/%/\\\x/g'`
      QS_ERROR_MESSAGE=`printf "${tmp}"`
    fi
    done
}

NOTE: In order to ensure that the browser does not cache these pages, it is important that you use the following HTML Meta tags in the HEAD section of each page:

<meta http-equiv="Pragma"        content="no-cache">
<meta http-equiv="Cache-Control" content="no-cache">   		
<meta http-equiv="Expires"       content="-1">

Optimizations

The Cams Apache 1.3 web agent installs with default configuration properties. However, you may find it beneficial to configure your installation to more adequately meet the requirements of your environment. See Cams Web Agent Optimizations to learn more about Cams Apache 1.3 web agent optimizations.

Cams Policy Server Configuration

Before you start the Apache server with a Cams Apache 1.3 web agent, you'll need to ensure that the Cams policy server knows about it. See Web Agent-specific Cams Policy Server Configuration to learn more about Cams policy server configuration requirements.

Testing

That's it, you should now be able to start Apache to test your Cams Apache web agent configuration. After you've started both Apache with the Cams Apache web agent and the Cams policy server, test the configuration using:

http://[hostname:port]/cgi-bin/cams-webagent-test.sh

Login to an account in the security domain that you've established. See the test page for more configuration and testing information.

Back | Next | Contents

© Copyright 1996-2004 Cafésoft LLC. All rights reserved.