t3lib/formprotection/class.t3lib_formprotection_abstract.php

   1 <?php
   2 /***************************************************************
   3 * Copyright notice
   4 *
   5 * (c) 2010 Oliver Klee <typo3-coding@oliverklee.de>
   6 * All rights reserved
   7 *
   8 * This script is part of the TYPO3 project. The TYPO3 project is
   9 * free software; you can redistribute it and/or modify
  10 * it under the terms of the GNU General Public License as published by
  11 * the Free Software Foundation; either version 2 of the License, or
  12 * (at your option) any later version.
  13 *
  14 * The GNU General Public License can be found at
  15 * http://www.gnu.org/copyleft/gpl.html.
  16 *
  17 * This script is distributed in the hope that it will be useful,
  18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 * GNU General Public License for more details.
  21 *
  22 * This copyright notice MUST APPEAR in all copies of the script!
  23 ***************************************************************/
  24
  25 /**
  26  * Class t3lib_formprotection_Abstract.
  27  *
  28  * This class provides protection against cross-site request forgery (XSRF/CSRF)
  29  * for forms.
  30  *
  31  * For documentation on how to use this class, please see the documentation of
  32  * the corresponding subclasses, e.g. t3lib_formprotection_BackendFormProtection.
  33  *
  34  * $Id$
  35  *
  36  * @package TYPO3
  37  * @subpackage t3lib
  38  *
  39  * @author Oliver Klee <typo3-coding@oliverklee.de>
  40  */
  41 abstract class t3lib_formprotection_Abstract {
  42         /**
  43          * the maximum number of tokens that can exist at the same time
  44          *
  45          * @var integer
  46          */
  47         protected $maximumNumberOfTokens = 0;
  48
  49         /**
  50          * Valid tokens sorted from oldest to newest.
  51          *
  52          * [tokenId] => array(formName, formInstanceName)
  53          *
  54          * @var array<array>
  55          */
  56         protected $tokens = array();
  57
  58         /**
  59          * Constructor. Makes sure existing tokens are read and available for
  60          * checking.
  61          */
  62         public function __construct() {
  63                 $this->retrieveTokens();
  64         }
  65
  66         /**
  67          * Frees as much memory as possible.
  68          */
  69         public function __destruct() {
  70                 $this->tokens = array();
  71         }
  72
  73         /**
  74          * Deletes all existing tokens and persists the (empty) token table.
  75          *
  76          * This function is intended to be called when a user logs on or off.
  77          *
  78          * @return void
  79          */
  80         public function clean() {
  81                 $this->tokens = array();
  82                 $this->persistTokens();
  83         }
  84
  85         /**
  86          * Generates and stores a token for a form.
  87          *
  88          * Calling this function two times with the same parameters will create
  89          * two valid, different tokens.
  90          *
  91          * Generating more tokens than $maximumNumberOfEntries will cause the oldest
  92          * tokens to get dropped.
  93          *
  94          * Note: This function does not persist the tokens.
  95          *
  96          * @param string $formName
  97          *        the name of the form, for example a table name like "tt_content",
  98          *        or some other identifier like "install_tool_password", must not be
  99          *        empty
 100          * @param string $action
 101          *        the name of the action of the form, for example "new", "delete" or
 102          *        "edit", may also be empty
 103          * @param string $formInstanceName
 104          *        a string used to differentiate two instances of the same form,
 105          *        form example a record UID or a comma-separated list of UIDs,
 106          *        may also be empty
 107          *
 108          * @return string the 32-character hex ID of the generated token
 109          */
 110         public function generateToken(
 111                 $formName, $action = '', $formInstanceName = ''
 112         ) {
 113                 if ($formName == '') {
 114                         throw new InvalidArgumentException('$formName must not be empty.');
 115                 }
 116
 117                 do {
 118                         $tokenId = bin2hex(t3lib_div::generateRandomBytes(16));
 119                 } while (isset($this->tokens[$tokenId]));
 120
 121                 $this->tokens[$tokenId] = array(
 122                         'formName' => $formName,
 123                         'action' => $action,
 124                         'formInstanceName' => $formInstanceName,
 125                 );
 126                 $this->preventOverflow();
 127
 128                 return $tokenId;
 129         }
 130
 131         /**
 132          * Checks whether the token $tokenId is valid in the form $formName with
 133          * $formInstanceName.
 134          *
 135          * A token is valid if $tokenId, $formName and $formInstanceName match and
 136          * the token has not been used yet.
 137          *
 138          * Calling this function will mark the token $tokenId as invalud (if it
 139          * exists).
 140          *
 141          * So calling this function with the same parameters two times will return
 142          * FALSE the second time.
 143          *
 144          * @param string $tokenId
 145          *        a form token to check, may also be empty or utterly misformed
 146          * @param string $formName
 147          *        the name of the form to check, for example "tt_content",
 148          *        may also be empty or utterly misformed
 149          * @param string $action
 150          *        the action of the form to check, for example "edit",
 151          *        may also be empty or utterly misformed
 152          * @param string $formInstanceName
 153          *        the instance name of the form to check, for example "42" or "foo"
 154          *        or "31,42", may also be empty or utterly misformed
 155          *
 156          * @return boolean
 157          *         TRUE if $tokenId, $formName, $action and $formInstanceName match
 158          *         and the token has not been used yet, FALSE otherwise
 159          */
 160         public function validateToken(
 161                 $tokenId, $formName, $action = '', $formInstanceName = ''
 162         ) {
 163                 if (isset($this->tokens[$tokenId])) {
 164                         $token = $this->tokens[$tokenId];
 165                         $isValid = ($token['formName'] == $formName)
 166                                 && ($token['action'] == $action)
 167                                 && ($token['formInstanceName'] == $formInstanceName);
 168                         $this->dropToken($tokenId);
 169                 } else {
 170                         $isValid = FALSE;
 171                 }
 172
 173                 if (!$isValid) {
 174                         $this->createValidationErrorMessage();
 175                 }
 176
 177                 return $isValid;
 178         }
 179
 180         /**
 181          * Creates or displayes an error message telling the user that the submitted
 182          * form token is invalid.
 183          *
 184          * This function may also be empty if the validation error should be handled
 185          * silently.
 186          *
 187          * @return void
 188          */
 189         abstract protected function createValidationErrorMessage();
 190
 191         /**
 192          * Retrieves all saved tokens.
 193          *
 194          * @return array<arrray>
 195          *         the saved tokens, will be empty if no tokens have been saved
 196          */
 197         abstract protected function retrieveTokens();
 198
 199         /**
 200          * Saves the tokens so that they can be used by a later incarnation of this
 201          * class.
 202          *
 203          * @return void
 204          */
 205         abstract public function persistTokens();
 206
 207         /**
 208          * Drops the token with the ID $tokenId.
 209          *
 210          * If there is no token with that ID, this function is a no-op.
 211          *
 212          * Note: This function does not persist the tokens.
 213          *
 214          * @param string $tokenId
 215          *        the 32-character ID of an existing token, must not be empty
 216          *
 217          * @return void
 218          */
 219         protected function dropToken($tokenId) {
 220                 if (isset($this->tokens[$tokenId])) {
 221                         unset($this->tokens[$tokenId]);
 222                 }
 223         }
 224
 225         /**
 226          * Checks whether the number of current tokens still is at most
 227          * $this->maximumNumberOfTokens.
 228          *
 229          * If there are more tokens, the oldest tokens are removed until the number
 230          * of tokens is low enough.
 231          *
 232          * Note: This function does not persist the tokens.
 233          *
 234          * @return void
 235          */
 236         protected function preventOverflow() {
 237                 if (empty($this->tokens)) {
 238                         return;
 239                 }
 240
 241                 while (count($this->tokens) > $this->maximumNumberOfTokens) {
 242                         reset($this->tokens);
 243                         $this->dropToken(key($this->tokens));
 244                 }
 245         }
 246 }
 247 ?>