convert to unix line endings
authorMatthew Vernon <mcv21@cam.ac.uk>
Tue, 22 Jul 2014 16:01:31 +0000 (17:01 +0100)
committerMatthew Vernon <mcv21@cam.ac.uk>
Tue, 22 Jul 2014 16:01:31 +0000 (17:01 +0100)
README.md

index 7c59294..3ddcbc1 100644 (file)
--- a/README.md
+++ b/README.md
-´╗┐University of Cambridge Classic ASP/VBScript Raven Authentication Module - v.1.0 (29/04/2014)\r
-==========================================================================\r
-\r
-Description\r
------------\r
-This software comprises a VBScript class 'Ucam_Webauth' and sample\r
-files that provide a Classic ASP/VBScript implementation of a 'Raven'\r
-authentication module; Raven is the web authentication protocol used\r
-by the University of Cambridge, UK. The logic and code of the\r
-'Ucam_Webauth' class are loosely based on the PHP Raven authentication\r
-class provided at http://raven.cam.ac.uk/project/.\r
-- For a full description of the latest Raven specification and an explanation \r
-of how Raven works, go to http://raven.cam.ac.uk/project/.\r
-- This software was originally created for the Careers Service,\r
-University of Cambridge by sh801@cam.ac.uk. For support, please\r
-contact raven-support@ucs.cam.ac.uk\r
-\r
-Files and folders\r
------------------\r
-- [certificates]: Temporary location for Raven public key certificates.\r
-- [js]: Folder containing Javascript cryptography libraries.\r
-- [docs]: Supporting documentation.\r
-- [logs]: Possible location for log files created by the module.\r
-- Default.asp: A sample file showing how the 'Ucam_Webauth' class is used \r
-to provide Raven authentication.\r
-- Test.asp: A test file for unit testing the 'Ucam_Webauth' module using the \r
-'Ucam_RavenWLS' dummy Raven server (separate project, not included).\r
-- Ucam_Webauth.vbs: The main 'Ucam_Webauth' VBScript class.\r
-\r
-Platform requirements\r
----------------------\r
-This module has been tested on IIS7 with .NET Framework set to \r
-'No managed code', ie. classic ASP.\r
-\r
-Installation\r
-------------\r
-### Cryptographic functions\r
-Cryptographic functions are provided by the Javascript libraries within the \r
-'js' folder. These libraries are versions of the client-side Javascript \r
-libraries provided at http://kjur.github.io/jsrsasign/index.html \r
-but modified to run server-side. There is no need to install any \r
-additional cryptography libraries.\r
-\r
-### Install Raven certificates\r
-The authentication module uses the Raven public key certificate at \r
-https://raven.cam.ac.uk/project/keys/ to verify authentication responses. \r
-Download the certificate from https://raven.cam.ac.uk/project/keys/ and copy \r
-to the 'certificates' folder provided with this authentication module \r
-download - the 'certificates' folder is a temporary location for the \r
-certificate while you get the module up and running. You will need to supply \r
-the full path to the 'certificates' folder as either a 'key_dir' argument \r
-to the 'Ucam_Webauth' constructor or by modifying the 'Ucam_Webauth' \r
-variable 'DEFAULT_KEY_DIR' directly. \r
-\r
-Once you have everything working, move the 'certificates' folder \r
-to a new location on your webserver that is not web- or publicly-accessible \r
-and modify the 'key_dir' string accordingly.\r
\r
-- NOTE: you may have to change the name of the key file from 'pubkey2.crt' \r
-to '2.crt'. \r
-\r
-If you're using the Raven test server \r
-(http://raven.cam.ac.uk/project/test-demo/) for testing purposes, make sure \r
-you install the test server keys instead, but ensure you remove these keys \r
-before using the authentication module in a production environment, as \r
-recommended by the demo Raven server:\r
-\r
-> It is vital to keep these demo keys seperate from keys \r
-> used with a production service - failure to do so could \r
-> allow an attacker to successfully replay a response \r
-> from the demonstration server, which anyone can easily \r
-> obtain, against a production service. \r
-\r
-Getting started\r
----------------\r
-\r
-The 'Ucam_Webauth' VBScript class must be used within an ASP server-side page \r
-as it interacts directly with a user's browser session. To use the \r
-'Ucam_Webauth' VBScript class:\r
-\r
-- 1. Ensure the 'Ucam_Webauth.vbs' class file and the folder 'js' are in the \r
-same directory as your ASP script. The folders 'certificates' and 'logs' may \r
-also be located here temporarily. \r
-- 2. Include the 'Ucam_Webauth.vbs' class file in the 'head' of your ASP file:\r
-\r
-\r
-    <head>\r
-    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">\r
-    <!--#include file="Ucam_Webauth.vbs"-->\r
-    </head>\r
-\r
-- 3. Set up the initial arguments for the 'Ucam_Webauth' class:\r
-\r
-```\r
-Set args = CreateObject("Scripting.Dictionary")\r
-args.Add "hostname", "localhost"\r
-args.Add "auth_service", "https://demo.raven.cam.ac.uk/auth/authenticate.html"\r
-args.Add "key_dir", "C:/Ucam_Webauth/certificates"\r
-```\r
-\r
-'args' is an associative array of *text* strings so parameter values must \r
-be converted into strings, ie. numbers and booleans must be supplied within \r
-quotes as in "23", "TRUE", "FALSE".\r
-A full list of allowed parameters is provided at the end of this README. \r
-\r
-- 4. Create an instance of the 'Ucam_Webauth' class from within your ASP \r
-server page and initialize with setup variables:\r
-\r
-```\r
-Set oUcam_Webauth = New Ucam_Webauth\r
-Call oUcam_Webauth(args)       \r
-```\r
-   \r
-- 5. Call 'Authenticate()' on the Ucam_Webauth object and act according to \r
-the value returned:\r
-\r
-```\r
-       Select Case oUcam_Webauth.Authenticate()\r
-               \r
-               Case oUcam_Webauth.AUTHENTICATE_INCOMPLETE\r
-\r
-                       ...                     \r
-                       Exit Sub\r
-\r
-               Case oUcam_Webauth.AUTHENTICATE_COMPLETE_AUTHENTICATED          \r
-\r
-                       ...\r
-                                       \r
-               Case oUcam_Webauth.AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED              \r
-\r
-                       ...\r
-\r
-               Case oUcam_Webauth.AUTHENTICATE_COMPLETE_ERROR          \r
-\r
-                       ...\r
-                                       \r
-       End Select\r
-```\r
-\r
-The four possible return values of 'Authenticate()' are:\r
-\r
-- AUTHENTICATE_INCOMPLETE : The authentication process has yet to complete. \r
-The user may have been redirected to the Raven server and has yet to enter \r
-their login details.\r
-- AUTHENTICATE_COMPLETE_AUTHENTICATED : The authentication process completed \r
-and the user has been successfully authenticated.\r
-- AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED : The authentication process \r
-completed and the user was not successfully authenticated. \r
-The user may have clicked 'Cancel' at the Raven server.\r
-- AUTHENTICATE_COMPLETE_ERROR : There was an error during the authentication \r
-process forcing the authentication cycle to terminate early.\r
-\r
-As the 'Authenticate()' function may need to send HTTP headers, it must be \r
-called before any output (e.g. HTML, HTTP headers) is sent to the browser.\r
-\r
-The 'Default.asp' file provided is a sample of a simple server page using \r
-the 'Ucam_Webauth' VBScript class.\r
-\r
-Overview of Raven process\r
--------------------------\r
-A diagram of the Raven authentication process is located within the 'docs' \r
-folder as [I - Overview of Raven Authentication Process.pdf]. \r
-\r
-The authentication cycle consists of the following key stages:\r
-\r
-#### User first tries to access authenticated page\r
-User tries to load an authenticated page on a particular website. \r
-The 'Ucam_Webauth' class is loaded and the 'Authenticate()' function is called. \r
-If no authentication cookie is found to indicate the user is authenticated, \r
-the user's browser is redirected to a separate Raven server using a special \r
-'Authentication Request'. The authentication request consists of a series of \r
-authentication parameters encoded into the URL redirect as name/value pairs.\r
-\r
-#### User is prompted for login information\r
-The Raven server interprets the authentication request sent by the main \r
-website and prompts the user for their username and password. The user may \r
-then be successfully authenticated or may decide to click 'Cancel'. They are \r
-redirected back to the main website with a series of 'Authentication Response' \r
-parameters encoded into a 'WLS-Response' GET variable.\r
-\r
-#### User redirected back to main webserver\r
-The user's original page is loaded again and 'Authenticate()' is called a \r
-second time. 'Ucam_Webauth' processes the new 'WLS-Response' GET value and, \r
-if it's valid, sets an authentication cookie on the user's browser. The \r
-user's original page is then loaded again. \r
-\r
-#### User redirected back to main webserver again \r
-With an authentication cookie now set, 'Authenticate()' checks the status \r
-code contained in the value of the authentication cookie and returns either \r
-'AUTHENTICATE_COMPLETE_AUTHENTICATED' or \r
-'AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED'. If \r
-'AUTHENTICATE_COMPLETE_AUTHENTICATED' is returned , the original page can \r
-go on to display authenticated content to the user.\r
-\r
-Specifics of module\r
--------------------\r
-The 'Authenticate()' function is the overarching authentication function of \r
-'Ucam_Webauth'. It performs some basic sanity checks using 'CheckSetup()' \r
-then uses 'GetCurrentState()' to establish the current state of the \r
-authentication process before branching accordingly. The possible return \r
-values of 'GetCurrentState()' are:\r
-\r
-#### STATE_NEW_AUTHENTICATION\r
-A completely fresh authentication. 'SendAuthenticationRequest()' [*1*] is \r
-then triggered which performs some basic data checks, sets the authentication \r
-cookie to 'AUTHENTICATIONCOOKIE_REDIRECT_WLS' (to record where we are in the \r
-authentication process) and redirects the user's browser to the Raven \r
-authentication server with a series of authentication parameters \r
-encoded as name/value pairs.\r
-\r
-#### STATE_WLS_RESPONSE_RECEIVED\r
-The Raven authentication server has processed the user and has returned the \r
-user's browser back to the original website with a series of authentication \r
-response parameters encoded into the 'WLS-Response' GET variable. \r
-'ProcessAuthenticationResponse()' [*2*] is then called which checks the \r
-validity of the 'WLS-Response' value, sets an authentication cookie and \r
-redirects the user back to the original page.\r
-\r
-#### STATE_WAA_AUTHENTICATIONCOOKIE_SET\r
-A valid authentication cookie has been set \r
-(<> AUTHENTICATIONCOOKIE_REDIRECT_WLS). \r
-'ProcessAuthenticationCookie()' [*3*] is then called which checks the \r
-validity of the cookie. If the cookie has expired, \r
-'SendAuthenticationRequest()' is called again in case the user needs to \r
-reauthenticate themselves. If the cookie is still valid, an \r
-'AUTHENTICATE_COMPLETE_XXX' value is returned, indicating that the \r
-authentication cycle has completed successfully. \r
-NOTE: this may be true if the user has cancelled the authentication process, \r
-in which case 'AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED' will be returned.\r
-\r
-#### STATE_ERROR\r
-An error occurred, breaking the authentication cycle and returning \r
-AUTHENTICATE_COMPLETE_ERROR to 'Authenticate()'. This return value will \r
-also be generated by the other functions above if they generate an error.\r
-\r
-## Accompanying diagrams\r
-Detailed diagrams of the Raven process flow for (i) a successful \r
-authentication (ii) a cancelled authentication, are located in the 'docs' \r
-folder as [II - Ucam_Webauth - Flowchart for Valid Authentication.pdf] and \r
-[III - Ucam_Webauth - Flowchart for Cancelled Authentication.pdf], respectively. \r
-\r
-The numbers on these diagrams correspond to the three key secondary functions \r
-described above:\r
-- *1*. SendAuthenticationRequest()\r
-- *2*. ProcessAuthenticationResponse()\r
-- *3*. ProcessAuthenticationCookie()\r
-\r
-Other important functions include:\r
-\r
-### ResetState()\r
-Attempts to reset state as if a new user has just loaded a fresh browser \r
-window. This is typically used when a user has experienced an error and we \r
-want to give them a fresh opportunity to try again. \r
-\r
-### check_signature(...)\r
-Checks the signature provided by the Raven server, when it signed the \r
-'WLS-Response' variable, is a valid signature for the data. This ensures the \r
-data has not been tampered with.\r
-\r
-### hmac_sha1(...)\r
-Creates a hash value for signing the local authentication cookie.\r
-\r
-### wls_encode/decode(...)\r
-Encoding/decoding functions to allow base64 signatures to be sent within URLs.\r
-\r
-Possible arguments to 'Ucam_Webauth'\r
-------------------------------------\r
-(Based on documentation for PHP Raven authentication module)\r
-\r
-- log_file : \r
-The location for a log file that will record progress and track possible \r
-errors. The folder containing the file must be read/writable by the webserver.\r
-Default: log.txt\r
-\r
-- response_timeout : \r
-Responses from the central authentication server are time-stamped. \r
-This parameter sets the period of time in seconds during which these \r
-responses are considered valid. \r
-Default: 30 seconds.\r
-\r
-- key_dir : \r
-The name of the directory containing the public key certificate(s) required \r
-to validate the authentication responses sent by the server. \r
-Default: '/etc/httpd/conf/webauth_keys'.\r
-\r
-- max_session_life : \r
-The maximum period of time in seconds for which an established session will \r
-be valid. This may be overriden if the authentication reply contains a \r
-shorter 'life' parameter. Note that this does NOT define an expiry time for \r
-the session cookie. Session cookies are always set without an expiry time, \r
-causing them to expire when the browser session finishes. \r
-Default: 7200 (2 hours).\r
-\r
-- timeout_message : \r
-A re-authentication by the authentication service will be triggered when an \r
-established session expires. This option sets a text string which is sent to \r
-the authentication server to explain to the user why they are being asked to \r
-authenticate again. HTML markup is suppressed as for the description \r
-parameter described below. \r
-Default: 'your login to the site has expired'.\r
-\r
-- hostname (required) :\r
-The fully-qualified TCP/IP hostname that should be used in request URLs \r
-referencing the Ucam_Webauth-enabled application. This *must* be set, as it \r
-is needed for multiple reasons - primarily security but also to avoid varying \r
-hostnames in URLs leading to failed or inconsistent authentication. \r
-No default.\r
-\r
-- cookie_key (required): \r
-A random key used to protect session cookies from tampering. Any reasonably \r
-unpredictable string (for example the MD5 checksum of a rapidly changing \r
-logfile) will be satisfactory. This key must be the same for all uses of the \r
-web authentication system that will receive the same session cookies (see the \r
-cookie_name, cookie_path and cookie_domain parameters below). \r
-No default.\r
-\r
-- cookie_name :\r
-The name used for the session cookie. \r
-When used for access to resources over HTTPS the string '-S' is appended to \r
-this name. \r
-Default: 'Ucam-Webauth-Session'.\r
-\r
-- cookie_path :\r
-The 'Path' attribute for the session cookie. The default is the directory \r
-component of the path to the script currently being executed. This should \r
-result in the cookie being returned for future requests for this script and \r
-for the other resources in the same 'directory'; see the important \r
-information about the cookie_key parameter above. \r
-Default: '/'.\r
-\r
-- cookie_domain :\r
-The 'Domain' attribute for the session cookie. By default the 'Domain' \r
-attribute is omitted when setting the cookie. This should result in the \r
-cookie being returned only to the server running the script. Be aware that \r
-some people may treat with suspicion cookies with domain attributes that are \r
-wider than the host setting the cookie. \r
-No default.\r
-\r
-- auth_service : The full URL for the web login service to be used. \r
-Default: 'https://raven.cam.ac.uk/auth/authenticate.html' \r
-\r
-#### Authentication request properties\r
-The following setup parameters prefixed with 'authrequest_' relate to \r
-properties that will be sent to the authentication server as part of an \r
-authentication request:\r
-\r
-- authrequest_desc : A text description of the resource that is requesting \r
-authentication. This may be displayed to the user by the authentication \r
-service. It is restricted to printable ASCII characters (0x20 - 0x7e) though \r
-it may contain HTML entities representing other characters. The characters \r
-'<' and '>' will be converted into HTML entities before being sent to the \r
-browser and so this text cannot usefully contain HTML markup.\r
-No default.\r
-\r
-- authrequest_params : Data that will be returned unaltered to the WAA in \r
-any 'authentication response message' issued as a result of this request. \r
-This could be used to carry the identity of the resource originally requested \r
-or other WAA state, or to associate authentication requests with their \r
-eventual replies. When returned, this data will be protected by the digital \r
-signature applied to the authentication response message but nothing else is \r
-done to ensure the integrity or confidentiality of this data - the WAA MUST \r
-take responsibility for this if necessary.\r
-No default.\r
-\r
-- authrequest_skew : Interpretation of response_timeout is difficult if the \r
-clocks on the server running the PHP agent and on the authentication server \r
-are out of step. Both servers should use NTP to synchronize their clocks, \r
-but if they don't then this parameter should be set to an estimate of the \r
-maximum expected difference between them (in seconds). \r
-Default: 0.\r
-\r
-- authrequest_fail :\r
-If TRUE, sets the fail parameter in any authentication request sent to the \r
-authentication server to 'yes'. This has the effect of requiring the \r
-authentication server itself to report any errors that it encounters, rather \r
-than returning an error indication. Note however that even with this parameter \r
-set errors may be detected by this module that will result in authentication \r
-failing here. \r
-Default: FALSE.\r
-\r
-- authrequest_iact :\r
-If TRUE, then the 'iact' parameter provided to the authentication server is \r
-set to 'yes'. If FALSE, then the 'iact' parameter is set to 'no'. If no value \r
-is provided for 'authrequest_iact', the 'iact' parameter is left blank. \r
-The value 'yes' for 'iact' requires that a re-authentication exchange takes \r
-place with the user. This could be used prior to a sensitive transaction in \r
-an attempt to ensure that a previously authenticated user is still present \r
-at the browser. The value 'no' requires that the authentication request will \r
-only succeed if the user's identity can be returned without interacting with \r
-the user. This could be used as an optimisation to take advantage of any \r
-existing authentication but without actively soliciting one. If omitted or \r
-empty, then a previously established identity may be returned if the WLS \r
-supports doing so, and if not then the user will be prompted as necessary.\r
+University of Cambridge Classic ASP/VBScript Raven Authentication Module - v.1.0 (29/04/2014)
+==========================================================================
+
+Description
+-----------
+This software comprises a VBScript class 'Ucam_Webauth' and sample
+files that provide a Classic ASP/VBScript implementation of a 'Raven'
+authentication module; Raven is the web authentication protocol used
+by the University of Cambridge, UK. The logic and code of the
+'Ucam_Webauth' class are loosely based on the PHP Raven authentication
+class provided at http://raven.cam.ac.uk/project/.
+- For a full description of the latest Raven specification and an explanation 
+of how Raven works, go to http://raven.cam.ac.uk/project/.
+- This software was originally created for the Careers Service,
+University of Cambridge by sh801@cam.ac.uk. For support, please
+contact raven-support@ucs.cam.ac.uk
+
+Files and folders
+-----------------
+- [certificates]: Temporary location for Raven public key certificates.
+- [js]: Folder containing Javascript cryptography libraries.
+- [docs]: Supporting documentation.
+- [logs]: Possible location for log files created by the module.
+- Default.asp: A sample file showing how the 'Ucam_Webauth' class is used 
+to provide Raven authentication.
+- Test.asp: A test file for unit testing the 'Ucam_Webauth' module using the 
+'Ucam_RavenWLS' dummy Raven server (separate project, not included).
+- Ucam_Webauth.vbs: The main 'Ucam_Webauth' VBScript class.
+
+Platform requirements
+---------------------
+This module has been tested on IIS7 with .NET Framework set to 
+'No managed code', ie. classic ASP.
+
+Installation
+------------
+### Cryptographic functions
+Cryptographic functions are provided by the Javascript libraries within the 
+'js' folder. These libraries are versions of the client-side Javascript 
+libraries provided at http://kjur.github.io/jsrsasign/index.html 
+but modified to run server-side. There is no need to install any 
+additional cryptography libraries.
+
+### Install Raven certificates
+The authentication module uses the Raven public key certificate at 
+https://raven.cam.ac.uk/project/keys/ to verify authentication responses. 
+Download the certificate from https://raven.cam.ac.uk/project/keys/ and copy 
+to the 'certificates' folder provided with this authentication module 
+download - the 'certificates' folder is a temporary location for the 
+certificate while you get the module up and running. You will need to supply 
+the full path to the 'certificates' folder as either a 'key_dir' argument 
+to the 'Ucam_Webauth' constructor or by modifying the 'Ucam_Webauth' 
+variable 'DEFAULT_KEY_DIR' directly. 
+
+Once you have everything working, move the 'certificates' folder 
+to a new location on your webserver that is not web- or publicly-accessible 
+and modify the 'key_dir' string accordingly.
+- NOTE: you may have to change the name of the key file from 'pubkey2.crt' 
+to '2.crt'. 
+
+If you're using the Raven test server 
+(http://raven.cam.ac.uk/project/test-demo/) for testing purposes, make sure 
+you install the test server keys instead, but ensure you remove these keys 
+before using the authentication module in a production environment, as 
+recommended by the demo Raven server:
+
+> It is vital to keep these demo keys seperate from keys 
+> used with a production service - failure to do so could 
+> allow an attacker to successfully replay a response 
+> from the demonstration server, which anyone can easily 
+> obtain, against a production service. 
+
+Getting started
+---------------
+
+The 'Ucam_Webauth' VBScript class must be used within an ASP server-side page 
+as it interacts directly with a user's browser session. To use the 
+'Ucam_Webauth' VBScript class:
+
+- 1. Ensure the 'Ucam_Webauth.vbs' class file and the folder 'js' are in the 
+same directory as your ASP script. The folders 'certificates' and 'logs' may 
+also be located here temporarily. 
+- 2. Include the 'Ucam_Webauth.vbs' class file in the 'head' of your ASP file:
+
+
+    <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <!--#include file="Ucam_Webauth.vbs"-->
+    </head>
+
+- 3. Set up the initial arguments for the 'Ucam_Webauth' class:
+
+```
+Set args = CreateObject("Scripting.Dictionary")
+args.Add "hostname", "localhost"
+args.Add "auth_service", "https://demo.raven.cam.ac.uk/auth/authenticate.html"
+args.Add "key_dir", "C:/Ucam_Webauth/certificates"
+```
+
+'args' is an associative array of *text* strings so parameter values must 
+be converted into strings, ie. numbers and booleans must be supplied within 
+quotes as in "23", "TRUE", "FALSE".
+A full list of allowed parameters is provided at the end of this README. 
+
+- 4. Create an instance of the 'Ucam_Webauth' class from within your ASP 
+server page and initialize with setup variables:
+
+```
+Set oUcam_Webauth = New Ucam_Webauth
+Call oUcam_Webauth(args)       
+```
+   
+- 5. Call 'Authenticate()' on the Ucam_Webauth object and act according to 
+the value returned:
+
+```
+       Select Case oUcam_Webauth.Authenticate()
+               
+               Case oUcam_Webauth.AUTHENTICATE_INCOMPLETE
+
+                       ...                     
+                       Exit Sub
+
+               Case oUcam_Webauth.AUTHENTICATE_COMPLETE_AUTHENTICATED          
+
+                       ...
+                                       
+               Case oUcam_Webauth.AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED              
+
+                       ...
+
+               Case oUcam_Webauth.AUTHENTICATE_COMPLETE_ERROR          
+
+                       ...
+                                       
+       End Select
+```
+
+The four possible return values of 'Authenticate()' are:
+
+- AUTHENTICATE_INCOMPLETE : The authentication process has yet to complete. 
+The user may have been redirected to the Raven server and has yet to enter 
+their login details.
+- AUTHENTICATE_COMPLETE_AUTHENTICATED : The authentication process completed 
+and the user has been successfully authenticated.
+- AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED : The authentication process 
+completed and the user was not successfully authenticated. 
+The user may have clicked 'Cancel' at the Raven server.
+- AUTHENTICATE_COMPLETE_ERROR : There was an error during the authentication 
+process forcing the authentication cycle to terminate early.
+
+As the 'Authenticate()' function may need to send HTTP headers, it must be 
+called before any output (e.g. HTML, HTTP headers) is sent to the browser.
+
+The 'Default.asp' file provided is a sample of a simple server page using 
+the 'Ucam_Webauth' VBScript class.
+
+Overview of Raven process
+-------------------------
+A diagram of the Raven authentication process is located within the 'docs' 
+folder as [I - Overview of Raven Authentication Process.pdf]. 
+
+The authentication cycle consists of the following key stages:
+
+#### User first tries to access authenticated page
+User tries to load an authenticated page on a particular website. 
+The 'Ucam_Webauth' class is loaded and the 'Authenticate()' function is called. 
+If no authentication cookie is found to indicate the user is authenticated, 
+the user's browser is redirected to a separate Raven server using a special 
+'Authentication Request'. The authentication request consists of a series of 
+authentication parameters encoded into the URL redirect as name/value pairs.
+
+#### User is prompted for login information
+The Raven server interprets the authentication request sent by the main 
+website and prompts the user for their username and password. The user may 
+then be successfully authenticated or may decide to click 'Cancel'. They are 
+redirected back to the main website with a series of 'Authentication Response' 
+parameters encoded into a 'WLS-Response' GET variable.
+
+#### User redirected back to main webserver
+The user's original page is loaded again and 'Authenticate()' is called a 
+second time. 'Ucam_Webauth' processes the new 'WLS-Response' GET value and, 
+if it's valid, sets an authentication cookie on the user's browser. The 
+user's original page is then loaded again. 
+
+#### User redirected back to main webserver again 
+With an authentication cookie now set, 'Authenticate()' checks the status 
+code contained in the value of the authentication cookie and returns either 
+'AUTHENTICATE_COMPLETE_AUTHENTICATED' or 
+'AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED'. If 
+'AUTHENTICATE_COMPLETE_AUTHENTICATED' is returned , the original page can 
+go on to display authenticated content to the user.
+
+Specifics of module
+-------------------
+The 'Authenticate()' function is the overarching authentication function of 
+'Ucam_Webauth'. It performs some basic sanity checks using 'CheckSetup()' 
+then uses 'GetCurrentState()' to establish the current state of the 
+authentication process before branching accordingly. The possible return 
+values of 'GetCurrentState()' are:
+
+#### STATE_NEW_AUTHENTICATION
+A completely fresh authentication. 'SendAuthenticationRequest()' [*1*] is 
+then triggered which performs some basic data checks, sets the authentication 
+cookie to 'AUTHENTICATIONCOOKIE_REDIRECT_WLS' (to record where we are in the 
+authentication process) and redirects the user's browser to the Raven 
+authentication server with a series of authentication parameters 
+encoded as name/value pairs.
+
+#### STATE_WLS_RESPONSE_RECEIVED
+The Raven authentication server has processed the user and has returned the 
+user's browser back to the original website with a series of authentication 
+response parameters encoded into the 'WLS-Response' GET variable. 
+'ProcessAuthenticationResponse()' [*2*] is then called which checks the 
+validity of the 'WLS-Response' value, sets an authentication cookie and 
+redirects the user back to the original page.
+
+#### STATE_WAA_AUTHENTICATIONCOOKIE_SET
+A valid authentication cookie has been set 
+(<> AUTHENTICATIONCOOKIE_REDIRECT_WLS). 
+'ProcessAuthenticationCookie()' [*3*] is then called which checks the 
+validity of the cookie. If the cookie has expired, 
+'SendAuthenticationRequest()' is called again in case the user needs to 
+reauthenticate themselves. If the cookie is still valid, an 
+'AUTHENTICATE_COMPLETE_XXX' value is returned, indicating that the 
+authentication cycle has completed successfully. 
+NOTE: this may be true if the user has cancelled the authentication process, 
+in which case 'AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED' will be returned.
+
+#### STATE_ERROR
+An error occurred, breaking the authentication cycle and returning 
+AUTHENTICATE_COMPLETE_ERROR to 'Authenticate()'. This return value will 
+also be generated by the other functions above if they generate an error.
+
+## Accompanying diagrams
+Detailed diagrams of the Raven process flow for (i) a successful 
+authentication (ii) a cancelled authentication, are located in the 'docs' 
+folder as [II - Ucam_Webauth - Flowchart for Valid Authentication.pdf] and 
+[III - Ucam_Webauth - Flowchart for Cancelled Authentication.pdf], respectively. 
+
+The numbers on these diagrams correspond to the three key secondary functions 
+described above:
+- *1*. SendAuthenticationRequest()
+- *2*. ProcessAuthenticationResponse()
+- *3*. ProcessAuthenticationCookie()
+
+Other important functions include:
+
+### ResetState()
+Attempts to reset state as if a new user has just loaded a fresh browser 
+window. This is typically used when a user has experienced an error and we 
+want to give them a fresh opportunity to try again. 
+
+### check_signature(...)
+Checks the signature provided by the Raven server, when it signed the 
+'WLS-Response' variable, is a valid signature for the data. This ensures the 
+data has not been tampered with.
+
+### hmac_sha1(...)
+Creates a hash value for signing the local authentication cookie.
+
+### wls_encode/decode(...)
+Encoding/decoding functions to allow base64 signatures to be sent within URLs.
+
+Possible arguments to 'Ucam_Webauth'
+------------------------------------
+(Based on documentation for PHP Raven authentication module)
+
+- log_file : 
+The location for a log file that will record progress and track possible 
+errors. The folder containing the file must be read/writable by the webserver.
+Default: log.txt
+
+- response_timeout : 
+Responses from the central authentication server are time-stamped. 
+This parameter sets the period of time in seconds during which these 
+responses are considered valid. 
+Default: 30 seconds.
+
+- key_dir : 
+The name of the directory containing the public key certificate(s) required 
+to validate the authentication responses sent by the server. 
+Default: '/etc/httpd/conf/webauth_keys'.
+
+- max_session_life : 
+The maximum period of time in seconds for which an established session will 
+be valid. This may be overriden if the authentication reply contains a 
+shorter 'life' parameter. Note that this does NOT define an expiry time for 
+the session cookie. Session cookies are always set without an expiry time, 
+causing them to expire when the browser session finishes. 
+Default: 7200 (2 hours).
+
+- timeout_message : 
+A re-authentication by the authentication service will be triggered when an 
+established session expires. This option sets a text string which is sent to 
+the authentication server to explain to the user why they are being asked to 
+authenticate again. HTML markup is suppressed as for the description 
+parameter described below. 
+Default: 'your login to the site has expired'.
+
+- hostname (required) :
+The fully-qualified TCP/IP hostname that should be used in request URLs 
+referencing the Ucam_Webauth-enabled application. This *must* be set, as it 
+is needed for multiple reasons - primarily security but also to avoid varying 
+hostnames in URLs leading to failed or inconsistent authentication. 
+No default.
+
+- cookie_key (required): 
+A random key used to protect session cookies from tampering. Any reasonably 
+unpredictable string (for example the MD5 checksum of a rapidly changing 
+logfile) will be satisfactory. This key must be the same for all uses of the 
+web authentication system that will receive the same session cookies (see the 
+cookie_name, cookie_path and cookie_domain parameters below). 
+No default.
+
+- cookie_name :
+The name used for the session cookie. 
+When used for access to resources over HTTPS the string '-S' is appended to 
+this name. 
+Default: 'Ucam-Webauth-Session'.
+
+- cookie_path :
+The 'Path' attribute for the session cookie. The default is the directory 
+component of the path to the script currently being executed. This should 
+result in the cookie being returned for future requests for this script and 
+for the other resources in the same 'directory'; see the important 
+information about the cookie_key parameter above. 
+Default: '/'.
+
+- cookie_domain :
+The 'Domain' attribute for the session cookie. By default the 'Domain' 
+attribute is omitted when setting the cookie. This should result in the 
+cookie being returned only to the server running the script. Be aware that 
+some people may treat with suspicion cookies with domain attributes that are 
+wider than the host setting the cookie. 
+No default.
+
+- auth_service : The full URL for the web login service to be used. 
+Default: 'https://raven.cam.ac.uk/auth/authenticate.html' 
+
+#### Authentication request properties
+The following setup parameters prefixed with 'authrequest_' relate to 
+properties that will be sent to the authentication server as part of an 
+authentication request:
+
+- authrequest_desc : A text description of the resource that is requesting 
+authentication. This may be displayed to the user by the authentication 
+service. It is restricted to printable ASCII characters (0x20 - 0x7e) though 
+it may contain HTML entities representing other characters. The characters 
+'<' and '>' will be converted into HTML entities before being sent to the 
+browser and so this text cannot usefully contain HTML markup.
+No default.
+
+- authrequest_params : Data that will be returned unaltered to the WAA in 
+any 'authentication response message' issued as a result of this request. 
+This could be used to carry the identity of the resource originally requested 
+or other WAA state, or to associate authentication requests with their 
+eventual replies. When returned, this data will be protected by the digital 
+signature applied to the authentication response message but nothing else is 
+done to ensure the integrity or confidentiality of this data - the WAA MUST 
+take responsibility for this if necessary.
+No default.
+
+- authrequest_skew : Interpretation of response_timeout is difficult if the 
+clocks on the server running the PHP agent and on the authentication server 
+are out of step. Both servers should use NTP to synchronize their clocks, 
+but if they don't then this parameter should be set to an estimate of the 
+maximum expected difference between them (in seconds). 
+Default: 0.
+
+- authrequest_fail :
+If TRUE, sets the fail parameter in any authentication request sent to the 
+authentication server to 'yes'. This has the effect of requiring the 
+authentication server itself to report any errors that it encounters, rather 
+than returning an error indication. Note however that even with this parameter 
+set errors may be detected by this module that will result in authentication 
+failing here. 
+Default: FALSE.
+
+- authrequest_iact :
+If TRUE, then the 'iact' parameter provided to the authentication server is 
+set to 'yes'. If FALSE, then the 'iact' parameter is set to 'no'. If no value 
+is provided for 'authrequest_iact', the 'iact' parameter is left blank. 
+The value 'yes' for 'iact' requires that a re-authentication exchange takes 
+place with the user. This could be used prior to a sensitive transaction in 
+an attempt to ensure that a previously authenticated user is still present 
+at the browser. The value 'no' requires that the authentication request will 
+only succeed if the user's identity can be returned without interacting with 
+the user. This could be used as an optimisation to take advantage of any 
+existing authentication but without actively soliciting one. If omitted or 
+empty, then a previously established identity may be returned if the WLS 
+supports doing so, and if not then the user will be prompted as necessary.
 Default: omitted.
\ No newline at end of file