classes/plsession.php

   1 <?php
   2 /***************************************************************************
   3  *  Copyright (C) 2003-2010 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         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     /** Check authentication with the given token.
 163      *
 164      * Token authentication is a light-weight authentication based on a user-specific token.
 165      * This can be used for protocols that requires a 'cookie'-free authentication, such as
 166      * RSS, iCal registration...
 167      *
 168      * This function returns a valid user object if authentication is successful, or null if
 169      * token mismatch.
 170      */
 171     abstract public function tokenAuth($login, $token);
 172
 173     /** Set the permissions to the given flagset.
 174      *
 175      * This function sets S::set('perms') with a flagset represeting the combination of
 176      * $perms and $is_admin.
 177      *
 178      * $perms is an abstract object representing the permissions.
 179      * $is_admin is a boolean, true if the current user has site-administration rights.
 180      */
 181     abstract protected function makePerms($perms, $is_admin);
 182
 183     /*** SUID management ***/
 184
 185     /** Start a new SUID session.
 186      */
 187     public function startSUID($user, $perms = null)
 188     {
 189         if (S::suid()) {
 190             return false;
 191         }
 192         $backup   = $_SESSION;
 193         $_SESSION = array();
 194         $this->fillSession();
 195         S::set('suid', $backup);
 196         if (!$this->startSessionAs($user, AUTH_SUID)) {
 197             $this->stopSUID();
 198             return false;
 199         }
 200         S::set('user', $user);
 201         if (!is_null($perms)) {
 202             $this->makePerms($perms, false);
 203         }
 204         return true;
 205     }
 206
 207     /** Stop a SUID session
 208      */
 209     public function stopSUID()
 210     {
 211         if (!S::suid()) {
 212             return false;
 213         }
 214         $_SESSION = $_SESSION['suid'];
 215         return true;
 216     }
 217
 218
 219     /*** Thresholds ***/
 220
 221     /** Minimum level of authentication that is considered as logged.
 222      */
 223     abstract public function loggedLevel();
 224
 225     /** Minimum level of authentication that is considered as sure.
 226      */
 227     abstract public function sureLevel();
 228 }
 229
 230 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
 231 ?>