2 /***************************************************************************
3 * Copyright (C) 2003-2011 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 ***************************************************************************/
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.
26 define('AUTH_SUID', -1);
27 define('AUTH_PUBLIC', 0);
28 define('AUTH_COOKIE', 5);
29 define('AUTH_PASSWD', 10);
30 // Backwards compatibility: AUTH_MDP must be an alias for AUTH_PASSWD.
31 define('AUTH_MDP', 10);
34 /** The PlSession is a wrapper around the user session management.
36 abstract class PlSession
38 /** Build a new session object.
39 * If a session is already started, this just wraps the session... if no
40 * session is currently started, this set the base session variables.
41 * * auth contains the current authentication level. The level is
42 * an integer that grows with the security of the authentication
44 * * perms contains the current permission flags of the user. This flags
45 * depends on the category of the user.
46 * * challenge contains a random uniq id for authentication.
47 * * xsrf_token contains a random uniq id for xsrf prevention.
48 * * user contains a reference to the current user.
50 public function __construct()
55 /** Build the session structure with system fields.
57 protected function fillSession()
59 S
::bootstrap('user', null
);
60 S
::bootstrap('auth', AUTH_PUBLIC
);
61 S
::bootstrap('challenge', sha1(uniqid(rand(), true
)));
62 S
::bootstrap('xsrf_token', rand_url_id());
63 S
::bootstrap('perms', new PlFlagSet());
66 /** Write current session and close it.
68 public function close()
70 session_write_close();
73 /** Create a new session
75 private function create()
81 /** Kill the current session.
83 public function destroy()
90 /** Check if the user has at least the given authentication level.
92 public function checkAuth($level)
94 return S
::i('auth') >= $level;
97 /** Check if the user has the given permissions.
99 public function checkPerms($perms)
101 return S
::v('perms')->hasFlagCombination($perms);
104 /** Run authentication procedure to reach at least the given level.
106 public function start($level)
108 if ($this->checkAuth($level)) {
111 $user = $this->doAuth($level);
112 if (is_null($user)) {
115 if (!$this->checkAuth($level)) {
119 if ($this->startSessionAs($user, $level)) {
120 if (is_null(S
::v('user'))) {
121 S
::set('user', $user);
131 /*** Abstract methods ***/
133 /** Function that check authentication at build time of the session object.
134 * This is useful to perform authentication from a cookie or when coming
135 * back from a authentication service.
137 * This function must NOT try to launch a new authenticatioin procedure. It
138 * just tests if the environment contains sufficient information to start
141 * This function return false if informations are available but lead to an
142 * authentication failure (invalid cookie, invalid service return data...)
144 abstract public function startAvailableAuth();
146 /** Run the effectively authentication procedure to reach the given user.
147 * This method must return a user object (that will be used to fill the
148 * $_SESSION['user'] field).
150 * If auth failed, the function MUST return null. If auth succeed, the
151 * field $_SESSION['auth'] MUST be filled to the current effective level.
153 abstract protected function doAuth($level);
155 /** Set the session environment to the given user and authentication level.
156 * This function MUST return false if a session is already started and the
159 * On succes, this function MUST return true.
160 * If $level is set to -1, this means you are building a new SUID session.
162 abstract protected function startSessionAs($user, $level);
164 /** Authenticate the request for the given (method, payload) pair.
166 * Implementations are expected to provide strong authentication. It is
167 * suggested to use an HMAC-based scheme, where the signature validates the
168 * method, url, and payload (to avoid replay of the signature against other
169 * methods), and the timestamp (to avoid replay in time).
171 * @param method method of the request (GET, POST, PUT, DELETE)
172 * @param resource URL path of the resource (eg. "/api/user")
173 * @param payload binary payload sent with the request (before decoding)
174 * @return a valid PlUser object if authentication is successfull, or null.
176 public function apiAuth($method, $resource, $payload)
178 return null
; // Default implementation does nothing
181 /** Check authentication with the given token.
183 * Token authentication is a light-weight authentication based on a user-specific token.
184 * This can be used for protocols that requires a 'cookie'-free authentication, such as
185 * RSS, iCal registration...
187 * This function returns a valid user object if authentication is successful, or null if
190 abstract public function tokenAuth($login, $token);
192 /** Set the permissions to the given flagset.
194 * This function sets S::set('perms') with a flagset represeting the combination of
195 * $perms and $is_admin.
197 * $perms is an abstract object representing the permissions.
198 * $is_admin is a boolean, true if the current user has site-administration rights.
200 abstract protected function makePerms($perms, $is_admin);
202 /*** SUID management ***/
204 /** Start a new SUID session.
206 public function startSUID($user, $perms = null
)
211 $backup = S
::changeSession(array());
212 $this->fillSession();
213 S
::set('suid', $backup);
214 if (!$this->startSessionAs($user, AUTH_SUID
)) {
218 S
::set('user', $user);
219 if (!is_null($perms)) {
220 $this->makePerms($perms, false
);
225 /** Stop a SUID session
227 public function stopSUID()
232 S
::changeSession(S
::v('suid'));
239 /** Minimum level of authentication that is considered as logged.
241 abstract public function loggedLevel();
243 /** Minimum level of authentication that is considered as sure.
245 abstract public function sureLevel();
248 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker fenc=utf-8: