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_SUID',   -1);
  27 define('AUTH_PUBLIC', 0);
  28 define('AUTH_COOKIE', 5);
  29 define('AUTH_MDP',    10);
  30
  31
  32 /** The PlSession is a wrapper around the user session management.
  33  */
  34 abstract class PlSession
  35 {
  36     /** Build a new session object.
  37      * If a session is already started, this just wraps the session... if no
  38      * session is currently started, this set the base session variables.
  39      *  * auth        contains the current authentication level. The level is
  40      *                an integer that grows with the security of the authentication
  41      *                method.
  42      *  * perms       contains the current permission flags of the user. This flags
  43      *                depends on the category of the user.
  44      *  * challenge   contains a random uniq id for authentication.
  45      *  * xsrf_token  contains a random uniq id for xsrf prevention.
  46      *  * user        contains a reference to the current user.
  47      */
  48     public function __construct()
  49     {
  50         $this->create();
  51     }
  52
  53     /** Build the session structure with system fields.
  54      */
  55     private function fillSession()
  56     {
  57         S::bootstrap('user', null);
  58         S::bootstrap('auth', AUTH_PUBLIC);
  59         S::bootstrap('challenge', sha1(uniqid(rand(), true)));
  60         S::bootstrap('xsrf_token', rand_url_id());
  61         S::bootstrap('perms', new PlFlagSet());
  62     }
  63
  64     /** Write current session and close it.
  65      */
  66     public function close()
  67     {
  68         session_write_close();
  69     }
  70
  71     /** Create a new session
  72      */
  73     private function create()
  74     {
  75         session_start();
  76         $this->fillSession();
  77     }
  78
  79     /** Kill the current session.
  80      */
  81     public function destroy()
  82     {
  83         session_destroy();
  84         unset($_SESSION);
  85         $this->create();
  86     }
  87
  88     /** Check if the user has at least the given authentication level.
  89      */
  90     public function checkAuth($level)
  91     {
  92         return S::i('auth') >= $level;
  93     }
  94
  95     /** Check if the user has the given permissions.
  96      */
  97     public function checkPerms($perms)
  98     {
  99         return S::v('perms')->hasFlagCombination($perms);
 100     }
 101
 102     /** Run authentication procedure to reach at least the given level.
 103      */
 104     public function start($level)
 105     {
 106         $backup = S::i($level);
 107         if ($this->checkAuth($level)) {
 108             return true;
 109         }
 110         $user = $this->doAuth($level);
 111         if (is_null($user)) {
 112             return false;
 113         }
 114         if (!$this->checkAuth($level)) {
 115             $this->destroy();
 116             return false;
 117         }
 118         if ($this->startSessionAs($user, $level)) {
 119             if (is_null(S::v('user'))) {
 120                 S::set('user', $user);
 121             }
 122             return true;
 123         } else {
 124             $this->destroy();
 125         }
 126         return false;
 127     }
 128
 129
 130     /*** Abstract methods ***/
 131
 132     /** Function that check authentication at build time of the session object.
 133      * This is useful to perform authentication from a cookie or when coming
 134      * back from a authentication service.
 135      *
 136      * This function must NOT try to launch a new authenticatioin procedure. It
 137      * just tests if the environment contains sufficient information to start
 138      * a user session.
 139      *
 140      * This function return false if informations are available but lead to an
 141      * authentication failure (invalid cookie, invalid service return data...)
 142      */
 143     abstract public function startAvailableAuth();
 144
 145     /** Run the effectively authentication procedure to reach the given user.
 146      * This method must return a user object (that will be used to fill the
 147      * $_SESSION['user'] field).
 148      *
 149      * If auth failed, the function MUST return null. If auth succeed, the
 150      * field $_SESSION['auth'] MUST be filled to the current effective level.
 151      */
 152     abstract protected function doAuth($level);
 153
 154     /** Set the session environment to the given user and authentication level.
 155      * This function MUST return false if a session is already started and the
 156      * user mismatch.
 157      *
 158      * On succes, this function MUST return true.
 159      * If $level is set to -1, this means you are building a new SUID session.
 160      */
 161     abstract protected function startSessionAs($user, $level);
 162
 163     /** Check authentication with the given token.
 164      *
 165      * Token authentication is a light-weight authentication based on a user-specific token.
 166      * This can be used for protocols that requires a 'cookie'-free authentication, such as
 167      * RSS, iCal registration...
 168      *
 169      * This function returns a valid user object if authentication is successful, or null if
 170      * token mismatch.
 171      */
 172     abstract public function tokenAuth($login, $token);
 173
 174     /** Set the permissions to the given flagset.
 175      *
 176      * This function sets S::set('perms') with a flagset represeting the combination of
 177      * $perms and $is_admin.
 178      *
 179      * $perms is an abstract object representing the permissions.
 180      * $is_admin is a boolean, true if the current user has site-administration rights.
 181      */
 182     abstract protected function makePerms($perms, $is_admin);
 183
 184     /*** SUID management ***/
 185
 186     /** Start a new SUID session.
 187      */
 188     public function startSUID($user, $perms = null)
 189     {
 190         if (S::suid()) {
 191             return false;
 192         }
 193         $backup   = $_SESSION;
 194         $_SESSION = array();
 195         $this->fillSession();
 196         S::set('suid', $backup);
 197         if (!$this->startSessionAs($user, AUTH_SUID)) {
 198             $this->stopSUID();
 199             return false;
 200         }
 201         S::set('user', $user);
 202         if (!is_null($perms)) {
 203             $this->makePerms($perms, false);
 204         }
 205         return true;
 206     }
 207
 208     /** Stop a SUID session
 209      */
 210     public function stopSUID()
 211     {
 212         if (!S::suid()) {
 213             return false;
 214         }
 215         $_SESSION = $_SESSION['suid'];
 216         return true;
 217     }
 218
 219
 220     /*** Thresholds ***/
 221
 222     /** Minimum level of authentication that is considered as logged.
 223      */
 224     abstract public function loggedLevel();
 225
 226     /** Minimum level of authentication that is considered as sure.
 227      */
 228     abstract public function sureLevel();
 229 }
 230
 231 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
 232 ?>