PrivateTutorial.html

   1 <html>
   2 <head>
   3         <title>Tutorial: How to set up login accounts</title>
   4 </head>
   5 <body>
   6 <p>
   7 <table width='100%'><tr>
   8         <td style='text-align: left'><a href="/index.html">Home</a></td>
   9         <td style='text-align: right'><a href="/Private/index.html?LOGOUT">Logout</a></td>
  10 </tr></table>
  11 </p>
  12 <h1 style="text-align: Center">Tutorial: How to set up login accounts</h1>
  13         <h3 style="text-align: Center">WARNING</h3>
  14         <p style="margin-left: 20%; margin-right: 20%; text-align: justified;font-style: italic">
  15         The current implementation of an authenticating and authorization procedure
  16         (Password Login) in <em>CGIscriptor.pl</em> is experimental and meant as an illustration
  17         for the use of the framework. The code has not been reviewed. <br />
  18         Before you use this procedure on your site, be sure you understand the limitations of the
  19         implemented procedures. You should evaluate first whether the procedures address your
  20         security needs and second whether the code implements the procedures correctly.
  21         </p>
  22
  23
  24 <h2 style="text-align: Center">Introduction</h2>
  25 <p style="text-align: Left">
  26         In situations where pages and services must be limited to authorized
  27         persons, it is possible to activate a login procedure when a certain page
  28         or url is requested. The authentication is done by requesting a user
  29         name and a password. The server stores information about the passwords
  30         and privileges of individual users.
  31 </p>
  32 <p style="text-align: Left">
  33         The method used to authorize requests is a server side session ticket.
  34         The client (user) browser will send an identifier token that is compared
  35         with the expected identifier. Only if the token is accepted, will the
  36         requested page be processed and send to the client. Identifier tokens
  37         can be send as cookies or as CGI variables. There is no difference
  38         between these two methods. If possible, use cookies as they are more
  39         convenient. Note that the ticket identifiers rely on the use of
  40         <a href="http://www.xul.fr/en/html5/sessionstorage.php">browser
  41         SessionStorage</a>. If the browsers of clients do not support
  42         <a href="http://www.xul.fr/en/html5/sessionstorage.php">browser
  43         SessionStorage</a>, your choices will be limited.
  44 </p>
  45
  46 <h2 style="text-align: Center">How to protect services with a password login</h2>
  47 <p style="text-align: Left">
  48         The variable <em>%TicketRequiredPatterns</em> contains a set of URL patterns that
  49         should be protected by a password login. Each pattern points to a
  50         directory where login sessions are stored (<tt>Private/.Sessions</tt>),
  51         account information (<tt>Private/.Passwords</tt>), the login page
  52         that should be shown for that URL (<tt>Private/Login.html</tt>),
  53         and finaly the default expire time for a session (<tt>+36000</tt>,
  54         i.e., 36 thousand seconds = 10 hours).
  55 <pre>
  56 # File patterns of files which are handled by session tickets.
  57 %TicketRequiredPatterns = (
  58 '^/Private(/|$)' => "Private/.Sessions\tPrivate/.Passwords\t/Private/Login.html\t+36000"
  59 );
  60 </pre>
  61 </p>
  62
  63 <h2 style="text-align: Center">Session types</h2>
  64
  65 <p style="text-align: Left">
  66         Security comes with costs attached. The more stringent the authentication should
  67         be, the more complex the authentication process will have to be. To allow a meaningful
  68         tradeof between security and costs, three levels of authentication are implemented.
  69 </p>
  70 <p style="text-align: Left">
  71         <ol>
  72                 <li>IPADDRESS: Remote client IP address<br />
  73                         Use the (apparent) IP address of the client as an identification.
  74                         Simple and not secure
  75                 </li>
  76                 <li>SESSION: Single session token<br />
  77                         Create a single token that the client can use during the session.
  78                         But also use the IP address. Relatively straightforeward and reasonably
  79                         secure.
  80                 </li>
  81                 <li>CHALLENGE: One time session tokens<br />
  82                         The client has to generate a new token for every request. Each token
  83                         can be used only once. The new token is constructed from a random
  84                         string send from the server and the stored password. This can be used
  85                         to prevent session hijacking by a third party who can simulate the same
  86                         IP address, or if the IP address is not fixed, e.g., when using Tor.
  87                 </li>
  88         </ol>
  89         It is adviced to use the SESSION (single session token) type unless there are
  90         specific reasons to increase security, eg, for the admin acount or Tor sessions.
  91 </p>
  92
  93 <h2 style="text-align: Center">Password account tickets</h2>
  94
  95 <p style="text-align: Left">
  96 This is an annotated example of a PASSWORD account ticket. At the right hand side is the literal text as present in the Account file.
  97 All regex patterns are <a href="http://www.regular-expressions.info/perl.html">Perl regex patterns</a>.
  98 </p>
  99 <p>
 100 <table>
 101 <tr><td style="text-align: Right">The type of the ticket</td><td>&nbsp;</td><td><tt>Type: PASSWORD</tt></td></tr>
 102 <tr><td style="text-align: Right">Official username, lowercase</td><td>&nbsp;</td><td><tt>Username: testchallenge</tt></td></tr>
 103 <tr><td style="text-align: Right">Hashed and encrypted password</td><td>&nbsp;</td><td><tt>Password: 6df7d66e8832ee52a9aba5e474ce8641a9577eff140d54b297b61443bf8d9eb1</tt></td></tr>
 104 <tr><td style="text-align: Right">Allowed IP addresses, a regex pattern</td><td>&nbsp;</td><td><tt>IPaddress: 127.0.0.1</tt></td></tr>
 105 <tr><td style="text-align: Right">Allowed paths in the web site, a regex pattern</td><td>&nbsp;</td><td><tt>AllowedPaths: ^/Private/index\.html$</tt></td></tr>
 106 <tr><td style="text-align: Right">idem</td><td>&nbsp;</td><td><tt>AllowedPaths: ^/Private/[^/]+\.html$</tt></td></tr>
 107 <tr><td style="text-align: Right">idem</td><td>&nbsp;</td><td><tt>AllowedPaths: ^/Private/?$</tt></td></tr>
 108 <tr><td style="text-align: Right">Privileges, in this case allowed to hop proxies</td><td>&nbsp;</td><td><tt>Capabilities: VariableREMOTE_ADDR</tt></td></tr>
 109 <tr><td style="text-align: Right">The server salt used to hash the password</td><td>&nbsp;</td><td><tt>Salt: e93cf858a1d5626bf095ea5c25df990dfa969ff5a5dc908b22c9a5229b525f65</tt></td></tr>
 110 <tr><td style="text-align: Right">Allowed session type</td><td>&nbsp;</td><td><tt>Session: CHALLENGE</tt></td></tr>
 111 <tr><td style="text-align: Right">A signature of important aspects of this ticket</td><td>&nbsp;</td><td><tt>Signature: eca5b95e3ff4a9628be4c6f1fca29ec2f5981cbbba0b29ce5b601055926a8720</tt></td></tr>
 112 <tr><td style="text-align: Right">Maximum lifetime of a session, 45 minutes</td><td>&nbsp;</td><td><tt>MaxLifetime: +45m</tt></td></tr>
 113 <tr><td style="text-align: Right">Creation date and time</td><td>&nbsp;</td><td><tt>Date: Fri Jun 29 12:46:22 2012</tt></td></tr>
 114 <tr><td style="text-align: Right">Creation time in seconds of epoch</td><td>&nbsp;</td><td><tt>Time: 1340973982</tt></td></tr>
 115 </table>
 116 The above account contains a contradiction. Although it has <em></em>Capabilities: VariableREMOTE_ADDR</em>,
 117 it is also limited to the local machine, <em>IPaddress: 127.0.0.1</em> (IPaddress is matched from the start).
 118 The default account in this example has been locked down for distribution. Shipping a default account that
 119 could be accessed from the outside would be a security hazard. You are adviced to change the
 120 password before you change any of the default accounts.
 121 </p>
 122 <p>
 123 An example <em>Create User Account</em> page is added. When logged in as any user, you can go to this
 124 page and enter your own password (the one you used to log in), the user name, and password of the new
 125 user. Below that, the allowed pages and IP addresses can be entered as a <em>;</em> separated list of
 126 regular expression patterns. After sumitting the form, the text of the account file will be printed
 127 on the page. These texts can be saved in the <em>.Passwords</em> directory.
 128 However, if the <em>admin</em> account is activated, that user can create active new accounts directly.
 129 With each new user, a home directory is automatically created as a copy of the
 130 <em>Private/.SkeletonDir</em> directory.
 131 </p>
 132
 133 <h2 style="text-align: Center">Account signatures and activation</h2>
 134
 135 <p style="text-align: Left">
 136         Reading the passwords or any change in the account files by other users of the servers could
 137         lead to a compromize of the system. Therefore, it is possible to encrypt passwords and sign
 138         accounts (and session tickets). If the web server supports an environment variable with the
 139         name <em>CGIMasterKey</em> (<em>$ENV{CGIMasterKey}</em>), the value of that variable will be used as
 140         a pass phrase. <em>$ENV{CGIMasterKey}</em> will be used to encrypt the password and create
 141         a signature of the account and session tickets. Any account or session ticket with an
 142         invalid signature will be discarded. Both the encryption keys and the signatures will be
 143         constructed from the server side salt and the user name. This means that if you change the
 144         server side salt or CGIMasterKey, you will have to reset all passwords and recreate all
 145         signatures.
 146 </p>
 147 <p style="text-align: Left">
 148         Activating an account means that the password is set and a correct signature is created.
 149         Setting passwords and generating signatures can be done with <em>CGIscriptor.pl</em> on the command line.
 150         The following command will set a new password and signature for the testchallenge account:<br /><tt>
 151         perl CGIscriptor.pl --managelogin salt=Private/.Passwords/SALT
 152         masterkey='Sherlock investigates oleander curry in Bath'
 153         password='testing' Private/.Passwords/testchallenge
 154         </tt><br />
 155         Note that the creation time of the account (if present) will be part
 156         of the signature. This will make that every new account file will have a
 157         unique signature. Even if all the other contents are the same. The password
 158         is <em>not</em> part of the signature, nor are any comments.
 159 </p>
 160 <p style="text-align: Left">
 161         There are four default accounts present: <em>testip, test, testchallenge</em>, and
 162         <em>admin</em>. The former three have password <em>testing</em>, the latter has password
 163         <em>There is no password like more password</em>. The <em>admin</em>
 164         account is disabled by default. You can enable it with a new password
 165         using the <tt>--managelogin</tt> option. All four accounts are limited to local
 166         (<em>localhost</em>) requests. When present, <em>testip, test</em>, and
 167         <em>testchallenge</em> are reactivated with the default password <em>testing</em>
 168         whenever a new SALT is automatically generated. It is adviced that the <em>test</em>
 169         accounts are removed when setting up a site.
 170 </p>
 171
 172 <h2 style="text-align: Center">Creating web pages</h2>
 173 <p style="text-align: Left">
 174         <em>IPADDRESS</em> and <em>SESSION</em>type sessions do not require
 175         any changes in web pages after login. <em>CHALLENGE</em> type sessions
 176         require JavaScript code on every single protected page (actually, only
 177         to get to the next page after that). Use of the <em>back</em> button
 178         is not possible in <em>CHALLENGE</em> type sessions. To add support
 179         for the login sessions to simple web pages, add the following code
 180         to the HEAD section of each HTML file:
 181 </p>
 182 <pre>
 183 &lt;script type="text/javascript"&gt;
 184 &lt;SCRIPT TYPE="text/ssperl" SRC="./JavaScript/PlainPage.js"&gt;&lt;/SCRIPT&gt;
 185 &lt;/script&gt;
 186 </pre>
 187 <p style="text-align: Left">
 188         Pages that require a user to enter username or password require special
 189         <em>window.onload</em> code as well as special <em>onSubmit</em> code
 190         for the FORM fields, eg, <em>LoginSubmit()</em>,
 191         <em>ChangePasswordSubmit ()</em>, and <em>CreateUserSubmit ()</em>.
 192         For the Login page, change <em>PlainPage.js</em> into <em>LoginPage.js</em>
 193         in the above code snippet.
 194         For Change Password and Create User use, respectively, <em>ChangePasswordPage.js</em>
 195         and <em>CreateUserPage.js</em>. The following FORM ID and CGI parameter
 196         names should be used (FORM element ID):
 197         <ul>
 198         <li>CGIUSERNAME<br />
 199         The account name of the current user (also if hidden)</li>
 200         <li>NEWUSERNAME<br />
 201         The new account name when creating a user</li>
 202         <li>PASSWORD<br />
 203         The password. Password visibility can be toggled with<br />
 204         <em>onClick="this.value=togglePasswords('Hide', 'Show', this.value);true"</em></li>
 205         <li>NEWPASSWORD<br />
 206         The new password for Change Password or Create User</li>
 207         <li>NEWPASSWORDREP<br />
 208         Repetition of the new password for Change Password or Create User.
 209         <em>onChange='check_password_fields()'</em> will check whether both
 210         fields are identical and set the Submit button</li>
 211         <li>SUBMIT<br />
 212         ID of the Submit button, used to grey out the button until all fields
 213         are entered
 214         </li>
 215         </li>
 216         <li>LOGINTICKET<br />
 217         Sending the login ticket when entering a password. Should not be changed by the user</li>
 218         <li>CLIENTIPADDRESS<br />
 219         A text input field containing the IP address of the client as seen by the server, i.e., $REMOTE_HOST.
 220         Will be used to generate the LOGINTICKET above. Can be outside of the proper FORM,
 221         the server will set it, but ignores it when send.
 222         </li>
 223         </ul>
 224         FORM ID and CGI parameter names that are optional as they are set by the server
 225         and also exchanged by cookies. All contain server generated hexadecimal hashes.
 226         Use the FORM ID versions when you use form fields instead of cookies:
 227         <ul>
 228         <li>SERVERSALT</li>
 229         <li>RANDOMSALT</li>
 230         <li>SESSIONTICKET</li>
 231         <li>CHALLENGETICKET</li>
 232         </ul>
 233
 234 </p>
 235 <p>
 236 In some cases it might be needed to defer setting the <em>SESSION</em>
 237 cookie at the login submit to the landing page. To achieve this, remove
 238 <em>setSessionParameters();true</em> from the onSubmit function in the
 239 Login.html page:
 240 <pre>
 241 onSubmit='LoginSubmit();setSessionParameters();true'
 242 </pre>
 243 should become:
 244 <pre>
 245 onSubmit='LoginSubmit()'
 246 </pre>
 247
 248 In those cases you will have to add
 249 JavaScript code to the first page after the login.
 250 </p>
 251 </body>
 252 </html>
 253