[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * auth/basic.class.php
   4   *
   5   * foundation authorisation class
   6   * all auth classes should inherit from this class
   7   *
   8   * @author    Chris Smith <chris@jalakai.co.uk>
   9   */
  10  
  11  class auth_basic {
  12  
  13    var $success = true;
  14  
  15  
  16    /**
  17     * Posible things an auth backend module may be able to
  18     * do. The things a backend can do need to be set to true
  19     * in the constructor.
  20     */
  21    var $cando = array (
  22      'addUser'     => false, // can Users be created?
  23      'delUser'     => false, // can Users be deleted?
  24      'modLogin'    => false, // can login names be changed?
  25      'modPass'     => false, // can passwords be changed?
  26      'modName'     => false, // can real names be changed?
  27      'modMail'     => false, // can emails be changed?
  28      'modGroups'   => false, // can groups be changed?
  29      'getUsers'    => false, // can a (filtered) list of users be retrieved?
  30      'getUserCount'=> false, // can the number of users be retrieved?
  31      'getGroups'   => false, // can a list of available groups be retrieved?
  32      'external'    => false, // does the module do external auth checking?
  33      'logoff'      => false, // has the module some special logoff method?
  34    );
  35  
  36  
  37    /**
  38     * Constructor.
  39     *
  40     * Carry out sanity checks to ensure the object is
  41     * able to operate. Set capabilities in $this->cando
  42     * array here
  43     *
  44     * Set $this->success to false if checks fail
  45     *
  46     * @author  Christopher Smith <chris@jalakai.co.uk>
  47     */
  48    function auth_basic() {
  49       // the base class constructor does nothing, derived class
  50      // constructors do the real work
  51    }
  52  
  53    /**
  54     * Capability check. [ DO NOT OVERRIDE ]
  55     *
  56     * Checks the capabilities set in the $this->cando array and
  57     * some pseudo capabilities (shortcutting access to multiple
  58     * ones)
  59     *
  60     * ususal capabilities start with lowercase letter
  61     * shortcut capabilities start with uppercase letter
  62     *
  63     * @author  Andreas Gohr <andi@splitbrain.org>
  64     * @return  bool
  65     */
  66    function canDo($cap) {
  67      switch($cap){
  68        case 'Profile':
  69          // can at least one of the user's properties be changed?
  70          return ( $this->cando['modPass']  ||
  71                   $this->cando['modName']  ||
  72                   $this->cando['modMail'] );
  73          break;
  74        case 'UserMod':
  75          // can at least anything be changed?
  76          return ( $this->cando['modPass']   ||
  77                   $this->cando['modName']   ||
  78                   $this->cando['modMail']   ||
  79                   $this->cando['modLogin']  ||
  80                   $this->cando['modGroups'] ||
  81                   $this->cando['modMail'] );
  82          break;
  83        default:
  84          // print a helping message for developers
  85          if(!isset($this->cando[$cap])){
  86            msg("Check for unknown capability '$cap' - Do you use an outdated Plugin?",-1);
  87          }
  88          return $this->cando[$cap];
  89      }
  90    }
  91  
  92    /**
  93     * Trigger the AUTH_USERDATA_CHANGE event and call the modification function. [ DO NOT OVERRIDE ]
  94     *
  95     * You should use this function instead of calling createUser, modifyUser or
  96     * deleteUsers directly. The event handlers can prevent the modification, for
  97     * example for enforcing a user name schema.
  98     *
  99     * @author Gabriel Birke <birke@d-scribe.de>
 100     * @param string $type Modification type ('create', 'modify', 'delete')
 101     * @param array $params Parameters for the createUser, modifyUser or deleteUsers method. The content of this array depends on the modification type
 102     * @return mixed Result from the modification function or false if an event handler has canceled the action
 103     */
 104    function triggerUserMod($type, $params)
 105    {
 106      $validTypes = array(
 107        'create' => 'createUser',
 108        'modify' => 'modifyUser',
 109        'delete' => 'deleteUsers'
 110      );
 111      if(empty($validTypes[$type]))
 112        return false;
 113      $eventdata = array('type' => $type, 'params' => $params, 'modification_result' => null);
 114      $evt = new Doku_Event('AUTH_USER_CHANGE', $eventdata);
 115      if ($evt->advise_before(true)) {
 116        $result = call_user_func_array(array($this, $validTypes[$type]), $params);
 117        $evt->data['modification_result'] = $result;
 118      }
 119      $evt->advise_after();
 120      unset($evt);
 121      return $result;
 122    }
 123  
 124    /**
 125     * Log off the current user [ OPTIONAL ]
 126     *
 127     * Is run in addition to the ususal logoff method. Should
 128     * only be needed when trustExternal is implemented.
 129     *
 130     * @see     auth_logoff()
 131     * @author  Andreas Gohr
 132     */
 133    function logOff(){
 134    }
 135  
 136    /**
 137     * Do all authentication [ OPTIONAL ]
 138     *
 139     * Set $this->cando['external'] = true when implemented
 140     *
 141     * If this function is implemented it will be used to
 142     * authenticate a user - all other DokuWiki internals
 143     * will not be used for authenticating, thus
 144     * implementing the checkPass() function is not needed
 145     * anymore.
 146     *
 147     * The function can be used to authenticate against third
 148     * party cookies or Apache auth mechanisms and replaces
 149     * the auth_login() function
 150     *
 151     * The function will be called with or without a set
 152     * username. If the Username is given it was called
 153     * from the login form and the given credentials might
 154     * need to be checked. If no username was given it
 155     * the function needs to check if the user is logged in
 156     * by other means (cookie, environment).
 157     *
 158     * The function needs to set some globals needed by
 159     * DokuWiki like auth_login() does.
 160     *
 161     * @see auth_login()
 162     * @author  Andreas Gohr <andi@splitbrain.org>
 163     *
 164     * @param   string  $user    Username
 165     * @param   string  $pass    Cleartext Password
 166     * @param   bool    $sticky  Cookie should not expire
 167     * @return  bool             true on successful auth
 168     */
 169    function trustExternal($user,$pass,$sticky=false){
 170  #    // some example:
 171  #
 172  #    global $USERINFO;
 173  #    global $conf;
 174  #    $sticky ? $sticky = true : $sticky = false; //sanity check
 175  #
 176  #    // do the checking here
 177  #
 178  #    // set the globals if authed
 179  #    $USERINFO['name'] = 'FIXME';
 180  #    $USERINFO['mail'] = 'FIXME';
 181  #    $USERINFO['grps'] = array('FIXME');
 182  #    $_SERVER['REMOTE_USER'] = $user;
 183  #    $_SESSION[DOKU_COOKIE]['auth']['user'] = $user;
 184  #    $_SESSION[DOKU_COOKIE]['auth']['pass'] = $pass;
 185  #    $_SESSION[DOKU_COOKIE]['auth']['info'] = $USERINFO;
 186  #    return true;
 187    }
 188  
 189    /**
 190     * Check user+password [ MUST BE OVERRIDDEN ]
 191     *
 192     * Checks if the given user exists and the given
 193     * plaintext password is correct
 194     *
 195     * May be ommited if trustExternal is used.
 196     *
 197     * @author  Andreas Gohr <andi@splitbrain.org>
 198     * @return  bool
 199     */
 200    function checkPass($user,$pass){
 201      msg("no valid authorisation system in use", -1);
 202      return false;
 203    }
 204  
 205    /**
 206     * Return user info [ MUST BE OVERRIDDEN ]
 207     *
 208     * Returns info about the given user needs to contain
 209     * at least these fields:
 210     *
 211     * name string  full name of the user
 212     * mail string  email addres of the user
 213     * grps array   list of groups the user is in
 214     *
 215     * @author  Andreas Gohr <andi@splitbrain.org>
 216     * @return  array containing user data or false
 217     */
 218    function getUserData($user) {
 219      if(!$this->cando['external']) msg("no valid authorisation system in use", -1);
 220      return false;
 221    }
 222  
 223    /**
 224     * Create a new User [implement only where required/possible]
 225     *
 226     * Returns false if the user already exists, null when an error
 227     * occurred and true if everything went well.
 228     *
 229     * The new user HAS TO be added to the default group by this
 230     * function!
 231     *
 232     * Set addUser capability when implemented
 233     *
 234     * @author  Andreas Gohr <andi@splitbrain.org>
 235     */
 236    function createUser($user,$pass,$name,$mail,$grps=null){
 237      msg("authorisation method does not allow creation of new users", -1);
 238      return null;
 239    }
 240  
 241    /**
 242     * Modify user data [implement only where required/possible]
 243     *
 244     * Set the mod* capabilities according to the implemented features
 245     *
 246     * @author  Chris Smith <chris@jalakai.co.uk>
 247     * @param   $user      nick of the user to be changed
 248     * @param   $changes   array of field/value pairs to be changed (password will be clear text)
 249     * @return  bool
 250     */
 251    function modifyUser($user, $changes) {
 252      msg("authorisation method does not allow modifying of user data", -1);
 253      return false;
 254    }
 255  
 256    /**
 257     * Delete one or more users [implement only where required/possible]
 258     *
 259     * Set delUser capability when implemented
 260     *
 261     * @author  Chris Smith <chris@jalakai.co.uk>
 262     * @param   array  $users
 263     * @return  int    number of users deleted
 264     */
 265    function deleteUsers($users) {
 266      msg("authorisation method does not allow deleting of users", -1);
 267      return false;
 268    }
 269  
 270    /**
 271     * Return a count of the number of user which meet $filter criteria
 272     * [should be implemented whenever retrieveUsers is implemented]
 273     *
 274     * Set getUserCount capability when implemented
 275     *
 276     * @author  Chris Smith <chris@jalakai.co.uk>
 277     */
 278    function getUserCount($filter=array()) {
 279      msg("authorisation method does not provide user counts", -1);
 280      return 0;
 281    }
 282  
 283    /**
 284     * Bulk retrieval of user data [implement only where required/possible]
 285     *
 286     * Set getUsers capability when implemented
 287     *
 288     * @author  Chris Smith <chris@jalakai.co.uk>
 289     * @param   start     index of first user to be returned
 290     * @param   limit     max number of users to be returned
 291     * @param   filter    array of field/pattern pairs, null for no filter
 292     * @return  array of userinfo (refer getUserData for internal userinfo details)
 293     */
 294    function retrieveUsers($start=0,$limit=-1,$filter=null) {
 295      msg("authorisation method does not support mass retrieval of user data", -1);
 296      return array();
 297    }
 298  
 299    /**
 300     * Define a group [implement only where required/possible]
 301     *
 302     * Set addGroup capability when implemented
 303     *
 304     * @author  Chris Smith <chris@jalakai.co.uk>
 305     * @return  bool
 306     */
 307    function addGroup($group) {
 308      msg("authorisation method does not support independent group creation", -1);
 309      return false;
 310    }
 311  
 312    /**
 313     * Retrieve groups [implement only where required/possible]
 314     *
 315     * Set getGroups capability when implemented
 316     *
 317     * @author  Chris Smith <chris@jalakai.co.uk>
 318     * @return  array
 319     */
 320    function retrieveGroups($start=0,$limit=0) {
 321      msg("authorisation method does not support group list retrieval", -1);
 322      return array();
 323    }
 324  
 325  
 326    /**
 327     * Check Session Cache validity [implement only where required/possible]
 328     *
 329     * DokuWiki caches user info in the user's session for the timespan defined
 330     * in $conf['securitytimeout'].
 331     *
 332     * This makes sure slow authentication backends do not slow down DokuWiki.
 333     * This also means that changes to the user database will not be reflected
 334     * on currently logged in users.
 335     *
 336     * To accommodate for this, the user manager plugin will touch a reference
 337     * file whenever a change is submitted. This function compares the filetime
 338     * of this reference file with the time stored in the session.
 339     *
 340     * This reference file mechanism does not reflect changes done directly in
 341     * the backend's database through other means than the user manager plugin.
 342     *
 343     * Fast backends might want to return always false, to force rechecks on
 344     * each page load. Others might want to use their own checking here. If
 345     * unsure, do not override.
 346     *
 347     * @param  string $user - The username
 348     * @author Andreas Gohr <andi@splitbrain.org>
 349     * @return bool
 350     */
 351    function useSessionCache($user){
 352      global $conf;
 353      return ($_SESSION[DOKU_COOKIE]['auth']['time'] >= @filemtime($conf['cachedir'].'/sessionpurge'));
 354    }
 355  
 356  }
 357  //Setup VIM: ex: et ts=2 enc=utf-8 :