includes/Token.php

   1 <?php
   2 /**
   3  * Copyright © 2010
   4  * http://www.mediawiki.org/
   5  *
   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.
  10  *
  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.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  * http://www.gnu.org/copyleft/gpl.html
  20  *
  21  * @file
  22  */
  23
  24 /**
  25  * CSRF attacks (where a malicious website uses frames, <img> tags, or
  26  * similar, to prompt a wiki user to open a wiki page or submit a form,
  27  * without being aware of doing so) are most easily countered by using
  28  * tokens.  For normal browsing, loading the form for a protected action
  29  * sets two copies of a random string: one in the $_SESSION, and one as
  30  * a hidden field in the form.  When the form is submitted, it checks
  31  * that a) the set of cookies submitted with the form *has* a copy of
  32  * the session cookie, and b) that it matches.  Since malicious websites
  33  * don't have control over the session cookies, they can't craft a form
  34  * that can be instantly submitted which will have the appropriate tokens.
  35  *
  36  * Note that these tokens are distinct from those in User::setToken(), which
  37  * are used for persistent session authentication and are retained for as
  38  * long as the user is logged in to the wiki.  These tokens are to protect
  39  * one individual action, and should ideally be cleared once the action is over.
  40  */
  41 class Token {
  42
  43         /*
  44          * Some punctuation to prevent editing from broken
  45          *  text-mangling proxies.
  46          */
  47         const TOKEN_SUFFIX = '+\\';
  48
  49         /**
  50          * Different tokens for different types of action.
  51          *
  52          * We don't store tokens for some actions for anons
  53          * so they can still do things when they have cookies disabled.
  54          * So either use this for actions which anons can't access, or
  55          * where you don't mind an attacker being able to trigger the action
  56          * anonymously from the user's IP.  However, the token is still
  57          * useful because it fails with some broken proxies.
  58          */
  59         const ANONYMOUS = 'Edit';
  60
  61         /**
  62          * For actions requiring a medium level of protection, or where the
  63          * user will be making repeated actions: this token should not be
  64          * cleared once the action is completed.  For instance, a user might
  65          * revert mass vandalism from a user by loading their contribs and
  66          * ctrl+clicking each rollback link.  If we cleared the Token from
  67          * session after each rollback, they'd have to reload the contribs
  68          * page each time, which would be annoying.
  69          */
  70         const PERSISTENT = 'Action';
  71
  72         /**
  73          * For actions requiring a high level of protection, and where the user
  74          * will not be performing multiple sequential actions without reloading
  75          * the form or link.  Eg login, block/protect/delete, userrights, etc.
  76          * Callers should clear these tokens upon completion of the action, and
  77          * other callers should expect that they will be cleared.
  78          */
  79         const UNIQUE = 'Unique';
  80
  81         /**
  82          * String the action which is being protected by the token
  83          * ('edit', 'login', 'rollback', etc)
  84          */
  85         protected $type = self::ANONYMOUS;
  86
  87         /**
  88          * An instance-specific salt. So if you want to generate a hundred rollback
  89          * tokens for the watchlist, pass a $salt which is unique
  90          * to each revision. Only one token is stored in the session, but it is munged
  91          * with a different salt for each revision, so the required value in the HTML
  92          * is different for each case.
  93          */
  94         protected $salt = '';
  95
  96         protected $request;
  97
  98         /**
  99          * Constructor
 100          * @param $salt String an instance-specific salt.  @see Token::$salt
 101          * @param $type Token class constant identifier
 102          * @param $request WebRequest most of the time you'll want to get/store
 103          *     the tokens in $wgRequest, which is the default.
 104          */
 105         public function __construct( $salt, $type = self::PERSISTENT, WebRequest $request = null ){
 106                 global $wgRequest;
 107                 $this->type = $type;
 108
 109                 if( is_array( $this->salt ) ) {
 110                         $this->salt = implode( '|', $this->salt );
 111                 } else {
 112                         $this->salt = strval( $salt );
 113                 }
 114
 115                 $this->request = $request instanceof WebRequest
 116                         ? $request
 117                         : $wgRequest;
 118         }
 119
 120         /**
 121          * Ensure that a token is set in cookies, by setting a new one
 122          * if necessary.
 123          * @param $purge Bool whether to overwrite an existing token in
 124          *     session if there is one.  This is more secure, but will
 125          *     only allow one Token of a particular $action to be used on
 126          *     the page (which may itself be a good thing).
 127          * @return String The version of the token which should be included
 128          *     in the HTML form/link.
 129          */
 130         public function set( $purge = false ) {
 131                 global $wgUser;
 132                 if ( $this->type == self::ANONYMOUS && $wgUser->isAnon() ) {
 133                         return self::TOKEN_SUFFIX;
 134                 }
 135
 136                 if( $purge || $this->get() === null ){
 137                         $token = self::generate();
 138                         if( session_id() == '' ) {
 139                                 wfSetupSession();
 140                         }
 141                         $this->store( $token );
 142                 } else {
 143                         $token = $this->get();
 144                 }
 145
 146                 return md5( $token . $this->salt ) . self::TOKEN_SUFFIX;
 147         }
 148
 149         /**
 150          * Check whether the copy of the token submitted with a form
 151          * matches the version stored in session
 152          * @param $val String version submitted with the form.
 153          * @return Mixed null if no session token was set, Bool false if there
 154          *     was a token but it didn't match, Bool true if it matched correctly
 155          */
 156         public function match( $val ){
 157                 global $wgUser;
 158                 if( $this->type == self::ANONYMOUS && $wgUser->isAnon() ){
 159                         return $val === self::TOKEN_SUFFIX;
 160                 }
 161
 162                 if( $this->get() === null ){
 163                         return null;
 164                 }
 165
 166                 return md5( $this->get() . $this->salt ) . self::TOKEN_SUFFIX === $val;
 167         }
 168
 169         /**
 170          * Delete the token after use, so it can't be used again.  This will
 171          * invalidate all tokens for this Token's action type.
 172          */
 173         public function clear(){
 174                 $this->store( null );
 175         }
 176
 177         /**
 178          * Prepare a new Token for a given action, set it in session, and
 179          * return the value we need to pass in the HTML
 180          * @param $salt String
 181          * @param $type Token class constant identifier
 182          * @return String token string to store in HTML
 183          */
 184         public static function prepare( $salt, $type = self::PERSISTENT ){
 185                 $t = new Token( $salt, $type );
 186                 return $t->set( false );
 187         }
 188
 189         /**
 190          * Generate a random token
 191          * @param $salt String Optional salt value
 192          * @return String 32-char random token
 193          */
 194         protected static function generate( $salt = '' ) {
 195                 $rand = dechex( mt_rand() ) . dechex( mt_rand() );
 196                 return md5( $rand . $salt );
 197         }
 198
 199         /**
 200          * Set the given token for the given action in the session
 201          * @param $token String
 202          * @param $action String
 203          */
 204         protected function store( $token ){
 205                 $this->request->setSessionData( "ws{$this->type}Token", $token );
 206         }
 207
 208         /**
 209          * Get the token set for a given action
 210          * @return String or null if no token was stored in the session
 211          */
 212         protected function get(){
 213                 return $this->request->getSessionData( "ws{$this->type}Token" );
 214         }
 215 }