+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
+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/.
+'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/.
+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
- [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.
+- 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
---------------------
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
+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/ 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.
+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.
+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:
+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
Getting started
---------------
-The 'Ucam_Webauth' VBScript class must be used within an ASP server-side page
+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:
+'Ucam\_Webauth' VBScript class:
-1. Ensure the 'Ucam_Webauth.vbs' class file and the folder 'js' are in the
+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>
+ <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
+
+ 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)
-```
+ 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()
+ Select Case oUcam_Webauth.Authenticate()
- Case oUcam_Webauth.AUTHENTICATE_INCOMPLETE
+ Case oUcam_Webauth.AUTHENTICATE_INCOMPLETE
- ...
- Exit Sub
+ ...
+ Exit Sub
- Case oUcam_Webauth.AUTHENTICATE_COMPLETE_AUTHENTICATED
+ Case oUcam_Webauth.AUTHENTICATE_COMPLETE_AUTHENTICATED
- ...
+ ...
- Case oUcam_Webauth.AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED
+ Case oUcam_Webauth.AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED
- ...
+ ...
- Case oUcam_Webauth.AUTHENTICATE_COMPLETE_ERROR
+ Case oUcam_Webauth.AUTHENTICATE_COMPLETE_ERROR
- ...
+ ...
- End Select
-```
+ End Select
-The four possible return values of 'Authenticate()' are:
+ The four possible return values of 'Authenticate()' are:
-- AUTHENTICATE_INCOMPLETE : The authentication process has yet to complete.
+ - 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
+ - AUTHENTICATE\_COMPLETE\_AUTHENTICATED : The authentication process completed
and the user has been successfully authenticated.
-- AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED : The authentication process
+ - 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
+ - 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
+ 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 'Default.asp' file provided is a sample of a simple server page using
the 'Ucam_Webauth' VBScript class.
Overview of Raven process
#### 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
+'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
authentication process before branching accordingly. The possible return
values of 'GetCurrentState()' are:
-#### STATE_NEW_AUTHENTICATION
+#### 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
+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
+#### 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.
validity of the 'WLS-Response' value, sets an authentication cookie and
redirects the user back to the original page.
-#### STATE_WAA_AUTHENTICATIONCOOKIE_SET
+#### STATE\_WAA\_AUTHENTICATIONCOOKIE\_SET
A valid authentication cookie has been set
-(<> AUTHENTICATIONCOOKIE_REDIRECT_WLS).
+(<> 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
+'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.
+in which case 'AUTHENTICATE\_COMPLETE\_NOT\_AUTHENTICATED' will be returned.
-#### STATE_ERROR
+#### STATE\_ERROR
An error occurred, breaking the authentication cycle and returning
-AUTHENTICATE_COMPLETE_ERROR to 'Authenticate()'. This return value will
+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.
+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:
responses are considered valid.
Default: 30 seconds.
-- key_dir :
+- 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'.
+Default: '/etc/httpd/conf/webauth\_keys'.
-- max_session_life :
+- 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
hostnames in URLs leading to failed or inconsistent authentication.
No default.
-- cookie_key (required):
+- 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).
+cookie\_name, cookie\_path and cookie\_domain parameters below).
No default.
- cookie_name :
this name.
Default: 'Ucam-Webauth-Session'.
-- cookie_path :
+- 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.
+information about the cookie\_key parameter above.
Default: '/'.
- cookie_domain :
take responsibility for this if necessary.
No default.
-- authrequest_skew : Interpretation of response_timeout is difficult if the
+- 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
failing here.
Default: FALSE.
-- authrequest_iact :
+- 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.
+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
/ uis / git / x / uis / raven / abandoned / asp.git / blobdiff