2 /***************************************************************************
3 * Copyright (C) 2003-2008 Polytechnique.org *
4 * http://opensource.polytechnique.org/ *
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. *
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. *
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 *
19 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *
20 ***************************************************************************/
23 /** The PlSession is a wrapper around the user session management.
25 abstract class PlSession
27 /** Build a new session object.
28 * If a session is already started, this just wraps the session... if no
29 * session is currently started, this set the base session variables.
30 * * auth contains the current authentication level. The level is
31 * an integer that grows with the security of the authentication
33 * * perms contains the current permission flags of the user. This flags
34 * depends on the category of the user.
35 * * challenge contains a random uniq id for authentication.
36 * * xsrf_token contains a random uniq id for xsrf prevention.
37 * * user contains a reference to the current user.
39 public function __construct()
44 /** Build the session structure with system fields.
46 private function fillSession()
48 S
::bootstrap('user', null
);
49 S
::bootstrap('auth', AUTH_PUBLIC
);
50 S
::bootstrap('challenge', sha1(uniqid(rand(), true
)));
51 S
::bootstrap('xsrf_token', rand_url_id());
52 S
::bootstrap('perms', new PlFlagSet());
55 /** Write current session and close it.
57 public function close()
59 session_write_close();
62 /** Create a new session
64 private function create()
70 /** Kill the current session.
72 public function destroy()
79 /** Check if the user has at least the given authentication level.
81 public function checkAuth($level)
83 return S
::i('auth') >= $level;
86 /** Check if the user has the given permissions.
88 public function checkPerms($perms)
90 return S
::v('perms')->hasFlagCombination($perms);
93 /** Run authentication procedure to reach at least the given level.
95 public function start($level)
97 $backup = S
::i($level);
98 if ($this->checkAuth($level)) {
101 $user = $this->doAuth($level);
102 if (is_null($user)) {
105 if (!$this->checkAuth($level)) {
109 if ($this->startSessionAs($user, $level)) {
110 if (is_null(S
::v('user'))) {
111 S
::set('user', $user);
121 /*** Abstract methods ***/
123 /** Function that check authentication at build time of the session object.
124 * This is useful to perform authentication from a cookie or when coming
125 * back from a authentication service.
127 * This function must NOT try to launch a new authenticatioin procedure. It
128 * just tests if the environment contains sufficient information to start
131 * This function return false if informations are available but lead to an
132 * authentication failure (invalid cookie, invalid service return data...)
134 abstract public function startAvailableAuth();
136 /** Run the effectively authentication procedure to reach the given user.
137 * This method must return a user object (that will be used to fill the
138 * $_SESSION['user'] field).
140 * If auth failed, the function MUST return null. If auth succeed, the
141 * field $_SESSION['auth'] MUST be filled to the current effective level.
143 abstract protected function doAuth($level);
145 /** Set the session environment to the given user and authentication level.
146 * This function MUST return false if a session is already started and the
149 * On succes, this function MUST return true.
150 * If $level is set to -1, this means you are building a new SUID session.
152 abstract protected function startSessionAs($user, $level);
155 /*** SUID management ***/
157 /** Start a new SUID session.
159 public function startSUID($user)
161 if (isset($_SESSION['suid'])) {
164 $newsession = array();
165 $backup =& $_SESSION;
166 $_SESSION =& $newsession;
167 $this->fillSession();
168 S
::set('suid', $backup);
169 if (!$this->startSessionAs($user, -1)) {
176 /** Stop a SUID session
178 public function stopSUID()
180 if (!isset($_SESSION['suid'])) {
183 $_SESSION =& $_SESSION['suid'];
190 /** Minimum level of authentication that is considered as sure.
192 abstract public function sureLevel();
195 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8: