5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 namespace MediaWiki\Session
;
26 use Psr\Log\LoggerInterface
;
31 * Manages data for an an authenticated session
33 * A Session represents the fact that the current HTTP request is part of a
34 * session. There are two broad types of Sessions, based on whether they
35 * return true or false from self::canSetUser():
36 * * When true (mutable), the Session identifies multiple requests as part of
37 * a session generically, with no tie to a particular user.
38 * * When false (immutable), the Session identifies multiple requests as part
39 * of a session by identifying and authenticating the request itself as
40 * belonging to a particular user.
42 * The Session object also serves as a replacement for PHP's $_SESSION,
43 * managing access to per-session data.
48 final class Session
implements \Countable
, \Iterator
, \ArrayAccess
{
49 /** @var null|string[] Encryption algorithm to use */
50 private static $encryptionAlgorithm = null;
52 /** @var SessionBackend Session backend */
55 /** @var int Session index */
58 /** @var LoggerInterface */
62 * @param SessionBackend $backend
64 * @param LoggerInterface $logger
66 public function __construct( SessionBackend
$backend, $index, LoggerInterface
$logger ) {
67 $this->backend
= $backend;
68 $this->index
= $index;
69 $this->logger
= $logger;
72 public function __destruct() {
73 $this->backend
->deregisterSession( $this->index
);
77 * Returns the session ID
80 public function getId() {
81 return $this->backend
->getId();
85 * Returns the SessionId object
86 * @private For internal use by WebRequest
89 public function getSessionId() {
90 return $this->backend
->getSessionId();
94 * Changes the session ID
95 * @return string New ID (might be the same as the old)
97 public function resetId() {
98 return $this->backend
->resetId();
102 * Fetch the SessionProvider for this session
103 * @return SessionProviderInterface
105 public function getProvider() {
106 return $this->backend
->getProvider();
110 * Indicate whether this session is persisted across requests
112 * For example, if cookies are set.
116 public function isPersistent() {
117 return $this->backend
->isPersistent();
121 * Make this session persisted across requests
123 * If the session is already persistent, equivalent to calling
126 public function persist() {
127 $this->backend
->persist();
131 * Make this session not be persisted across requests
133 public function unpersist() {
134 $this->backend
->unpersist();
138 * Indicate whether the user should be remembered independently of the
142 public function shouldRememberUser() {
143 return $this->backend
->shouldRememberUser();
147 * Set whether the user should be remembered independently of the session
149 * @param bool $remember
151 public function setRememberUser( $remember ) {
152 $this->backend
->setRememberUser( $remember );
156 * Returns the request associated with this session
159 public function getRequest() {
160 return $this->backend
->getRequest( $this->index
);
164 * Returns the authenticated user for this session
167 public function getUser() {
168 return $this->backend
->getUser();
172 * Fetch the rights allowed the user when this session is active.
173 * @return null|string[] Allowed user rights, or null to allow all.
175 public function getAllowedUserRights() {
176 return $this->backend
->getAllowedUserRights();
180 * Indicate whether the session user info can be changed
183 public function canSetUser() {
184 return $this->backend
->canSetUser();
188 * Set a new user for this session
189 * @note This should only be called when the user has been authenticated
190 * @param User $user User to set on the session.
191 * This may become a "UserValue" in the future, or User may be refactored
194 public function setUser( $user ) {
195 $this->backend
->setUser( $user );
199 * Get a suggested username for the login form
200 * @return string|null
202 public function suggestLoginUsername() {
203 return $this->backend
->suggestLoginUsername( $this->index
);
207 * Whether HTTPS should be forced
210 public function shouldForceHTTPS() {
211 return $this->backend
->shouldForceHTTPS();
215 * Set whether HTTPS should be forced
218 public function setForceHTTPS( $force ) {
219 $this->backend
->setForceHTTPS( $force );
223 * Fetch the "logged out" timestamp
226 public function getLoggedOutTimestamp() {
227 return $this->backend
->getLoggedOutTimestamp();
231 * Set the "logged out" timestamp
234 public function setLoggedOutTimestamp( $ts ) {
235 $this->backend
->setLoggedOutTimestamp( $ts );
239 * Fetch provider metadata
240 * @protected For use by SessionProvider subclasses only
243 public function getProviderMetadata() {
244 return $this->backend
->getProviderMetadata();
248 * Delete all session data and clear the user (if possible)
250 public function clear() {
251 $data = &$this->backend
->getData();
254 $this->backend
->dirty();
256 if ( $this->backend
->canSetUser() ) {
257 $this->backend
->setUser( new User
);
259 $this->backend
->save();
265 * Resets the TTL in the backend store if the session is near expiring, and
266 * re-persists the session to any active WebRequests if persistent.
268 public function renew() {
269 $this->backend
->renew();
273 * Fetch a copy of this session attached to an alternative WebRequest
275 * Actions on the copy will affect this session too, and vice versa.
277 * @param WebRequest $request Any existing session associated with this
278 * WebRequest object will be overwritten.
281 public function sessionWithRequest( WebRequest
$request ) {
282 $request->setSessionId( $this->backend
->getSessionId() );
283 return $this->backend
->getSession( $request );
287 * Fetch a value from the session
288 * @param string|int $key
289 * @param mixed $default Returned if $this->exists( $key ) would be false
292 public function get( $key, $default = null ) {
293 $data = &$this->backend
->getData();
294 return array_key_exists( $key, $data ) ?
$data[$key] : $default;
298 * Test if a value exists in the session
299 * @note Unlike isset(), null values are considered to exist.
300 * @param string|int $key
303 public function exists( $key ) {
304 $data = &$this->backend
->getData();
305 return array_key_exists( $key, $data );
309 * Set a value in the session
310 * @param string|int $key
311 * @param mixed $value
313 public function set( $key, $value ) {
314 $data = &$this->backend
->getData();
315 if ( !array_key_exists( $key, $data ) ||
$data[$key] !== $value ) {
316 $data[$key] = $value;
317 $this->backend
->dirty();
322 * Remove a value from the session
323 * @param string|int $key
325 public function remove( $key ) {
326 $data = &$this->backend
->getData();
327 if ( array_key_exists( $key, $data ) ) {
328 unset( $data[$key] );
329 $this->backend
->dirty();
334 * Fetch a CSRF token from the session
336 * Note that this does not persist the session, which you'll probably want
337 * to do if you want the token to actually be useful.
339 * @param string|string[] $salt Token salt
340 * @param string $key Token key
343 public function getToken( $salt = '', $key = 'default' ) {
345 $secrets = $this->get( 'wsTokenSecrets' );
346 if ( !is_array( $secrets ) ) {
349 if ( isset( $secrets[$key] ) && is_string( $secrets[$key] ) ) {
350 $secret = $secrets[$key];
352 $secret = \MWCryptRand
::generateHex( 32 );
353 $secrets[$key] = $secret;
354 $this->set( 'wsTokenSecrets', $secrets );
357 if ( is_array( $salt ) ) {
358 $salt = implode( '|', $salt );
360 return new Token( $secret, (string)$salt, $new );
364 * Remove a CSRF token from the session
366 * The next call to self::getToken() with $key will generate a new secret.
368 * @param string $key Token key
370 public function resetToken( $key = 'default' ) {
371 $secrets = $this->get( 'wsTokenSecrets' );
372 if ( is_array( $secrets ) && isset( $secrets[$key] ) ) {
373 unset( $secrets[$key] );
374 $this->set( 'wsTokenSecrets', $secrets );
379 * Remove all CSRF tokens from the session
381 public function resetAllTokens() {
382 $this->remove( 'wsTokenSecrets' );
386 * Fetch the secret keys for self::setSecret() and self::getSecret().
387 * @return string[] Encryption key, HMAC key
389 private function getSecretKeys() {
390 global $wgSessionSecret, $wgSecretKey, $wgSessionPbkdf2Iterations;
392 $wikiSecret = $wgSessionSecret ?
: $wgSecretKey;
393 $userSecret = $this->get( 'wsSessionSecret', null );
394 if ( $userSecret === null ) {
395 $userSecret = \MWCryptRand
::generateHex( 32 );
396 $this->set( 'wsSessionSecret', $userSecret );
398 $iterations = $this->get( 'wsSessionPbkdf2Iterations', null );
399 if ( $iterations === null ) {
400 $iterations = $wgSessionPbkdf2Iterations;
401 $this->set( 'wsSessionPbkdf2Iterations', $iterations );
404 $keymats = hash_pbkdf2( 'sha256', $wikiSecret, $userSecret, $iterations, 64, true );
406 substr( $keymats, 0, 32 ),
407 substr( $keymats, 32, 32 ),
412 * Decide what type of encryption to use, based on system capabilities.
415 private static function getEncryptionAlgorithm() {
416 global $wgSessionInsecureSecrets;
418 if ( self
::$encryptionAlgorithm === null ) {
419 if ( function_exists( 'openssl_encrypt' ) ) {
420 $methods = openssl_get_cipher_methods();
421 if ( in_array( 'aes-256-ctr', $methods, true ) ) {
422 self
::$encryptionAlgorithm = [ 'openssl', 'aes-256-ctr' ];
423 return self
::$encryptionAlgorithm;
425 if ( in_array( 'aes-256-cbc', $methods, true ) ) {
426 self
::$encryptionAlgorithm = [ 'openssl', 'aes-256-cbc' ];
427 return self
::$encryptionAlgorithm;
431 if ( function_exists( 'mcrypt_encrypt' )
432 && in_array( 'rijndael-128', mcrypt_list_algorithms(), true )
434 $modes = mcrypt_list_modes();
435 if ( in_array( 'ctr', $modes, true ) ) {
436 self
::$encryptionAlgorithm = [ 'mcrypt', 'rijndael-128', 'ctr' ];
437 return self
::$encryptionAlgorithm;
439 if ( in_array( 'cbc', $modes, true ) ) {
440 self
::$encryptionAlgorithm = [ 'mcrypt', 'rijndael-128', 'cbc' ];
441 return self
::$encryptionAlgorithm;
445 if ( $wgSessionInsecureSecrets ) {
446 // @todo: import a pure-PHP library for AES instead of this
447 self
::$encryptionAlgorithm = [ 'insecure' ];
448 return self
::$encryptionAlgorithm;
451 throw new \
BadMethodCallException(
452 'Encryption is not available. You really should install the PHP OpenSSL extension, ' .
453 'or failing that the mcrypt extension. But if you really can\'t and you\'re willing ' .
454 'to accept insecure storage of sensitive session data, set ' .
455 '$wgSessionInsecureSecrets = true in LocalSettings.php to make this exception go away.'
459 return self
::$encryptionAlgorithm;
463 * Set a value in the session, encrypted
465 * This relies on the secrecy of $wgSecretKey (by default), or $wgSessionSecret.
467 * @param string|int $key
468 * @param mixed $value
470 public function setSecret( $key, $value ) {
471 list( $encKey, $hmacKey ) = $this->getSecretKeys();
472 $serialized = serialize( $value );
474 // The code for encryption (with OpenSSL) and sealing is taken from
475 // Chris Steipp's OATHAuthUtils class in Extension::OATHAuth.
478 // @todo: import a pure-PHP library for AES instead of doing $wgSessionInsecureSecrets
479 $iv = \MWCryptRand
::generate( 16, true );
480 $algorithm = self
::getEncryptionAlgorithm();
481 switch ( $algorithm[0] ) {
483 $ciphertext = openssl_encrypt( $serialized, $algorithm[1], $encKey, OPENSSL_RAW_DATA
, $iv );
484 if ( $ciphertext === false ) {
485 throw new \
UnexpectedValueException( 'Encryption failed: ' . openssl_error_string() );
490 $blocksize = mcrypt_get_block_size( $algorithm[1], $algorithm[2] );
491 $pad = $blocksize - ( strlen( $serialized ) %
$blocksize );
492 $serialized .= str_repeat( chr( $pad ), $pad );
494 $ciphertext = mcrypt_encrypt( $algorithm[1], $encKey, $serialized, $algorithm[2], $iv );
495 if ( $ciphertext === false ) {
496 throw new \
UnexpectedValueException( 'Encryption failed' );
500 $ex = new \
Exception( 'No encryption is available, storing data as plain text' );
501 $this->logger
->warning( $ex->getMessage(), [ 'exception' => $ex ] );
502 $ciphertext = $serialized;
505 throw new \
LogicException( 'invalid algorithm' );
509 $sealed = base64_encode( $iv ) . '.' . base64_encode( $ciphertext );
510 $hmac = hash_hmac( 'sha256', $sealed, $hmacKey, true );
511 $encrypted = base64_encode( $hmac ) . '.' . $sealed;
514 $this->set( $key, $encrypted );
518 * Fetch a value from the session that was set with self::setSecret()
519 * @param string|int $key
520 * @param mixed $default Returned if $this->exists( $key ) would be false or decryption fails
523 public function getSecret( $key, $default = null ) {
525 $encrypted = $this->get( $key, null );
526 if ( $encrypted === null ) {
530 // The code for unsealing, checking, and decrypting (with OpenSSL) is
531 // taken from Chris Steipp's OATHAuthUtils class in
532 // Extension::OATHAuth.
535 $pieces = explode( '.', $encrypted );
536 if ( count( $pieces ) !== 3 ) {
537 $ex = new \
Exception( 'Invalid sealed-secret format' );
538 $this->logger
->warning( $ex->getMessage(), [ 'exception' => $ex ] );
541 list( $hmac, $iv, $ciphertext ) = $pieces;
542 list( $encKey, $hmacKey ) = $this->getSecretKeys();
543 $integCalc = hash_hmac( 'sha256', $iv . '.' . $ciphertext, $hmacKey, true );
544 if ( !hash_equals( $integCalc, base64_decode( $hmac ) ) ) {
545 $ex = new \
Exception( 'Sealed secret has been tampered with, aborting.' );
546 $this->logger
->warning( $ex->getMessage(), [ 'exception' => $ex ] );
551 $algorithm = self
::getEncryptionAlgorithm();
552 switch ( $algorithm[0] ) {
554 $serialized = openssl_decrypt( base64_decode( $ciphertext ), $algorithm[1], $encKey,
555 OPENSSL_RAW_DATA
, base64_decode( $iv ) );
556 if ( $serialized === false ) {
557 $ex = new \
Exception( 'Decyption failed: ' . openssl_error_string() );
558 $this->logger
->debug( $ex->getMessage(), [ 'exception' => $ex ] );
563 $serialized = mcrypt_decrypt( $algorithm[1], $encKey, base64_decode( $ciphertext ),
564 $algorithm[2], base64_decode( $iv ) );
565 if ( $serialized === false ) {
566 $ex = new \
Exception( 'Decyption failed' );
567 $this->logger
->debug( $ex->getMessage(), [ 'exception' => $ex ] );
571 // Remove PKCS7 padding
572 $pad = ord( substr( $serialized, -1 ) );
573 $serialized = substr( $serialized, 0, -$pad );
576 $ex = new \
Exception(
577 'No encryption is available, retrieving data that was stored as plain text'
579 $this->logger
->warning( $ex->getMessage(), [ 'exception' => $ex ] );
580 $serialized = base64_decode( $ciphertext );
583 throw new \
LogicException( 'invalid algorithm' );
586 $value = unserialize( $serialized );
587 if ( $value === false && $serialized !== serialize( false ) ) {
594 * Delay automatic saving while multiple updates are being made
596 * Calls to save() or clear() will not be delayed.
598 * @return \ScopedCallback When this goes out of scope, a save will be triggered
600 public function delaySave() {
601 return $this->backend
->delaySave();
607 public function save() {
608 $this->backend
->save();
612 * @name Interface methods
616 public function count() {
617 $data = &$this->backend
->getData();
618 return count( $data );
621 public function current() {
622 $data = &$this->backend
->getData();
623 return current( $data );
626 public function key() {
627 $data = &$this->backend
->getData();
631 public function next() {
632 $data = &$this->backend
->getData();
636 public function rewind() {
637 $data = &$this->backend
->getData();
641 public function valid() {
642 $data = &$this->backend
->getData();
643 return key( $data ) !== null;
647 * @note Despite the name, this seems to be intended to implement isset()
648 * rather than array_key_exists(). So do that.
650 public function offsetExists( $offset ) {
651 $data = &$this->backend
->getData();
652 return isset( $data[$offset] );
656 * @note This supports indirect modifications but can't mark the session
657 * dirty when those happen. SessionBackend::save() checks the hash of the
658 * data to detect such changes.
659 * @note Accessing a nonexistent key via this mechanism causes that key to
660 * be created with a null value, and does not raise a PHP warning.
662 public function &offsetGet( $offset ) {
663 $data = &$this->backend
->getData();
664 if ( !array_key_exists( $offset, $data ) ) {
665 $ex = new \
Exception( "Undefined index (auto-adds to session with a null value): $offset" );
666 $this->logger
->debug( $ex->getMessage(), [ 'exception' => $ex ] );
668 return $data[$offset];
671 public function offsetSet( $offset, $value ) {
672 $this->set( $offset, $value );
675 public function offsetUnset( $offset ) {
676 $this->remove( $offset );