Fix spurious italics
authorMatthew Vernon <mcv21@cam.ac.uk>
Thu, 15 Jan 2015 16:57:53 +0000 (16:57 +0000)
committerMatthew Vernon <mcv21@cam.ac.uk>
Thu, 15 Jan 2015 16:57:53 +0000 (16:57 +0000)
_foo_ in markdown makes _foo_ italic, so lots of _ need escaping

README.md

index fb4d8a3..89869ae 100644 (file)
--- a/README.md
+++ b/README.md
@@ -3,11 +3,11 @@ University of Cambridge Classic ASP/VBScript Raven Authentication Module - v.1.0
 
 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
+'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/).
@@ -23,9 +23,9 @@ Files and folders
 - [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
 ---------------------
@@ -51,13 +51,13 @@ 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.
+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'. 
@@ -78,11 +78,11 @@ the demo Raven server:
 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:
@@ -137,15 +137,15 @@ the value returned:
 
     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 
@@ -185,9 +185,9 @@ 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 
+'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
@@ -198,15 +198,15 @@ 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
+#### 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. 
@@ -214,28 +214,28 @@ 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:
@@ -276,12 +276,12 @@ This parameter sets the period of time in seconds during which these
 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 
@@ -304,12 +304,12 @@ 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): 
+- 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 :
@@ -318,12 +318,12 @@ When used for access to resources over HTTPS the string '-S' is appended to
 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 :
@@ -360,7 +360,7 @@ 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 
+- 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 
@@ -376,10 +376,10 @@ set errors may be detected by this module that will result in authentication
 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