* 1.3.0

* Major shake-up of the documentation. README is now just a stub
  listing the other files; build and installation instructions now in
  INSTALL, with platform-dependent notes in INSTALL.Platforms;
  configuration reference now in README.Config. Documentation extended
  and (hopefully) improved. INSTALL now includes instructions for
  building and installing RPMs.

* Update Apache 2 code to use new APR_-prefixed macros rather than the
  depricated Apache 1.3 set. Apache 1.3 builds still see the old
  names.

* Extend the default 'no cookie' error page to mention that trying to
  bookmark a login page can provoke 'no cookie' errors.

* Move the files needed (only) for building rpms into a seperate
  directory

CHANGES

@@ -1,3 +1,35 @@
+1.3.0 - 2005-11-28 jw
+
+ Change to distributions
+
+ . Binary RPMs are no longer being distributed, at least from the
+   'official' distribution site, though Source RPMs will continue to
+   be provided. To partly compensate for this, the .spec files in the
+   source RPMs are now more general and at least stand a chance of
+   working unaltered on most distributions. The installation
+   documentation now includes instructions for building and installing
+   starting with source RPMs.
+
+ . The names given to binary RPMs generated by the provided .spec
+   files no-longer include a component identifying the distribution
+   for which they are intended.
+
+ Enhancements
+
+ . Major shake-up of the documentation. README is now just a stub
+   listing the other files; build and installation instructions now in
+   INSTALL, with platform-dependent notes in INSTALL.Platforms;
+   configuration reference now in README.Config. Documentation
+   extended and (hopefully) improved. INSTALL now includes
+   instructions for building and installing RPMs.
+
+ . Update Apache 2 code to use new APR_-prefixed macros rather than
+   the depricated Apache 1.3 set. Apache 1.3 builds still see the old
+   names.
+
+ . Extend the default 'no cookie' error page to mention that trying to
+   bookmark a login page can provoke 'no cookie' errors.
+
 1.2.2 - 2005-06-09 jw
 
  Bugs fixed

INSTALL

@@ -0,0 +1,246 @@
+     ===============================================================
+     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 $