includes/session/SessionProvider.php

   1 <?php
   2 /**
   3  * MediaWiki session provider base class
   4  *
   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.
   9  *
  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.
  14  *
  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
  19  *
  20  * @file
  21  * @ingroup Session
  22  */
  23
  24 namespace MediaWiki\Session;
  25
  26 use Psr\Log\LoggerAwareInterface;
  27 use Psr\Log\LoggerInterface;
  28 use Config;
  29 use Language;
  30 use WebRequest;
  31
  32 /**
  33  * A SessionProvider provides SessionInfo and support for Session
  34  *
  35  * A SessionProvider is responsible for taking a WebRequest and determining
  36  * the authenticated session that it's a part of. It does this by returning an
  37  * SessionInfo object with basic information about the session it thinks is
  38  * associated with the request, namely the session ID and possibly the
  39  * authenticated user the session belongs to.
  40  *
  41  * The SessionProvider also provides for updating the WebResponse with
  42  * information necessary to provide the client with data that the client will
  43  * send with later requests, and for populating the Vary and Key headers with
  44  * the data necessary to correctly vary the cache on these client requests.
  45  *
  46  * An important part of the latter is indicating whether it even *can* tell the
  47  * client to include such data in future requests, via the persistsSessionId()
  48  * and canChangeUser() methods. The cases are (in order of decreasing
  49  * commonness):
  50  *  - Cannot persist ID, no changing User: The request identifies and
  51  *    authenticates a particular local user, and the client cannot be
  52  *    instructed to include an arbitrary session ID with future requests. For
  53  *    example, OAuth or SSL certificate auth.
  54  *  - Can persist ID and can change User: The client can be instructed to
  55  *    return at least one piece of arbitrary data, that being the session ID.
  56  *    The user identity might also be given to the client, otherwise it's saved
  57  *    in the session data. For example, cookie-based sessions.
  58  *  - Can persist ID but no changing User: The request uniquely identifies and
  59  *    authenticates a local user, and the client can be instructed to return an
  60  *    arbitrary session ID with future requests. For example, HTTP Digest
  61  *    authentication might somehow use the 'opaque' field as a session ID
  62  *    (although getting MediaWiki to return 401 responses without breaking
  63  *    other stuff might be a challenge).
  64  *  - Cannot persist ID but can change User: I can't think of a way this
  65  *    would make sense.
  66  *
  67  * Note that many methods that are technically "cannot persist ID" could be
  68  * turned into "can persist ID but not changing User" using a session cookie,
  69  * as implemented by ImmutableSessionProviderWithCookie. If doing so, different
  70  * session cookie names should be used for different providers to avoid
  71  * collisions.
  72  *
  73  * @ingroup Session
  74  * @since 1.27
  75  */
  76 abstract class SessionProvider implements SessionProviderInterface, LoggerAwareInterface {
  77
  78         /** @var LoggerInterface */
  79         protected $logger;
  80
  81         /** @var Config */
  82         protected $config;
  83
  84         /** @var SessionManager */
  85         protected $manager;
  86
  87         /** @var int Session priority. Used for the default newSessionInfo(), but
  88          * could be used by subclasses too.
  89          */
  90         protected $priority;
  91
  92         /**
  93          * @note To fully initialize a SessionProvider, the setLogger(),
  94          *  setConfig(), and setManager() methods must be called (and should be
  95          *  called in that order). Failure to do so is liable to cause things to
  96          *  fail unexpectedly.
  97          */
  98         public function __construct() {
  99                 $this->priority = SessionInfo::MIN_PRIORITY + 10;
 100         }
 101
 102         public function setLogger( LoggerInterface $logger ) {
 103                 $this->logger = $logger;
 104         }
 105
 106         /**
 107          * Set configuration
 108          * @param Config $config
 109          */
 110         public function setConfig( Config $config ) {
 111                 $this->config = $config;
 112         }
 113
 114         /**
 115          * Set the session manager
 116          * @param SessionManager $manager
 117          */
 118         public function setManager( SessionManager $manager ) {
 119                 $this->manager = $manager;
 120         }
 121
 122         /**
 123          * Get the session manager
 124          * @return SessionManager
 125          */
 126         public function getManager() {
 127                 return $this->manager;
 128         }
 129
 130         /**
 131          * Provide session info for a request
 132          *
 133          * If no session exists for the request, return null. Otherwise return an
 134          * SessionInfo object identifying the session.
 135          *
 136          * If multiple SessionProviders provide sessions, the one with highest
 137          * priority wins. In case of a tie, an exception is thrown.
 138          * SessionProviders are encouraged to make priorities user-configurable
 139          * unless only max-priority makes sense.
 140          *
 141          * @warning This will be called early in the MediaWiki setup process,
 142          *  before $wgUser, $wgLang, $wgOut, $wgParser, $wgTitle, and corresponding
 143          *  pieces of the main RequestContext are set up! If you try to use these,
 144          *  things *will* break.
 145          * @note The SessionProvider must not attempt to auto-create users.
 146          *  MediaWiki will do this later (when it's safe) if the chosen session has
 147          *  a user with a valid name but no ID.
 148          * @protected For use by \\MediaWiki\\Session\\SessionManager only
 149          * @param WebRequest $request
 150          * @return SessionInfo|null
 151          */
 152         abstract public function provideSessionInfo( WebRequest $request );
 153
 154         /**
 155          * Provide session info for a new, empty session
 156          *
 157          * Return null if such a session cannot be created. This base
 158          * implementation assumes that it only makes sense if a session ID can be
 159          * persisted and changing users is allowed.
 160          *
 161          * @protected For use by \\MediaWiki\\Session\\SessionManager only
 162          * @param string|null $id ID to force for the new session
 163          * @return SessionInfo|null
 164          *  If non-null, must return true for $info->isIdSafe(); pass true for
 165          *  $data['idIsSafe'] to ensure this.
 166          */
 167         public function newSessionInfo( $id = null ) {
 168                 if ( $this->canChangeUser() && $this->persistsSessionId() ) {
 169                         return new SessionInfo( $this->priority, array(
 170                                 'id' => $id,
 171                                 'provider' => $this,
 172                                 'persisted' => false,
 173                                 'idIsSafe' => true,
 174                         ) );
 175                 }
 176                 return null;
 177         }
 178
 179         /**
 180          * Merge saved session provider metadata
 181          *
 182          * The default implementation checks that anything in both arrays is
 183          * identical, then returns $providedMetadata.
 184          *
 185          * @protected For use by \\MediaWiki\\Session\\SessionManager only
 186          * @param array $savedMetadata Saved provider metadata
 187          * @param array $providedMetadata Provided provider metadata
 188          * @return array Resulting metadata
 189          * @throws \UnexpectedValueException If the metadata cannot be merged
 190          */
 191         public function mergeMetadata( array $savedMetadata, array $providedMetadata ) {
 192                 foreach ( $providedMetadata as $k => $v ) {
 193                         if ( array_key_exists( $k, $savedMetadata ) && $savedMetadata[$k] !== $v ) {
 194                                 throw new \UnexpectedValueException( "Key \"$k\" changed" );
 195                         }
 196                 }
 197                 return $providedMetadata;
 198         }
 199
 200         /**
 201          * Validate a loaded SessionInfo and refresh provider metadata
 202          *
 203          * This is similar in purpose to the 'SessionCheckInfo' hook, and also
 204          * allows for updating the provider metadata. On failure, the provider is
 205          * expected to write an appropriate message to its logger.
 206          *
 207          * @protected For use by \\MediaWiki\\Session\\SessionManager only
 208          * @param SessionInfo $info
 209          * @param WebRequest $request
 210          * @param array|null &$metadata Provider metadata, may be altered.
 211          * @return bool Return false to reject the SessionInfo after all.
 212          */
 213         public function refreshSessionInfo( SessionInfo $info, WebRequest $request, &$metadata ) {
 214                 return true;
 215         }
 216
 217         /**
 218          * Indicate whether self::persistSession() can save arbitrary session IDs
 219          *
 220          * If false, any session passed to self::persistSession() will have an ID
 221          * that was originally provided by self::provideSessionInfo().
 222          *
 223          * If true, the provider may be passed sessions with arbitrary session IDs,
 224          * and will be expected to manipulate the request in such a way that future
 225          * requests will cause self::provideSessionInfo() to provide a SessionInfo
 226          * with that ID.
 227          *
 228          * For example, a session provider for OAuth would function by matching the
 229          * OAuth headers to a particular user, and then would use self::hashToSessionId()
 230          * to turn the user and OAuth client ID (and maybe also the user token and
 231          * client secret) into a session ID, and therefore can't easily assign that
 232          * user+client a different ID. Similarly, a session provider for SSL client
 233          * certificates would function by matching the certificate to a particular
 234          * user, and then would use self::hashToSessionId() to turn the user and
 235          * certificate fingerprint into a session ID, and therefore can't easily
 236          * assign a different ID either. On the other hand, a provider that saves
 237          * the session ID into a cookie can easily just set the cookie to a
 238          * different value.
 239          *
 240          * @protected For use by \\MediaWiki\\Session\\SessionBackend only
 241          * @return bool
 242          */
 243         abstract public function persistsSessionId();
 244
 245         /**
 246          * Indicate whether the user associated with the request can be changed
 247          *
 248          * If false, any session passed to self::persistSession() will have a user
 249          * that was originally provided by self::provideSessionInfo(). Further,
 250          * self::provideSessionInfo() may only provide sessions that have a user
 251          * already set.
 252          *
 253          * If true, the provider may be passed sessions with arbitrary users, and
 254          * will be expected to manipulate the request in such a way that future
 255          * requests will cause self::provideSessionInfo() to provide a SessionInfo
 256          * with that ID. This can be as simple as not passing any 'userInfo' into
 257          * SessionInfo's constructor, in which case SessionInfo will load the user
 258          * from the saved session's metadata.
 259          *
 260          * For example, a session provider for OAuth or SSL client certificates
 261          * would function by matching the OAuth headers or certificate to a
 262          * particular user, and thus would return false here since it can't
 263          * arbitrarily assign those OAuth credentials or that certificate to a
 264          * different user. A session provider that shoves information into cookies,
 265          * on the other hand, could easily do so.
 266          *
 267          * @protected For use by \\MediaWiki\\Session\\SessionBackend only
 268          * @return bool
 269          */
 270         abstract public function canChangeUser();
 271
 272         /**
 273          * Notification that the session ID was reset
 274          *
 275          * No need to persist here, persistSession() will be called if appropriate.
 276          *
 277          * @protected For use by \\MediaWiki\\Session\\SessionBackend only
 278          * @param SessionBackend $session Session to persist
 279          * @param string $oldId Old session ID
 280          * @codeCoverageIgnore
 281          */
 282         public function sessionIdWasReset( SessionBackend $session, $oldId ) {
 283         }
 284
 285         /**
 286          * Persist a session into a request/response
 287          *
 288          * For example, you might set cookies for the session's ID, user ID, user
 289          * name, and user token on the passed request.
 290          *
 291          * To correctly persist a user independently of the session ID, the
 292          * provider should persist both the user ID (or name, but preferably the
 293          * ID) and the user token. When reading the data from the request, it
 294          * should construct a User object from the ID/name and then verify that the
 295          * User object's token matches the token included in the request. Should
 296          * the tokens not match, an anonymous user *must* be passed to
 297          * SessionInfo::__construct().
 298          *
 299          * When persisting a user independently of the session ID,
 300          * $session->shouldRememberUser() should be checked first. If this returns
 301          * false, the user token *must not* be saved to cookies. The user name
 302          * and/or ID may be persisted, and should be used to construct an
 303          * unverified UserInfo to pass to SessionInfo::__construct().
 304          *
 305          * A backend that cannot persist sesison ID or user info should implement
 306          * this as a no-op.
 307          *
 308          * @protected For use by \\MediaWiki\\Session\\SessionBackend only
 309          * @param SessionBackend $session Session to persist
 310          * @param WebRequest $request Request into which to persist the session
 311          */
 312         abstract public function persistSession( SessionBackend $session, WebRequest $request );
 313
 314         /**
 315          * Remove any persisted session from a request/response
 316          *
 317          * For example, blank and expire any cookies set by self::persistSession().
 318          *
 319          * A backend that cannot persist sesison ID or user info should implement
 320          * this as a no-op.
 321          *
 322          * @protected For use by \\MediaWiki\\Session\\SessionManager only
 323          * @param WebRequest $request Request from which to remove any session data
 324          */
 325         abstract public function unpersistSession( WebRequest $request );
 326
 327         /**
 328          * Prevent future sessions for the user
 329          *
 330          * If the provider is capable of returning a SessionInfo with a verified
 331          * UserInfo for the named user in some manner other than by validating
 332          * against $user->getToken(), steps must be taken to prevent that from
 333          * occurring in the future. This might add the username to a blacklist, or
 334          * it might just delete whatever authentication credentials would allow
 335          * such a session in the first place (e.g. remove all OAuth grants or
 336          * delete record of the SSL client certificate).
 337          *
 338          * The intention is that the named account will never again be usable for
 339          * normal login (i.e. there is no way to undo the prevention of access).
 340          *
 341          * Note that the passed user name might not exist locally (i.e.
 342          * User::idFromName( $username ) === 0); the name should still be
 343          * prevented, if applicable.
 344          *
 345          * @protected For use by \\MediaWiki\\Session\\SessionManager only
 346          * @param string $username
 347          */
 348         public function preventSessionsForUser( $username ) {
 349                 if ( !$this->canChangeUser() ) {
 350                         throw new \BadMethodCallException(
 351                                 __METHOD__ . ' must be implmented when canChangeUser() is false'
 352                         );
 353                 }
 354         }
 355
 356         /**
 357          * Return the HTTP headers that need varying on.
 358          *
 359          * The return value is such that someone could theoretically do this:
 360          * @code
 361          *  foreach ( $provider->getVaryHeaders() as $header => $options ) {
 362          *      $outputPage->addVaryHeader( $header, $options );
 363          *  }
 364          * @endcode
 365          *
 366          * @protected For use by \\MediaWiki\\Session\\SessionManager only
 367          * @return array
 368          */
 369         public function getVaryHeaders() {
 370                 return array();
 371         }
 372
 373         /**
 374          * Return the list of cookies that need varying on.
 375          * @protected For use by \\MediaWiki\\Session\\SessionManager only
 376          * @return string[]
 377          */
 378         public function getVaryCookies() {
 379                 return array();
 380         }
 381
 382         /**
 383          * Get a suggested username for the login form
 384          * @protected For use by \\MediaWiki\\Session\\SessionBackend only
 385          * @param WebRequest $request
 386          * @return string|null
 387          */
 388         public function suggestLoginUsername( WebRequest $request ) {
 389                 return null;
 390         }
 391
 392         /**
 393          * Fetch the rights allowed the user when the specified session is active.
 394          * @param SessionBackend $backend
 395          * @return null|string[] Allowed user rights, or null to allow all.
 396          */
 397         public function getAllowedUserRights( SessionBackend $backend ) {
 398                 if ( $backend->getProvider() !== $this ) {
 399                         // Not that this should ever happen...
 400                         throw new \InvalidArgumentException( 'Backend\'s provider isn\'t $this' );
 401                 }
 402
 403                 return null;
 404         }
 405
 406         /**
 407          * @note Only override this if it makes sense to instantiate multiple
 408          *  instances of the provider. Value returned must be unique across
 409          *  configured providers. If you override this, you'll likely need to
 410          *  override self::describeMessage() as well.
 411          * @return string
 412          */
 413         public function __toString() {
 414                 return get_class( $this );
 415         }
 416
 417         /**
 418          * Return a Message identifying this session type
 419          *
 420          * This default implementation takes the class name, lowercases it,
 421          * replaces backslashes with dashes, and prefixes 'sessionprovider-' to
 422          * determine the message key. For example, MediaWiki\\Session\\CookieSessionProvider
 423          * produces 'sessionprovider-mediawiki-session-cookiesessionprovider'.
 424          *
 425          * @note If self::__toString() is overridden, this will likely need to be
 426          *  overridden as well.
 427          * @warning This will be called early during MediaWiki startup. Do not
 428          *  use $wgUser, $wgLang, $wgOut, $wgParser, or their equivalents via
 429          *  RequestContext from this method!
 430          * @return Message
 431          */
 432         protected function describeMessage() {
 433                 return wfMessage(
 434                         'sessionprovider-' . str_replace( '\\', '-', strtolower( get_class( $this ) ) )
 435                 );
 436         }
 437
 438         public function describe( Language $lang ) {
 439                 $msg = $this->describeMessage();
 440                 $msg->inLanguage( $lang );
 441                 if ( $msg->isDisabled() ) {
 442                         $msg = wfMessage( 'sessionprovider-generic', (string)$this )->inLanguage( $lang );
 443                 }
 444                 return $msg->plain();
 445         }
 446
 447         public function whyNoSession() {
 448                 return null;
 449         }
 450
 451         /**
 452          * Hash data as a session ID
 453          *
 454          * Generally this will only be used when self::persistsSessionId() is false and
 455          * the provider has to base the session ID on the verified user's identity
 456          * or other static data.
 457          *
 458          * @param string $data
 459          * @param string|null $key Defaults to $this->config->get( 'SecretKey' )
 460          * @return string
 461          */
 462         final protected function hashToSessionId( $data, $key = null ) {
 463                 if ( !is_string( $data ) ) {
 464                         throw new \InvalidArgumentException(
 465                                 '$data must be a string, ' . gettype( $data ) . ' was passed'
 466                         );
 467                 }
 468                 if ( $key !== null && !is_string( $key ) ) {
 469                         throw new \InvalidArgumentException(
 470                                 '$key must be a string or null, ' . gettype( $key ) . ' was passed'
 471                         );
 472                 }
 473
 474                 $hash = \MWCryptHash::hmac( "$this\n$data", $key ?: $this->config->get( 'SecretKey' ), false );
 475                 if ( strlen( $hash ) < 32 ) {
 476                         // Should never happen, even md5 is 128 bits
 477                         // @codeCoverageIgnoreStart
 478                         throw new \UnexpectedValueException( 'Hash fuction returned less than 128 bits' );
 479                         // @codeCoverageIgnoreEnd
 480                 }
 481                 if ( strlen( $hash ) >= 40 ) {
 482                         $hash = wfBaseConvert( $hash, 16, 32, 32 );
 483                 }
 484                 return substr( $hash, -32 );
 485         }
 486
 487 }