X-Git-Url: https://git.uis.cam.ac.uk/x/uis/raven/abandoned/asp.git/blobdiff_plain/40f5cb1123dbf48301aaf1b2f0a26a020376372d..HEAD:/README.md diff --git a/README.md b/README.md index 86cfe2f..213ecd3 100644 --- a/README.md +++ b/README.md @@ -1,396 +1,401 @@ -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: - -``` - - - - - -``` - -- 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. +WARNING: THIS SOFTWARE IS UNSUPPORTED AND HAS A SECURITY PROBLEM - DO NOT USE WITHOUT MODIFICATION +========================================================================= + +This code has a path traversal vulnerability, and needs updating to +validate the new, stricter definition of the "kid" field (1-8 digits, +not beginning '0'). **Do not use it** without fixing this issue. If +you do fix this issue, please email raven-support@ucs.cam.ac.uk your +patch ;-) + +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/](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/](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](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/](https://raven.cam.ac.uk/project/keys/) +to verify authentication responses. Download the certificate from +[https://raven.cam.ac.uk/project/keys/](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/](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: + + + + + + + +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