     ===============================================================
     University of Cambridge Web Authentication System (UcamWebauth)
       Apache Authentication Agent (mod_ucam_webauth) Installation
     ===============================================================

     1. Build requirements

     2. Building and installing the module
        2.1  Building and installing using APXS
        2.2  Building and installing RPMs
        2.3  Static Linking

     3. Operating requirements

     4. Initial configuration

Note that a pre-compiled binary version of the module is available for
use on Microsoft Windows. Windows users should see README.WIN32 and
then read sections 3 'Operating requirements' and 4 'Initial
Configuration' below.

1. Build requirements
=====================

* Apache

  The module is only of any use when used with a copy of Apache,
  version 1.3 or version 2.0 (it may or may not work with version
  2.1/2.2). Apache comes as part of most Unix/Linux distributions,
  though it may be necessary to install an additional package, perhaps
  called httpd-devel or apache-devel, for access to the tools needed
  to build the module.

* OpenSSL

  The module uses the OpenSSL library. Again this comes as part of
  most Unix/Linux distributions, and again it may be necessary to
  install an additional package, perhaps called openssl-devel for
  access to the tools needed to build the module.

* C compiler

  The module is written in C and all installation options involve
  compiling it from source so a C compiler is needed. Most Unix and
  Linux distributions install a C compiler by default. MacOS users
  should see INSTALL.Platforms for instructions on installing a C
  compiler and related tools.


2. Building and installing the module
=====================================

2.1 Building and installing using APXS
--------------------------------------

Apache is normally built so that new modules can be built as 'shared
objects' and plugged-in to Apache without having to rebuild the whole
program. Apache provides a tool, called apxs, to manage this
process. Providing your copy of Apache supports this, and most do,
then it's the easiest way to build the module.

You can check if you copy of Apache supports this feature by running
it with the '-l' command line option - if mod_so.c is shown
as one of the modules loaded then shared object support is available.

To build the module and copy it into the correct Apache directory,
first unpack the distribution tar file and cd into the directory it
creates:

  tar zxf mod_ucam_webauth-<ver>.tar.gz
  cd mod_ucam_webauth-<ver>

then issue the following command as root:

  apxs -c -i -lcrypto mod_ucam_webauth.c

If your copy of the OpenSSL library isn't in a standard place it may
be necessary to modify the '-lcrypto' option. apxs may not be on
root's default path and may be renamed, e.g. to apxs2, on some
platforms - see INSTALL.Platforms for some further details. apxs and
related files are sometimes provided by a httpd-devel or apache-devel
package which will need to be installed.


2.3 Building and installing RPMs
--------------------------------

The module is distributed as a pair of 'Source RPMs', one for Apache
v1.3 and one for Apache 2. On RPM-based Linux systems it is straight
forward to use one of these to build a binary RPM which can then be
installed as for any other package. This is particularly useful if you
need to install the module on a number of similar systems. This
approach will only work with copies of Apache that include shared
object support (see above). This is almost always the case with
RPM-based distributions.

To build an RPM, download the appropriate Source RPM, cd to the
directory containing it, and then as root issue the command

  rpmbuild --rebuild mod_ucam_webauth<n>-<ver>.src.rpm         

Near the end of the resulting output will be a line identifying the
binary RPM that was built, such as

  Wrote: /usr/src/redhat/RPMS/i386/mod_ucam_webauth<n>-<ver>.i386.rpm

can be installed by issuing, e.g., the command

  rpm -Uvh /usr/src/redhat/RPMS/i386/mod_ucam_webauth<n>-<ver>.i386.rpm


2.2  Static Linking
-------------------

Apache can be built with all modules linked into the main program - so
called 'static linking'. To add mod_ucam_webauth to such an
installation it is necessary to copy the module into the unpacked
Apache source tree and then to rebuild Apache.

Change into the Apache build directory and copy mod_ucam_webauth.c
from an unpacked tar distribution to src/modules/extra (for Apache
1.3) or modules/aaa (for Apache 2). Run the configure script with the
options as specified below in addition to any other options you wish
to set.

