[Summary view] [Print] [Text view]

   1  <?php
   2  # MantisBT - A PHP based bugtracking system
   3  
   4  # MantisBT is free software: you can redistribute it and/or modify
   5  # it under the terms of the GNU General Public License as published by
   6  # the Free Software Foundation, either version 2 of the License, or
   7  # (at your option) any later version.
   8  #
   9  # MantisBT is distributed in the hope that it will be useful,
  10  # but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  # GNU General Public License for more details.
  13  #
  14  # You should have received a copy of the GNU General Public License
  15  # along with MantisBT.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * Tokens API
  19   *
  20   * This implements temporary storage of strings.
  21   * DB schema: id, type, owner, timestamp, value
  22   *
  23   * @package CoreAPI
  24   * @subpackage TokensAPI
  25   * @copyright Copyright (C) 2000 - 2002  Kenzaburo Ito - kenito@300baud.org
  26   * @copyright Copyright (C) 2002 - 2011  MantisBT Team - mantisbt-dev@lists.sourceforge.net
  27   * @link http://www.mantisbt.org
  28   *
  29   * @uses authentication_api.php
  30   * @uses constant_inc.php
  31   * @uses database_api.php
  32   */
  33  
  34  require_api( 'authentication_api.php' );
  35  require_api( 'constant_inc.php' );
  36  require_api( 'database_api.php' );
  37  
  38  # Set up global for token_purge_expired_once()
  39  $g_tokens_purged = false;
  40  
  41  /**
  42   * Check if a token exists.
  43   * @param integer Token ID
  44   * @return boolean True if token exists
  45   */
  46  function token_exists( $p_token_id ) {
  47      $c_token_id = db_prepare_int( $p_token_id );
  48      $t_tokens_table = db_get_table( 'tokens' );
  49  
  50      $t_query = "SELECT id
  51                        FROM $t_tokens_table
  52                        WHERE id=" . db_param();
  53      $t_result = db_query_bound( $t_query, Array( $c_token_id ), 1 );
  54  
  55      return( 1 == db_num_rows( $t_result ) );
  56  }
  57  
  58  /**
  59   * Make sure a token exists.
  60   * @param integer Token ID
  61   * @return boolean True if token exists
  62   */
  63  function token_ensure_exists( $p_token_id ) {
  64      if( !token_exists( $p_token_id ) ) {
  65          trigger_error( ERROR_TOKEN_NOT_FOUND, ERROR );
  66      }
  67  
  68      return true;
  69  }
  70  
  71  # High-level CRUD Usage
  72  /**
  73   * Get a token's information
  74   * @param integer Token type
  75   * @param integer User ID
  76   * @return array Token row
  77   */
  78  function token_get( $p_type, $p_user_id = null ) {
  79      token_purge_expired_once();
  80  
  81      $c_type = db_prepare_int( $p_type );
  82      $c_user_id = db_prepare_int( $p_user_id == null ? auth_get_current_user_id() : $p_user_id );
  83  
  84      $t_tokens_table = db_get_table( 'tokens' );
  85  
  86      $t_query = "SELECT * FROM $t_tokens_table
  87                      WHERE type=" . db_param() . " AND owner=" . db_param();
  88      $t_result = db_query_bound( $t_query, Array( $c_type, $c_user_id ) );
  89  
  90      if( db_num_rows( $t_result ) > 0 ) {
  91          return db_fetch_array( $t_result );
  92      }
  93  
  94      return null;
  95  }
  96  
  97  /**
  98   * Get a token's value or null if not found
  99   * @param integer Token type
 100   * @param integer User ID (null for current user)
 101   * @return array Token row
 102   */
 103  function token_get_value( $p_type, $p_user_id = null ) {
 104      $t_token = token_get( $p_type, $p_user_id );
 105  
 106      if( null !== $t_token ) {
 107          return $t_token['value'];
 108      }
 109  
 110      return null;
 111  }
 112  
 113  /**
 114   * Create or update a token's value and expiration
 115   * @param integer Token type
 116   * @param string Token value
 117   * @param integer Token expiration in seconds
 118   * @param integer User ID
 119   * @return integer Token ID
 120   */
 121  function token_set( $p_type, $p_value, $p_expiry = TOKEN_EXPIRY, $p_user_id = null ) {
 122      $t_token = token_get( $p_type, $p_user_id );
 123      if( $t_token === null ) {
 124          return token_create( $p_type, $p_value, $p_expiry, $p_user_id );
 125      }
 126  
 127      token_update( $t_token['id'], $p_value, $p_expiry );
 128      return $t_token['id'];
 129  }
 130  
 131  /**
 132   * Touch a token to update its expiration time.
 133   * @param integer Token ID
 134   * @param integer Token expiration in seconds
 135   * @return always true
 136   */
 137  function token_touch( $p_token_id, $p_expiry = TOKEN_EXPIRY ) {
 138      token_ensure_exists( $p_token_id );
 139  
 140      $c_token_id = db_prepare_int( $p_token_id );
 141      $c_token_expiry = time() + $p_expiry;
 142      $t_tokens_table = db_get_table( 'tokens' );
 143  
 144      $t_query = "UPDATE $t_tokens_table
 145                      SET expiry=" . db_param() . "
 146                      WHERE id=" . db_param();
 147      db_query_bound( $t_query, Array( $c_token_expiry, $c_token_id ) );
 148  
 149      return true;
 150  }
 151  
 152  /**
 153   * Delete a token.
 154   * @param integer Token type
 155   * @param integer User ID or null for current logged in user.
 156   * @return always true
 157   */
 158  function token_delete( $p_type, $p_user_id = null ) {
 159      $c_type = db_prepare_int( $p_type );
 160      $c_user_id = db_prepare_int( $p_user_id == null ? auth_get_current_user_id() : $p_user_id );
 161  
 162      $t_tokens_table = db_get_table( 'tokens' );
 163  
 164      $t_query = "DELETE FROM $t_tokens_table
 165                      WHERE type=" . db_param() . " AND owner=" . db_param();
 166      db_query_bound( $t_query, Array( $c_type, $c_user_id ) );
 167  
 168      return true;
 169  }
 170  
 171  /**
 172   * Delete all tokens owned by a specified user.
 173   * @param integer User ID or null for current logged in user.
 174   * @return always true
 175   */
 176  function token_delete_by_owner( $p_user_id = null ) {
 177      if( $p_user_id == null ) {
 178          $c_user_id = auth_get_current_user_id();
 179      } else {
 180          $c_user_id = db_prepare_int( $p_user_id );
 181      }
 182  
 183      $t_tokens_table = db_get_table( 'tokens' );
 184  
 185      # Remove
 186      $t_query = "DELETE FROM $t_tokens_table
 187                        WHERE owner=" . db_param();
 188      db_query_bound( $t_query, Array( $c_user_id ) );
 189  
 190      return true;
 191  }
 192  
 193  # Low-level CRUD, not for general use
 194  /**
 195   * Create a token.
 196   * @param integer Token type
 197   * @param string Token value
 198   * @param integer Token expiration in seconds
 199   * @param integer User ID
 200   * @return integer Token ID
 201   */
 202  function token_create( $p_type, $p_value, $p_expiry = TOKEN_EXPIRY, $p_user_id = null ) {
 203      $c_type = db_prepare_int( $p_type );
 204      $c_timestamp = db_now();
 205      $c_expiry = time() + $p_expiry;
 206      $c_user_id = db_prepare_int( $p_user_id == null ? auth_get_current_user_id() : $p_user_id );
 207  
 208      $t_tokens_table = db_get_table( 'tokens' );
 209  
 210      $t_query = "INSERT INTO $t_tokens_table
 211                      ( type, value, timestamp, expiry, owner )
 212                      VALUES ( " . db_param() . ', ' . db_param() . ', ' . db_param() . ', ' . db_param() . ', ' . db_param() . ' )';
 213      db_query_bound( $t_query, Array( $c_type, $p_value, $c_timestamp, $c_expiry, $c_user_id ) );
 214      return db_insert_id( $t_tokens_table );
 215  }
 216  
 217  /**
 218   * Update a token
 219   * @param integer Token ID
 220   * @param string Token value
 221   * @param integer Token expiration in seconds
 222   * @return always true.
 223   */
 224  function token_update( $p_token_id, $p_value, $p_expiry = TOKEN_EXPIRY ) {
 225      token_ensure_exists( $p_token_id );
 226      $c_token_id = db_prepare_int( $p_token_id );
 227      $c_expiry = time() + $p_expiry;
 228  
 229      $t_tokens_table = db_get_table( 'tokens' );
 230  
 231      $t_query = "UPDATE $t_tokens_table
 232                      SET value=" . db_param() . ", expiry=" . db_param() . "
 233                      WHERE id=" . db_param();
 234      db_query_bound( $t_query, Array( $p_value, $c_expiry, $c_token_id ) );
 235  
 236      return true;
 237  }
 238  
 239  /**
 240   * Delete all tokens of a specified type.
 241   * @param integer Token Type
 242   * @return always true.
 243   */
 244  function token_delete_by_type( $p_token_type ) {
 245      $c_token_type = db_prepare_int( $p_token_type );
 246  
 247      $t_tokens_table = db_get_table( 'tokens' );
 248  
 249      # Remove
 250      $t_query = "DELETE FROM $t_tokens_table
 251                        WHERE type=" . db_param();
 252      db_query_bound( $t_query, Array( $c_token_type ) );
 253  
 254      return true;
 255  }
 256  
 257  /**
 258   * Purge all expired tokens.
 259   * @param integer Token type
 260   * @return always true.
 261   */
 262  function token_purge_expired( $p_token_type = null ) {
 263      global $g_tokens_purged;
 264  
 265      $t_tokens_table = db_get_table( 'tokens' );
 266  
 267      $t_query = "DELETE FROM $t_tokens_table WHERE " . db_param() . " > expiry";
 268      if( !is_null( $p_token_type ) ) {
 269          $c_token_type = db_prepare_int( $p_token_type );
 270          $t_query .= " AND type=" . db_param();
 271          db_query_bound( $t_query, Array( db_now(), $c_token_type ) );
 272      } else {
 273          db_query_bound( $t_query, Array( db_now() ) );
 274      }
 275  
 276      $g_tokens_purged = true;
 277  
 278      return true;
 279  }
 280  
 281  /**
 282   * Purge all expired tokens only once per session.
 283   */
 284  function token_purge_expired_once() {
 285      global $g_tokens_purged;
 286      if( !$g_tokens_purged ) {
 287          token_purge_expired();
 288      }
 289  }