Private/manual.html

   1 <html>
   2 <head>
   3 <title>
   4         Private data
   5 </title>
   6 <script type="text/javascript">
   7 <SCRIPT TYPE="text/ssperl" SRC="./JavaScript/CGIscriptorSession.js"></SCRIPT>
   8
   9 window.onload = function() {
  10         loadSessionData (CGIscriptorSessionType, CGIscriptorChallengeTicket);
  11         return true;
  12 };
  13 </script>
  14
  15 <script type="text/javascript">
  16 <SCRIPT TYPE="text/ssperl" SRC="./JavaScript/sha.js"></SCRIPT>
  17 </script>
  18 </head>
  19 <body>
  20 <p ALIGN=RIGHT><a href="?LOGOUT">Logout</a></p>
  21 <p ALIGN=RIGHT><a href="ChangePassword.html">Change Password</a><br />
  22 <a href="CreateUser.html">Create New User Account</a>
  23 </p>
  24 <h1 align=CENTER>Manual</h1>
  25 <p align=CENTER>Logged in from <script type="text/ssperl" CGI='$LOGINIPADDRESS="" $LOGINPATH=""'>"$LOGINIPADDRESS $LOGINPATH"</script></p>
  26 <p align=CENTER><form method=GET action="index.html">
  27         <p align=CENTER><input type="submit" value="Go back to home page" /></p>
  28         <input type="hidden" name="SESSIONTICKET" id="SESSIONTICKET" value="" />
  29         <input type="hidden" name="CHALLENGETICKET" id="CHALLENGETICKET" value="" /><br />
  30         </form>
  31         </p>
  32
  33
  34 <A NAME="SESSIONTICKETS"><H2 ALIGN="CENTER">SERVER SIDE SESSIONS AND ACCESS CONTROL (LOGIN)</H2></A>
  35 <p>
  36 An infrastructure for user acount authorization and file access control
  37 is available. Each request is matched against a list of URL path patterns.
  38 If the request matches, a Session Ticket is required to access the URL.
  39 This Session Ticket should be present as a CGI parameter or Cookie, eg:
  40 </p>
  41 <p>
  42 CGI: SESSIONTICKET=&lt;value&gt;<br />
  43 Cookie: CGIscriptorSESSION=&lt;value&gt;</p>
  44 <p>
  45 The example implementation stores Session Tickets as files in a local
  46 directory. To create Session Tickets, a Login request must be given
  47 with a LOGIN=&lt;value&gt; CGI parameter, a user name and a (doubly hashed)
  48 password. The user name and (singly hashed) password are stored in a
  49 PASSWORD ticket with the same name as the user account (name cleaned up
  50 for security).
  51 </p>
  52 <p>
  53 The example session model implements 3 functions:
  54 <ol>
  55 <li>Login<br />
  56 The password is hashed with the user name and server side salt, and then
  57 hashed with a random salt. Client and Server both perform these actions
  58 and the Server only grants access if restults are the same. The server
  59 side only stores the password hashed with the user name and
  60 server side salt. Neither the plain password, nor the hashed password is
  61 ever exchanged. Only values hashed with the one-time salt are exchanged.
  62 </li>
  63 <li>Session<br />
  64 For every access to a restricted URL, the Session Ticket is checked before
  65 access is granted. There are three session modes. The first uses a fixed
  66 Session Ticket that is stored as a cookie value in the browser (actually,
  67 as a sessionStorage value). The second uses only the IP address at login
  68 to authenticate requests. The third
  69 is a Challenge mode, where the client has to calculate the value of the
  70 next one-time Session Ticket from a value derived from the password and
  71 a random string.
  72 </li>
  73 <li>Password Change<br />
  74 A new password is hashed with the user name and server side salt, and
  75 then encrypted (XORed)
  76 with the old password hashed with the user name and salt. That value is
  77 exchanged and XORed with the stored old hashed(salt+password+username).
  78 Again, the stored password value is never exchanged unencrypted.
  79 </li>
  80 </ol>
  81 </p>
  82 <H3 ALIGN="CENTER">Implementation</H3>
  83 <p>
  84 The session authentication mechanism is based on the exchange of ticket
  85 identifiers. A ticket identifier is just a string of characters, a name
  86 or a random 64 character hexadecimal string. Ticket identifiers should be
  87 "safe" filenames (except user names). There are four types of tickets:
  88 <ul>
  89 <li>PASSWORD: User account descriptors, including a user name and password</li>
  90 <li>LOGIN: Temporary anonymous tickets used during login</li>
  91 <li>IPADDRESS: Authetication tokens that allow access based on the IP address of the request</li>
  92 <li>SESSION: Reusable authetication tokens</li>
  93 <li>CHALLENGE: One-time authetication tokens</li>
  94 </ul>
  95 All tickets can have an expiration date in the form of a time duration
  96 from creation, in seconds, minutes, hours, or days (<em>+duration</em>[smhd]).
  97 An absolute time can be given in seconds since the epoch of the server host.
  98 Note that expiration times of CHALLENGE authetication tokens are calculated
  99 from the last access time. Accounts can include a maximal lifetime
 100 for session tickets (MaxLifetime).
 101 </p>
 102 <p>
 103 A Login page should create a LOGIN ticket file locally and send a
 104 server specific salt, a Random salt, and a LOGIN ticket
 105 identifier. The server side compares the username and hashed password,
 106 actually hashed(Random salt+hashed(serversalt+password)) from the client with
 107 the values it calculates from the stored Random salt from the LOGIN
 108 ticket and the hashed(serversalt+password) from the PASSWORD ticket. If
 109 successful, a new SESSION ticket is generated as a hash sum of the LOGIN
 110 ticket and the stored password. This SESSION ticket should also be
 111 generated by the client and stored as sessionStorage and cookie values
 112 as needed. The Username, IP address and Path are available as
 113 $LoginUsername, $LoginIPaddress, and $LoginPath, respectively.
 114 </p>
 115 <p>
 116 The CHALLENGE protocol stores the same value as the SESSION tickets.
 117 However, this value is not exchanged, but kept secret in the JavaScript
 118 <em>sessionStorage</em> object. Instead, every page returned from the
 119 server will contain a one-time Challenge value ($CHALLENGETICKET) which
 120 has to be hashed with the stored value to return the current ticket
 121 id string.
 122 </p>
 123 <p>
 124 In the current example implementation, all random values are created as
 125 full, 256 bit SHA256 hash values (Hex strings) of 64 bytes read from
 126 /dev/urandom.
 127 </p>
 128
 129 <H3 ALIGN="CENTER">Security considerations with Session tickets</H3>
 130 <p>
 131 For strong security, please use end-to-end encryption. This can be
 132 achieved using a VPN (Virtual Private Network), SSH tunnel, or a HTTPS
 133 capable server with OpenSSL. The session ticket system of CGIscriptor.pl
 134 is intended to be used as a simple authentication mechanism WITHOUT
 135 END-TO-END ENCRYPTION. The authenticating mechanism tries to use some
 136 simple means to protect the authentication process from eavesdropping.
 137 For this it uses a secure hash function, SHA256. For all practial purposes,
 138 it is impossible to "decrypt" a SHA256 sum. But this login scheme is
 139 only as secure as your browser. Which, in general, is not very secure.
 140 </p>
 141 <p>
 142 Humans tend to reuse passwords. A compromise of a site running
 143 CGIscriptor.pl could therefore lead to a compromise of user accounts at
 144 other sites. Therefore, plain text passwords are never stored, used, or
 145 exchanged. Instead, a server site salt value is "encrypted" with
 146 the plain password and user name. Actually, all are concatenated and hashed
 147 with a one-way secure hash function (SHA256) into a single string.
 148 Whenever the word "password" is used, this hash sum is meant. Note that
 149 the salts are generated from /dev/urandom. You should check whether the
 150 implementation of /dev/urandom on your platform is secure before
 151 relying on it. This might be a problem when running CGIscriptor under
 152 Cygwin on MS Windows.<br />
 153 <em>Note: no attempt is made to slow down the password hash, so bad
 154 passwords can be cracked by brute force</em>
 155 </p>
 156 <p>
 157 As the (hashed) passwords are all that is needed to identify at the site,
 158 these should not be stored in this form. A site specific passphrase
 159 can be entered as an environment variable ($ENV{'CGIMasterKey'}). This
 160 phrase is hashed with the server site salt and the result is hashed with
 161 the user name and then XORed with the password when it is stored. Also, to
 162 detect changes to the account (PASSWORD) and session tickets, a
 163 (HMAC) hash of some of the contents of the ticket with the server salt and
 164 CGIMasterKey is stored in each ticket.
 165 </p>
 166 <p>
 167 Creating a valid (hashed) password, encrypt it with the CGIMasterKey and
 168 construct a signature of the ticket are non-trivial. This has to be redone
 169 with every change of the ticket file or CGIMasterKey change. CGIscriptor
 170 can do this from the command line with the command:
 171 <pre>
 172 perl CGIscriptor.pl --managelogin salt=Private/.Passwords/SALT \
 173   masterkey='Sherlock investigates oleander curry in Bath' \
 174   password='There is no password like more password' \
 175   admin
 176 </pre>
 177 CGIscriptor will exit after this command with the first option being
 178 <em>--managelogin</em>. Options have the form:
 179 <ul>
 180 <li>salt=[file or string]<br />Server salt value to use io the value
 181     stored in the ticket file. Will replace the stored value if a new
 182     password is given. If you change the server salt, you have to
 183     reset all the passwords. There is <em>absolutely no</em> procedure known
 184     to recover plaintext passwords, except asking the account holders.
 185     You are strongly adviced to make a backup before you apply such a change</li>
 186 <li>masterkey=[file or string]<br />CGIMasterKey used to read and decrypt
 187     the ticket</li>
 188 <li>newmasterkey=[file or string]<br />CGIMasterKey used to encrypt, sign,
 189     and write the ticket. Defaults to the masterkey. If you change
 190     the masterkey, you will have to reset all the accounts. You are strongly
 191     adviced to make a backup before you apply such a change</li>
 192 <li>password=[file or string]<br />New plaintext password</li>
 193 </ul>
 194 When the value of an option is a existing file path, the first line of
 195 that file is used. Options are followed by one or more paths plus names
 196 of existing ticket files. Each password option is only used for a single
 197 ticket file. It is most definitely a bad idea to use a password that is
 198 identical to an existing filepath, as the file will be read instead. Be
 199 aware that the name of the file should be a cleaned up version of the
 200 Username.This will not be checked.
 201 </p>
 202 <p>
 203 For the authentication and a change of password, the (old) password
 204 is used to "encrypt" a random one-time token or the new password,
 205 respectively. For authentication, decryption is not needed, so a secure
 206 hash function (SHA256) is used to create a one-way hash sum "encryption".
 207 A new password must be decrypted. New passwords are encryped by XORing
 208 them with the old password.
 209 </p>
 210
 211 <h3 align=CENTER>Strong Passwords: It is so easy</h3>
 212 <p align=CENTER><em>If you only could see what you are typing</em></p>
 213 <p >
 214 Your password might be vulnerable to
 215 <a href="https://en.wikipedia.org/wiki/Brute_force_attack">
 216 <em>brute force</em></a> guessing. Protections against such attacks are
 217 costly in terms of code complexity, bugs, and execution time.
 218 However, there is a very simple and secure counter measure. See the
 219 <a href="http://xkcd.com/936/" target="_blank">XKCD comic</a>. The phrase,
 220 <em>There is no password like more password</em> would
 221 be both much easier to remember, and still stronger than
 222 <em>h4]D%@m:49</em>, at least before this phrase was pasted as an example
 223 on the Internet.<br />
 224 For the procedures used at this site, a basic computer setup can check
 225 in the order of a billion passwords per second. You need a password (or
 226 phrase) strength in the order of 56 bits to be a little secure (one year
 227 on a single computer). One of the largest network in the world, Bitcoin
 228 mining, can check some 12 terahashes per second (June 2012). This
 229 corresponds to checking 6 times 10<sup>12</sup> passwords per second.
 230 It would take a passwords strength of ~68 bits to keep the equivalent of
 231 the Bitcoin computer network occupied for around a year before it found
 232 a match.<br />
 233 Please be so kind and add the name of your favorite flower, dish,
 234 fictional character, or small town to your password. Say,
 235 <em>Oleander</em>, <em>Curry</em>, <em>Sherlock</em>, or <em>Bath</em> (each adds
 236 ~12 bits) or even the phrase <em>Sherlock investigates oleander curry in
 237 Bath</em> (adds &gt; 56 bits, note that oleander is <em>poisonous</em>, so
 238 do not try this curry at home). That would be more effective than adding
 239 a thousand rounds of encryption. <br />
 240 Typing long passwords without seeing what you are typing is problematic.
 241 So a button should be included to make password visible.
 242 </p>
 243
 244 </body>
 245 </html>