## Apache Zeta Components Manual :: File Source for authentication_session.php

## Source for file authentication_session.php

Documentation is available at authentication_session.php

1. <?php
2. /**
3. * File containing the ezcAuthenticationSession class.
4. *
5. * Licensed to the Apache Software Foundation (ASF) under one
6. * or more contributor license agreements. See the NOTICE file
7. * distributed with this work for additional information
8. * regarding copyright ownership. The ASF licenses this file
9. * to you under the Apache License, Version 2.0 (the
10. * "License"); you may not use this file except in compliance
11. * with the License. You may obtain a copy of the License at
12. *
13. * http://www.apache.org/licenses/LICENSE-2.0
14. *
15. * Unless required by applicable law or agreed to in writing,
16. * software distributed under the License is distributed on an
17. * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18. * KIND, either express or implied. See the License for the
19. * specific language governing permissions and limitations
20. * under the License.
21. *
22. * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
23. * @filesource
24. * @package Authentication
25. * @version //autogen//
26. */
28. /**
29. * Support for session authentication and saving of authentication information
30. * between requests.
31. *
32. * Contains the methods:
33. * - start - starts the session, calling the PHP function session_start()
34. * - load - returns the information stored in the session key ezcAuth_id
35. * - save - saves information in the session key ezcAuth_id and also saves
36. * the current timestamp in the session key ezcAuth_timestamp
37. * - destroy - deletes the information stored in the session keys ezcAuth_id
38. * and ezcAuth_timestamp
39. * - regenerateId - regenerates the PHPSESSID value
40. *
41. * Example of use (combined with the Htpasswd filter):
42. * <code>
43. * // no headers should be sent before calling $session->start()
44. * $session = new ezcAuthenticationSession();
45. * $session->start();
46. *
47. * // retrieve the POST request information
48. * $user = isset( $_POST['user'] ) ? $_POST['user'] : $session->load();
49. * $password = isset( $_POST['password'] ) ? $_POST['password'] : null;
50. * $credentials = new ezcAuthenticationPasswordCredentials( $user, $password );
51. * $authentication = new ezcAuthentication( $credentials );
52. * $authentication->session = $session;
53. * $authentication->addFilter( new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd' ) );
54. * // add other filters if needed
55. * if ( !$authentication->run() )
56. * {
57. * // authentication did not succeed, so inform the user
58. * $status = $authentication->getStatus();
59. * $err = array(
60. * 'ezcAuthenticationHtpasswdFilter' => array(
61. * ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
62. * ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
63. * ),
64. * 'ezcAuthenticationSession' => array(
65. * ezcAuthenticationSession::STATUS_EMPTY => '',
66. * ezcAuthenticationSession::STATUS_EXPIRED => 'Session expired'
67. * )
68. * );
69. * foreach ( $status as $line )
70. * {
71. * list( $key, $value ) = each( $line );
72. * echo $err[$key][$value] . "\n";
73. * }
74. * }
75. * else
76. * {
77. * // authentication succeeded, so allow the user to see his content
78. * }
79. * </code>
80. *
81. * See {@link ezcAuthenticationSessionOptions} for options you can set to
82. * session objects.
83. *
84. * @package Authentication
85. * @version //autogen//
86. * @mainclass
87. */
88. class ezcAuthenticationSession
89. {
90. /**
91. * Successful authentication; normal behaviour is to skip the other filters.
92. *
93. * This should be the same value as ezcAuthenticationFilter::STATUS_OK.
94. */
95. const STATUS_OK = 0;
97. /**
98. * The session is empty; normal behaviour is to continue with the other filters.
99. */
100. const STATUS_EMPTY = 1;
102. /**
103. * The session expired; normal behaviour is to regenerate the session ID.
104. */
105. const STATUS_EXPIRED = 2;
107. /**
108. * Options for authentication filters.
109. *
110. * @var ezcAuthenticationFilterOptions
111. */
112. protected $options ;
114. /**
115. * Creates a new object of this class.
116. *
117. * @param ezcAuthenticationSessionOptions $options Options for this class
118. */
119. public function __construct ( ezcAuthenticationSessionOptions $options = null )
120. {
121. $this-> options = ( $options === null ) ? new ezcAuthenticationSessionOptions () : $options;
122. }
124. /**
125. * Runs through the session and returns a status code when finished.
126. *
127. * @param ezcAuthenticationCredentials $credentials Authentication credentials
128. * @return int
129. */
130. public function run ( $credentials )
131. {
132. $this-> start ();
133. if ( isset( $_SESSION[$this-> options ->timestampKey] ) &&
134. time () - $_SESSION[$this-> options ->timestampKey] >= $this-> options ->validity
135. )
136. {
137. $this-> destroy ();
138. $this-> regenerateId ();
139. return self::STATUS_EXPIRED;
140. }
141. if ( $this-> load () !== null )
142. {
143. return self::STATUS_OK;
144. }
145. return self::STATUS_EMPTY;
146. }
148. /**
149. * Runs through the session and returns true if the session is correct.
150. *
151. * When using the session, it is often desirable to take advantage of the
152. * fact that the authenticated state of the user is kept in the session and
153. * not create and initialize the other filters (which might slow things
154. * down on every request).
155. *
156. * The application can be structured like this:
157. * <code>
158. * $session = new ezcAuthenticationSession();
159. * $session->start();
160. *
161. * $credentials = new ezcAuthenticationPasswordCredentials( $user, $pass );
162. *
163. * $authenticated = false;
164. * if ( !$session->isValid( $credentials ) )
165. * {
166. * // create the authentication object
167. * $authentication = new ezcAuthentication( $credentials );
168. * $authentication->session = $session;
169. *
170. * // create filters and add them to the authentication object
171. * $authentication->addFilter( new ezcAuthenticationOpenidFilter() );
172. *
173. * // run the authentication object
174. * if ( !$authentication->run() )
175. * {
176. * $status = $authentication->getStatus();
177. * // build an error message based on $status
178. * }
179. * else
180. * {
181. * $authenticated = true;
182. * }
183. * }
184. * else
185. * {
186. * $authenticated = true;
187. * }
188. *
189. * if ( $authenticated )
190. * {
191. * // the authentication succeeded and the user can see his content
192. * }
193. * else
194. * {
195. * // inform the user that the authentication failed (with the error
196. * // message that was created earlier)
197. * }
198. * </code>
199. *
200. * In this way, the creation and initialization of the authentication
201. * filters is not performed if the credentials are stored in the session.
202. *
203. * @param ezcAuthenticationCredentials $credentials Authentication credentials
204. * @return bool
205. */
206. public function isValid ( $credentials )
207. {
208. return ( $this-> run ( $credentials ) === self::STATUS_OK );
209. }
211. /**
212. * Starts the session.
213. *
214. * This function must be called before sending any headers to the client.
215. */
216. public function start ()
217. {
218. if ( session_id () === '' && PHP_SAPI !== 'cli' )
219. {
220. session_start ();
221. }
222. }
224. /**
225. * Loads the authenticated username from the session or null if it doesn't exist.
226. *
227. * @return string
228. */
229. public function load ()
230. {
231. return isset( $_SESSION[$this-> options ->idKey] ) ? $_SESSION[$this-> options ->idKey] :
232. null;
233. }
235. /**
236. * Saves the authenticated username and the current timestamp in the session
237. * variables.
238. *
239. * @param string $data Information to save in the session, usually username
240. */
241. public function save ( $data )
242. {
243. $_SESSION[$this-> options ->idKey] = $data;
244. $_SESSION[$this-> options ->timestampKey] = time ();
245. }
247. /**
248. * Removes the variables used by this class from the session variables.
249. */
250. public function destroy ()
251. {
252. unset( $_SESSION[$this-> options ->idKey] );
253. unset( $_SESSION[$this-> options ->timestampKey] );
254. }
256. /**
257. * Regenerates the session ID.
258. */
259. public function regenerateId ()
260. {
261. if ( ! headers_sent () )
262. {
263. // ???? seems that PHPSESSID is not regenerated if session is destroyed first????
264. // session_destroy();
265. session_regenerate_id ();
266. }
267. }
269. /**
270. * Sets the options of this class to $options.
271. *
272. * @param ezcAuthenticationSessionOptions $options Options for this class
273. */
274. public function setOptions ( ezcAuthenticationSessionOptions $options )
275. {
276. $this-> options = $options;
277. }
279. /**
280. * Returns the options of this class.
281. *
282. * @return ezcAuthenticationSessionOptions
283. */
284. public function getOptions ()
285. {
286. return $this-> options ;
287. }
288. }
289. ?>

Documentation generated by phpDocumentor 1.4.3