For an Apache 1.3 installation:

    ./configure --prefix=<PREFIX> \
    --activate-module=src/modules/extra/mod_ucam_webauth.c \
    --enable-module=ucam_webauth

For an Apache 2 installation:

    ./configure --prefix=<PREFIX> \
    --with-module=aaa:ucam_webauth

Issue the commands to build and install Apache in the usual way:

  make
  make install

Use the command

  httpd -l

to check that the module has been successfully incorporated into the
Apache server. It should be listed as mod_ucam_webauth.c.


3. Operating requirements
=========================

* RSA Public Keys

  UcamWebauth uses RSA public key cryptography to verify that
  authentication responses are sent only by the trusted authentication
  server. The module needs access to the relevant RSA public
  keys. Within the University of Cambridge, the keys used by the Raven
  service are available from https://raven.cam.ac.uk/project/keys/

  By default the module expects to find keys in a directory called
  conf/webauth_keys/ within Apache's server's 'ServerRoot'
  directory. INSTALL.Platforms documents server root for some
  systems. Alternatively the 'apxs' tool (see '2.1 Building and
  installing using APXS' above) can display the compiled-in default
  value of ServerRoot (though this can be overridden both on the
  command line used to start Apache and in the configuration file) by
  using

    apxs -q PREFIX

  If all else fails, trying to use the module with no keys installed
  will result in an error message in the server's error log which
  includes the expected path to the keys. The key file location can
  also be set using the AAKeyDir directive (see README.Config).

  The names of the key files should not be changed - beware that they
  have no filename suffix but that some browsers may add .txt or
  similar when downloading them.

* Timekeeping

  The protocol used to communicate between the module and the
  authentication server requires that both have access to accurate
  time values. UcamWebauth servers use NTP (Network Time Protocol) to
  set their clocks. Providing the server using the module has a clock
  synchronised by NTP or something similar then the default values for
  the time-related parameters in the module should be fine.

  If the server clock can't be assumed to be accurate within a second
  or so than the AAClockSkew directive (see README.Config) _must_ be
  used to provide an estimate of the maximum possible error in the
  server's clock. Messages in the web server error log containing the
  text 'local clock incorrect?' are likely if this parameter is not
  used on a server that needs it.


4. Initial configuration
========================

If the module has been built as a dynamic shared objects then it must
first be loaded using a 'LoadModule' directive such as:

  LoadModule ucam_webauth_module modules/mod_ucam_webauth.so

in the Apache configuration file, replacing 'modules/' if necessary
with the path to the directory containing the module, relative to
ServerRoot if it doesn't start '/'. This is not necessary if the
module has been statically linked into the httpd program.

Under Apache v1 some configuration files use 'ClearModuleList'
followed by 'AddModule' directives to ensure that modules are used in
the right order - if mod_ucam_webauth is loaded before
'ClearModuleList' then

  AddModule mod_ucam_webauth.c

will also be required somewhere. mod_ucam_webauth does not depend on
load order.

The minimum configuration required to restrict access to resources in
a particular directory to users with a Ucam-WebAuth login is, e.g.

  AACookieKey "some random string"
  <Directory "/path/to/protected/directory">
    AuthType Ucam-WebAuth
    Require valid-user
  </Directory>

The AACookieKey directive is required. It provides data used to sign
and verify the session cookie, providing detection of any
tampering. See README.Config for further important information about
this. See standard Apache documentation for other ways to use the
'Require' directive to restrict access to identified individuals.

In this example the protected resources is selected with a
<Directory> directive; resources specified by <Location> or <Files>
directives can also be protected. 'AuthType' must be set to
'Ucam-WebAuth'. A 'Require' directive must also appear before
authentication will take place.

See README.Config for more information about configuring the module.


--
$Id: INSTALL,v 1.1 2005/11/29 13:15:55 jw35 Exp $
