Add a warning about the security hole :-(
[raven/abandoned/asp.git] / README.md
CommitLineData
61f4932b
MV
1WARNING: THIS SOFTWARE IS UNSUPPORTED AND HAS A SECURITY PROBLEM - DO NOT USE WITHOUT MODIFICATION
2=========================================================================
3
4This code has a path traversal vulnerability, and needs updating to
5validate the new, stricter definition of the "kid" field (1-8 digits,
6not beginning '0'). **Do not use it** without fixing this issue. If
7you do fix this issue, please email raven-support@ucs.cam.ac.uk your
8patch ;-)
9
2ffb56d1
MV
10University of Cambridge Classic ASP/VBScript Raven Authentication Module - v.1.0 (29/04/2014)
11==========================================================================
12
13Description
14-----------
56bfe1a7 15This software comprises a VBScript class 'Ucam\_Webauth' and sample
2ffb56d1
MV
16files that provide a Classic ASP/VBScript implementation of a 'Raven'
17authentication module; Raven is the web authentication protocol used
18by the University of Cambridge, UK. The logic and code of the
56bfe1a7 19'Ucam\_Webauth' class are loosely based on the PHP Raven authentication
f3a5461b 20class provided at [http://raven.cam.ac.uk/project/](http://raven.cam.ac.uk/project/).
2ffb56d1 21- For a full description of the latest Raven specification and an explanation
f3a5461b 22of how Raven works, go to [http://raven.cam.ac.uk/project/](http://raven.cam.ac.uk/project/).
2ffb56d1
MV
23- This software was originally created for the Careers Service,
24University of Cambridge by sh801@cam.ac.uk. For support, please
25contact raven-support@ucs.cam.ac.uk
26
27Files and folders
28-----------------
29- [certificates]: Temporary location for Raven public key certificates.
30- [js]: Folder containing Javascript cryptography libraries.
31- [docs]: Supporting documentation.
32- [logs]: Possible location for log files created by the module.
33- Default.asp: A sample file showing how the 'Ucam_Webauth' class is used
34to provide Raven authentication.
56bfe1a7
MV
35- Test.asp: A test file for unit testing the 'Ucam\_Webauth' module using the
36'Ucam\_RavenWLS' dummy Raven server (separate project, not included).
37- Ucam\_Webauth.vbs: The main 'Ucam\_Webauth' VBScript class.
2ffb56d1
MV
38
39Platform requirements
40---------------------
41This module has been tested on IIS7 with .NET Framework set to
42'No managed code', ie. classic ASP.
43
44Installation
45------------
46### Cryptographic functions
f3a5461b
MV
47Cryptographic functions are provided by the Javascript libraries
48within the 'js' folder. These libraries are versions of the
49client-side Javascript libraries provided at
50[http://kjur.github.io/jsrsasign/index.html](http://kjur.github.io/jsrsasign/index.html)
51but modified to run server-side. There is no need to install any
2ffb56d1
MV
52additional cryptography libraries.
53
54### Install Raven certificates
f3a5461b
MV
55The authentication module uses the Raven public key certificate at
56[https://raven.cam.ac.uk/project/keys/](https://raven.cam.ac.uk/project/keys/)
57to verify authentication responses. Download the certificate from
58[https://raven.cam.ac.uk/project/keys/](https://raven.cam.ac.uk/project/keys/)
59and copy to the 'certificates' folder provided with this
60authentication module download - the 'certificates' folder is a
61temporary location for the certificate while you get the module up and
62running. You will need to supply the full path to the 'certificates'
56bfe1a7
MV
63folder as either a 'key\_dir' argument to the 'Ucam\_Webauth'
64constructor or by modifying the 'Ucam\_Webauth' variable
65'DEFAULT\_KEY\_DIR' directly.
2ffb56d1
MV
66
67Once you have everything working, move the 'certificates' folder
68to a new location on your webserver that is not web- or publicly-accessible
56bfe1a7 69and modify the 'key\_dir' string accordingly.
2ffb56d1
MV
70
71- NOTE: you may have to change the name of the key file from 'pubkey2.crt'
72to '2.crt'.
73
f3a5461b
MV
74If you're using the Raven test server
75([http://raven.cam.ac.uk/project/test-demo/](http://raven.cam.ac.uk/project/test-demo/))
76for testing purposes, make sure you install the test server keys
77instead, but ensure you remove these keys before using the
78authentication module in a production environment, as recommended by
79the demo Raven server:
2ffb56d1
MV
80
81> It is vital to keep these demo keys seperate from keys
82> used with a production service - failure to do so could
83> allow an attacker to successfully replay a response
84> from the demonstration server, which anyone can easily
85> obtain, against a production service.
86
87Getting started
88---------------
89
56bfe1a7 90The 'Ucam\_Webauth' VBScript class must be used within an ASP server-side page
2ffb56d1 91as it interacts directly with a user's browser session. To use the
56bfe1a7 92'Ucam\_Webauth' VBScript class:
2ffb56d1 93
56bfe1a7 941. Ensure the 'Ucam\_Webauth.vbs' class file and the folder 'js' are in the
2ffb56d1
MV
95same directory as your ASP script. The folders 'certificates' and 'logs' may
96also be located here temporarily.
087f7f48 972. Include the 'Ucam_Webauth.vbs' class file in the 'head' of your ASP file:
2ffb56d1
MV
98
99
17d19429
MV
100 <head>
101 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
102 <!--#include file="Ucam_Webauth.vbs"-->
103 </head>
2ffb56d1 104
087f7f48 1053. Set up the initial arguments for the 'Ucam_Webauth' class:
d3465de2 106
9541b2dd
MV
107 Set args = CreateObject("Scripting.Dictionary")
108 args.Add "hostname", "localhost"
109 args.Add "auth_service", "https://demo.raven.cam.ac.uk/auth/authenticate.html"
110 args.Add "key_dir", "C:/Ucam_Webauth/certificates"
2ffb56d1 111
0ec3b31c 112 'args' is an associative array of *text* strings so parameter values must
2ffb56d1
MV
113be converted into strings, ie. numbers and booleans must be supplied within
114quotes as in "23", "TRUE", "FALSE".
115A full list of allowed parameters is provided at the end of this README.
116
087f7f48 1174. Create an instance of the 'Ucam_Webauth' class from within your ASP
2ffb56d1
MV
118server page and initialize with setup variables:
119
17d19429
MV
120 Set oUcam_Webauth = New Ucam_Webauth
121 Call oUcam_Webauth(args)
2ffb56d1 122
087f7f48 1235. Call 'Authenticate()' on the Ucam_Webauth object and act according to
2ffb56d1
MV
124the value returned:
125
17d19429 126 Select Case oUcam_Webauth.Authenticate()
2ffb56d1 127
17d19429 128 Case oUcam_Webauth.AUTHENTICATE_INCOMPLETE
2ffb56d1 129
17d19429
MV
130 ...
131 Exit Sub
2ffb56d1 132
17d19429 133 Case oUcam_Webauth.AUTHENTICATE_COMPLETE_AUTHENTICATED
2ffb56d1 134
17d19429 135 ...
2ffb56d1 136
17d19429 137 Case oUcam_Webauth.AUTHENTICATE_COMPLETE_NOT_AUTHENTICATED
2ffb56d1 138
17d19429 139 ...
2ffb56d1 140
17d19429 141 Case oUcam_Webauth.AUTHENTICATE_COMPLETE_ERROR
2ffb56d1 142
17d19429 143 ...
2ffb56d1 144
17d19429 145 End Select
2ffb56d1 146
17d19429 147 The four possible return values of 'Authenticate()' are:
2ffb56d1 148
56bfe1a7 149 - AUTHENTICATE\_INCOMPLETE : The authentication process has yet to complete.
2ffb56d1
MV
150The user may have been redirected to the Raven server and has yet to enter
151their login details.
56bfe1a7 152 - AUTHENTICATE\_COMPLETE\_AUTHENTICATED : The authentication process completed
2ffb56d1 153and the user has been successfully authenticated.
56bfe1a7 154 - AUTHENTICATE\_COMPLETE\_NOT\_AUTHENTICATED : The authentication process
2ffb56d1
MV
155completed and the user was not successfully authenticated.
156The user may have clicked 'Cancel' at the Raven server.
56bfe1a7 157 - AUTHENTICATE\_COMPLETE\_ERROR : There was an error during the authentication
2ffb56d1
MV
158process forcing the authentication cycle to terminate early.
159
5f7b5b58 160 As the 'Authenticate()' function may need to send HTTP headers, it must be
2ffb56d1
MV
161called before any output (e.g. HTML, HTTP headers) is sent to the browser.
162
5f7b5b58 163 The 'Default.asp' file provided is a sample of a simple server page using
2ffb56d1
MV
164the 'Ucam_Webauth' VBScript class.
165
166Overview of Raven process
167-------------------------
168A diagram of the Raven authentication process is located within the 'docs'
169folder as [I - Overview of Raven Authentication Process.pdf].
170
171The authentication cycle consists of the following key stages:
172
173#### User first tries to access authenticated page
174User tries to load an authenticated page on a particular website.
175The 'Ucam_Webauth' class is loaded and the 'Authenticate()' function is called.
176If no authentication cookie is found to indicate the user is authenticated,
177the user's browser is redirected to a separate Raven server using a special
178'Authentication Request'. The authentication request consists of a series of
179authentication parameters encoded into the URL redirect as name/value pairs.
180
181#### User is prompted for login information
182The Raven server interprets the authentication request sent by the main
183website and prompts the user for their username and password. The user may
184then be successfully authenticated or may decide to click 'Cancel'. They are
185redirected back to the main website with a series of 'Authentication Response'
186parameters encoded into a 'WLS-Response' GET variable.
187
188#### User redirected back to main webserver
189The user's original page is loaded again and 'Authenticate()' is called a
190second time. 'Ucam_Webauth' processes the new 'WLS-Response' GET value and,
191if it's valid, sets an authentication cookie on the user's browser. The
192user's original page is then loaded again.
193
194#### User redirected back to main webserver again
195With an authentication cookie now set, 'Authenticate()' checks the status
196code contained in the value of the authentication cookie and returns either
56bfe1a7
MV
197'AUTHENTICATE\_COMPLETE\_AUTHENTICATED' or
198'AUTHENTICATE\_COMPLETE\_NOT\_AUTHENTICATED'. If
199'AUTHENTICATE\_COMPLETE\_AUTHENTICATED' is returned , the original page can
2ffb56d1
MV
200go on to display authenticated content to the user.
201
202Specifics of module
203-------------------
204The 'Authenticate()' function is the overarching authentication function of
205'Ucam_Webauth'. It performs some basic sanity checks using 'CheckSetup()'
206then uses 'GetCurrentState()' to establish the current state of the
207authentication process before branching accordingly. The possible return
208values of 'GetCurrentState()' are:
209
56bfe1a7 210#### STATE\_NEW\_AUTHENTICATION
2ffb56d1
MV
211A completely fresh authentication. 'SendAuthenticationRequest()' [*1*] is
212then triggered which performs some basic data checks, sets the authentication
56bfe1a7 213cookie to 'AUTHENTICATIONCOOKIE\_REDIRECT\_WLS' (to record where we are in the
2ffb56d1
MV
214authentication process) and redirects the user's browser to the Raven
215authentication server with a series of authentication parameters
216encoded as name/value pairs.
217
56bfe1a7 218#### STATE\_WLS\_RESPONSE\_RECEIVED
2ffb56d1
MV
219The Raven authentication server has processed the user and has returned the
220user's browser back to the original website with a series of authentication
221response parameters encoded into the 'WLS-Response' GET variable.
222'ProcessAuthenticationResponse()' [*2*] is then called which checks the
223validity of the 'WLS-Response' value, sets an authentication cookie and
224redirects the user back to the original page.
225
56bfe1a7 226#### STATE\_WAA\_AUTHENTICATIONCOOKIE\_SET
2ffb56d1 227A valid authentication cookie has been set
56bfe1a7 228(<> AUTHENTICATIONCOOKIE\_REDIRECT\_WLS).
2ffb56d1
MV
229'ProcessAuthenticationCookie()' [*3*] is then called which checks the
230validity of the cookie. If the cookie has expired,
231'SendAuthenticationRequest()' is called again in case the user needs to
232reauthenticate themselves. If the cookie is still valid, an
56bfe1a7 233'AUTHENTICATE\_COMPLETE\_XXX' value is returned, indicating that the
2ffb56d1
MV
234authentication cycle has completed successfully.
235NOTE: this may be true if the user has cancelled the authentication process,
56bfe1a7 236in which case 'AUTHENTICATE\_COMPLETE\_NOT\_AUTHENTICATED' will be returned.
2ffb56d1 237
56bfe1a7 238#### STATE\_ERROR
2ffb56d1 239An error occurred, breaking the authentication cycle and returning
56bfe1a7 240AUTHENTICATE\_COMPLETE\_ERROR to 'Authenticate()'. This return value will
2ffb56d1
MV
241also be generated by the other functions above if they generate an error.
242
243## Accompanying diagrams
244Detailed diagrams of the Raven process flow for (i) a successful
245authentication (ii) a cancelled authentication, are located in the 'docs'
56bfe1a7
MV
246folder as [II - Ucam\_Webauth - Flowchart for Valid Authentication.pdf] and
247[III - Ucam\_Webauth - Flowchart for Cancelled Authentication.pdf], respectively.
2ffb56d1
MV
248
249The numbers on these diagrams correspond to the three key secondary functions
250described above:
251- *1*. SendAuthenticationRequest()
252- *2*. ProcessAuthenticationResponse()
253- *3*. ProcessAuthenticationCookie()
254
255Other important functions include:
256
257### ResetState()
258Attempts to reset state as if a new user has just loaded a fresh browser
259window. This is typically used when a user has experienced an error and we
260want to give them a fresh opportunity to try again.
261
262### check_signature(...)
263Checks the signature provided by the Raven server, when it signed the
264'WLS-Response' variable, is a valid signature for the data. This ensures the
265data has not been tampered with.
266
267### hmac_sha1(...)
268Creates a hash value for signing the local authentication cookie.
269
270### wls_encode/decode(...)
271Encoding/decoding functions to allow base64 signatures to be sent within URLs.
272
273Possible arguments to 'Ucam_Webauth'
274------------------------------------
275(Based on documentation for PHP Raven authentication module)
276
277- log_file :
278The location for a log file that will record progress and track possible
279errors. The folder containing the file must be read/writable by the webserver.
280Default: log.txt
281
282- response_timeout :
283Responses from the central authentication server are time-stamped.
284This parameter sets the period of time in seconds during which these
285responses are considered valid.
286Default: 30 seconds.
287
56bfe1a7 288- key\_dir :
2ffb56d1
MV
289The name of the directory containing the public key certificate(s) required
290to validate the authentication responses sent by the server.
56bfe1a7 291Default: '/etc/httpd/conf/webauth\_keys'.
2ffb56d1 292
56bfe1a7 293- max\_session\_life :
2ffb56d1
MV
294The maximum period of time in seconds for which an established session will
295be valid. This may be overriden if the authentication reply contains a
296shorter 'life' parameter. Note that this does NOT define an expiry time for
297the session cookie. Session cookies are always set without an expiry time,
298causing them to expire when the browser session finishes.
299Default: 7200 (2 hours).
300
301- timeout_message :
302A re-authentication by the authentication service will be triggered when an
303established session expires. This option sets a text string which is sent to
304the authentication server to explain to the user why they are being asked to
305authenticate again. HTML markup is suppressed as for the description
306parameter described below.
307Default: 'your login to the site has expired'.
308
309- hostname (required) :
310The fully-qualified TCP/IP hostname that should be used in request URLs
311referencing the Ucam_Webauth-enabled application. This *must* be set, as it
312is needed for multiple reasons - primarily security but also to avoid varying
313hostnames in URLs leading to failed or inconsistent authentication.
314No default.
315
56bfe1a7 316- cookie\_key (required):
2ffb56d1
MV
317A random key used to protect session cookies from tampering. Any reasonably
318unpredictable string (for example the MD5 checksum of a rapidly changing
319logfile) will be satisfactory. This key must be the same for all uses of the
320web authentication system that will receive the same session cookies (see the
56bfe1a7 321cookie\_name, cookie\_path and cookie\_domain parameters below).
2ffb56d1
MV
322No default.
323
324- cookie_name :
325The name used for the session cookie.
326When used for access to resources over HTTPS the string '-S' is appended to
327this name.
328Default: 'Ucam-Webauth-Session'.
329
56bfe1a7 330- cookie\_path :
2ffb56d1
MV
331The 'Path' attribute for the session cookie. The default is the directory
332component of the path to the script currently being executed. This should
333result in the cookie being returned for future requests for this script and
334for the other resources in the same 'directory'; see the important
56bfe1a7 335information about the cookie\_key parameter above.
2ffb56d1
MV
336Default: '/'.
337
338- cookie_domain :
339The 'Domain' attribute for the session cookie. By default the 'Domain'
340attribute is omitted when setting the cookie. This should result in the
341cookie being returned only to the server running the script. Be aware that
342some people may treat with suspicion cookies with domain attributes that are
343wider than the host setting the cookie.
344No default.
345
346- auth_service : The full URL for the web login service to be used.
347Default: 'https://raven.cam.ac.uk/auth/authenticate.html'
348
349#### Authentication request properties
350The following setup parameters prefixed with 'authrequest_' relate to
351properties that will be sent to the authentication server as part of an
352authentication request:
353
354- authrequest_desc : A text description of the resource that is requesting
355authentication. This may be displayed to the user by the authentication
356service. It is restricted to printable ASCII characters (0x20 - 0x7e) though
357it may contain HTML entities representing other characters. The characters
358'<' and '>' will be converted into HTML entities before being sent to the
359browser and so this text cannot usefully contain HTML markup.
360No default.
361
362- authrequest_params : Data that will be returned unaltered to the WAA in
363any 'authentication response message' issued as a result of this request.
364This could be used to carry the identity of the resource originally requested
365or other WAA state, or to associate authentication requests with their
366eventual replies. When returned, this data will be protected by the digital
367signature applied to the authentication response message but nothing else is
368done to ensure the integrity or confidentiality of this data - the WAA MUST
369take responsibility for this if necessary.
370No default.
371
56bfe1a7 372- authrequest\_skew : Interpretation of response\_timeout is difficult if the
2ffb56d1
MV
373clocks on the server running the PHP agent and on the authentication server
374are out of step. Both servers should use NTP to synchronize their clocks,
375but if they don't then this parameter should be set to an estimate of the
376maximum expected difference between them (in seconds).
377Default: 0.
378
379- authrequest_fail :
380If TRUE, sets the fail parameter in any authentication request sent to the
381authentication server to 'yes'. This has the effect of requiring the
382authentication server itself to report any errors that it encounters, rather
383than returning an error indication. Note however that even with this parameter
384set errors may be detected by this module that will result in authentication
385failing here.
386Default: FALSE.
387
56bfe1a7 388- authrequest\_iact :
2ffb56d1
MV
389If TRUE, then the 'iact' parameter provided to the authentication server is
390set to 'yes'. If FALSE, then the 'iact' parameter is set to 'no'. If no value
56bfe1a7 391is provided for 'authrequest\_iact', the 'iact' parameter is left blank.
2ffb56d1
MV
392The value 'yes' for 'iact' requires that a re-authentication exchange takes
393place with the user. This could be used prior to a sensitive transaction in
394an attempt to ensure that a previously authenticated user is still present
395at the browser. The value 'no' requires that the authentication request will
396only succeed if the user's identity can be returned without interacting with
397the user. This could be used as an optimisation to take advantage of any
398existing authentication but without actively soliciting one. If omitted or
399empty, then a previously established identity may be returned if the WLS
400supports doing so, and if not then the user will be prompted as necessary.
f560b040 401Default: omitted.