File: ReadMe.txt

/**************************************************************************
 *
 * Title:         Class 'Session' (class_session.inc.php)
 *
 * Version:       1.2
 *
 * Copyright:     (c) 2012 Volker Rubach - All rights reserved
 *
 * Description:   This class provide a secure session handler with
 *                PDO connection to a MySQL database.
 *
 *************************************************************************/


 Importend notes
 ---------------
 Save 'class_session.inc.php' under 'CGI-BIN' in the root folder. This
 directory exists in most cases, is not accessible from outside, but
 locally executed PHP scripts can access this folder and can use the
 class.

 If the hosting package has not a protected 'CGI-BIN' directory, manual
 a secure directory should be set up, then the class and config stored
 there.

 These measures increase the security against unauthorized access to
 the database, because the credentials are not as freely available!!!


 Notes
 -----
 This class have a own session handler, use a database to save sessions,
 open the connection over PDO, uses preparestatements and bind variables.
 

 Security
 --------
 To prevent session fixation, PHP not include the identifier in the URL
 and don't read the URL for identifiers (session.use_trans_sid = 0).
 Also PHP will use only Cookies for session handling and never use URLs
 with session identifiers (session.use_only_cookies = 1).
 
 To prevent session hijacking, this class use a fingerprint to identify
 a user. This fingerprint will be generated from following values:
 
 - SALT             =>  free random value
                        (can be themselves added; longer is better)
 - Host Name        =>  determined by PHP
                        (or 'unkown' if can't determined)
 - IP Address       =>  determined by PHP
                        (only first two sets used; rest are set to 0)
 - HTTP User Agent  =>  determined by PHP

 This fingerprint is checked each time during a session. This ensures
 that if a session is hijacked, they will be immediately destroyed.
 

 Declaration of variables
 ------------------------
 $this->dbHost        CONF: MySQL server address
 $this->dbName        CONF: MySQL database name
 $this->dbUser        CONF: MySQL account username [read rights]
 $this->dbPass        CONF: MySQL account password [read rights]
 $this->table         CONF: MySQL table name where sessions are saved
 $this->confPDO       PDO attributes
 $this->salt          SALT [free random value to increase the session security]
 $this->location      Target address after session was destroyed
 $this->domain        Domain name
 $this->dbc           Database connection
 $this->fingerprint   Composite chain of values [hashed with MD5]
 $this->sessfp        Fingerprint of current session [read from table]
 $id                  Session ID
 $data                Session data
 $fingerprint         Composite chain of values [hashed with MD5]
 $stmt                SQL statement [prepare / execute]


 Include class
 -------------
 <code>
   include('../ <path> /class_session.inc.php');
 </code>


 Create instance
 ---------------
 <code>
   $session = new Session();
 </code>


Important note:  Include class and create instance must be done before
                 the first HTML tag in the script or HTML page and no
                 blank line before the commands.


 Usage: Write session data
 -------------------------
 <code>
   $_SESSION['user']='<name>';
 </code>


 Usage: Output session data
 --------------------------
 <code>
   $echo $_SESSION['user'];
 </code>


 Usage: Session data into variable
 ---------------------------------
 <code>
   $user = $_SESSION['user'];
 </code>


 SECURITY: Reliable values
 -------------------------
 $_SERVER["DOCUMENT_ROOT"]
 $_SERVER["HTTP_USER_AGENT"]        (may be empty, but then reliable empty)


 SECURITY: 'Salt' (free random sequence)
 ---------------------------------------
 $this->salt = "w3463-dfgsdgd-564564";


 SECURITY: Less reliable values
 ------------------------------
 $_SERVER["REMOTE_ADDR"]            (or only parts of it; e.g. 192.64.0.0)
 $_SERVER["HTTP_ACCEPT_LANGUAGE"]
 $_SERVER["HTTP_ACCEPT_CHARSET"]
 $_SERVER["HTTP_ACCEPT_ENCODING"]
 $_SERVER["HTTP_ACCEPT"]