classes/plsession.php

   1 <?php
   2 /***************************************************************************
   3  *  Copyright (C) 2003-2008 Polytechnique.org                              *
   4  *  http://opensource.polytechnique.org/                                   *
   5  *                                                                         *
   6  *  This program is free software; you can redistribute it and/or modify   *
   7  *  it under the terms of the GNU General Public License as published by   *
   8  *  the Free Software Foundation; either version 2 of the License, or      *
   9  *  (at your option) any later version.                                    *
  10  *                                                                         *
  11  *  This program is distributed in the hope that it will be useful,        *
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of         *
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
  14  *  GNU General Public License for more details.                           *
  15  *                                                                         *
  16  *  You should have received a copy of the GNU General Public License      *
  17  *  along with this program; if not, write to the Free Software            *
  18  *  Foundation, Inc.,                                                      *
  19  *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA                *
  20  ***************************************************************************/
  21
  22 /** Authentication level.
  23  * Only AUTH_PUBLIC is mandatory. The others are defined as useful values,
  24  * but can be overwritten by others auth levels definitions.
  25  */
  26 define('AUTH_PUBLIC', 0);
  27 define('AUTH_COOKIE', 1);
  28 define('AUTH_MDP',    2);
  29
  30
  31 /** The PlSession is a wrapper around the user session management.
  32  */
  33 abstract class PlSession
  34 {
  35     /** Build a new session object.
  36      * If a session is already started, this just wraps the session... if no
  37      * session is currently started, this set the base session variables.
  38      *  * auth        contains the current authentication level. The level is
  39      *                an integer that grows with the security of the authentication
  40      *                method.
  41      *  * perms       contains the current permission flags of the user. This flags
  42      *                depends on the category of the user.
  43      *  * challenge   contains a random uniq id for authentication.
  44      *  * xsrf_token  contains a random uniq id for xsrf prevention.
  45      *  * user        contains a reference to the current user.
  46      */
  47     public function __construct()
  48     {
  49         $this->create();
  50     }
  51
  52     /** Build the session structure with system fields.
  53      */
  54     private function fillSession()
  55     {
  56         S::bootstrap('user', null);
  57         S::bootstrap('auth', AUTH_PUBLIC);
  58         S::bootstrap('challenge', sha1(uniqid(rand(), true)));
  59         S::bootstrap('xsrf_token', rand_url_id());
  60         S::bootstrap('perms', new PlFlagSet());
  61     }
  62
  63     /** Write current session and close it.
  64      */
  65     public function close()
  66     {
  67         session_write_close();
  68     }
  69
  70     /** Create a new session
  71      */
  72     private function create()
  73     {
  74         session_start();
  75         $this->fillSession();
  76     }
  77
  78     /** Kill the current session.
  79      */
  80     public function destroy()
  81     {
  82         session_destroy();
  83         unset($_SESSION);
  84         $this->create();
  85     }
  86
  87     /** Check if the user has at least the given authentication level.
  88      */
  89     public function checkAuth($level)
  90     {
  91         return S::i('auth') >= $level;
  92     }
  93
  94     /** Check if the user has the given permissions.
  95      */
  96     public function checkPerms($perms)
  97     {
  98         return S::v('perms')->hasFlagCombination($perms);
  99     }
 100
 101     /** Run authentication procedure to reach at least the given level.
 102      */
 103     public function start($level)
 104     {
 105         $backup = S::i($level);
 106         if ($this->checkAuth($level)) {
 107             return true;
 108         }
 109         $user = $this->doAuth($level);
 110         if (is_null($user)) {
 111             return false;
 112         }
 113         if (!$this->checkAuth($level)) {
 114             $this->destroy();
 115             return false;
 116         }
 117         if ($this->startSessionAs($user, $level)) {
 118             if (is_null(S::v('user'))) {
 119                 S::set('user', $user);
 120             }
 121             return true;
 122         } else {
 123             $this->destroy();
 124         }
 125         return false;
 126     }
 127
 128
 129     /*** Abstract methods ***/
 130
 131     /** Function that check authentication at build time of the session object.
 132      * This is useful to perform authentication from a cookie or when coming
 133      * back from a authentication service.
 134      *
 135      * This function must NOT try to launch a new authenticatioin procedure. It
 136      * just tests if the environment contains sufficient information to start
 137      * a user session.
 138      *
 139      * This function return false if informations are available but lead to an
 140      * authentication failure (invalid cookie, invalid service return data...)
 141      */
 142     abstract public function startAvailableAuth();
 143
 144     /** Run the effectively authentication procedure to reach the given user.
 145      * This method must return a user object (that will be used to fill the
 146      * $_SESSION['user'] field).
 147      *
 148      * If auth failed, the function MUST return null. If auth succeed, the
 149      * field $_SESSION['auth'] MUST be filled to the current effective level.
 150      */
 151     abstract protected function doAuth($level);
 152
 153     /** Set the session environment to the given user and authentication level.
 154      * This function MUST return false if a session is already started and the
 155      * user mismatch.
 156      *
 157      * On succes, this function MUST return true.
 158      * If $level is set to -1, this means you are building a new SUID session.
 159      */
 160     abstract protected function startSessionAs($user, $level);
 161
 162
 163     /*** SUID management ***/
 164
 165     /** Start a new SUID session.
 166      */
 167     public function startSUID($user)
 168     {
 169         if (S::has('suid')) {
 170             return false;
 171         }
 172         $backup   = $_SESSION;
 173         $_SESSION = array();
 174         $this->fillSession();
 175         S::set('suid', $backup);
 176         if (!$this->startSessionAs($user, -1)) {
 177             $this->stopSUID();
 178             return false;
 179         }
 180         S::set('user', $user);
 181         return true;
 182     }
 183
 184     /** Stop a SUID session
 185      */
 186     public function stopSUID()
 187     {
 188         if (!S::has('suid')) {
 189             return false;
 190         }
 191         $_SESSION = $_SESSION['suid'];
 192         return true;
 193     }
 194
 195
 196     /*** Thresholds ***/
 197
 198     /** Minimum level of authentication that is considered as sure.
 199      */
 200     abstract public function sureLevel();
 201 }
 202
 203 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
 204 ?>