inc/auth/basic.class.php

   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 <andi@splitbrain.org>
 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    * Return case sensitivity of the backend [OPTIONAL]
 327    *
 328    * When your backend is caseinsensitive (eg. you can login with USER and
 329    * user) then you need to overwrite this method and return false
 330    */
 331   function isCaseSensitive(){
 332     return true;
 333   }
 334
 335   /**
 336    * Sanitize a given username [OPTIONAL]
 337    *
 338    * This function is applied to any user name that is given to
 339    * the backend and should also be applied to any user name within
 340    * the backend before returning it somewhere.
 341    *
 342    * This should be used to enforce username restrictions.
 343    *
 344    * @author Andreas Gohr <andi@splitbrain.org>
 345    * @param string $user - username
 346    * @param string - the cleaned username
 347    */
 348   function cleanUser($user){
 349     return $user;
 350   }
 351
 352   /**
 353    * Sanitize a given groupname [OPTIONAL]
 354    *
 355    * This function is applied to any groupname that is given to
 356    * the backend and should also be applied to any groupname within
 357    * the backend before returning it somewhere.
 358    *
 359    * This should be used to enforce groupname restrictions.
 360    *
 361    * Groupnames are to be passed without a leading '@' here.
 362    *
 363    * @author Andreas Gohr <andi@splitbrain.org>
 364    * @param string $group - groupname
 365    * @param string - the cleaned groupname
 366    */
 367   function cleanGroup($group){
 368     return $group;
 369   }
 370
 371
 372   /**
 373    * Check Session Cache validity [implement only where required/possible]
 374    *
 375    * DokuWiki caches user info in the user's session for the timespan defined
 376    * in $conf['auth_security_timeout'].
 377    *
 378    * This makes sure slow authentication backends do not slow down DokuWiki.
 379    * This also means that changes to the user database will not be reflected
 380    * on currently logged in users.
 381    *
 382    * To accommodate for this, the user manager plugin will touch a reference
 383    * file whenever a change is submitted. This function compares the filetime
 384    * of this reference file with the time stored in the session.
 385    *
 386    * This reference file mechanism does not reflect changes done directly in
 387    * the backend's database through other means than the user manager plugin.
 388    *
 389    * Fast backends might want to return always false, to force rechecks on
 390    * each page load. Others might want to use their own checking here. If
 391    * unsure, do not override.
 392    *
 393    * @param  string $user - The username
 394    * @author Andreas Gohr <andi@splitbrain.org>
 395    * @return bool
 396    */
 397   function useSessionCache($user){
 398     global $conf;
 399     return ($_SESSION[DOKU_COOKIE]['auth']['time'] >= @filemtime($conf['cachedir'].'/sessionpurge'));
 400   }
 401
 402 }
 403 //Setup VIM: ex: et ts=2 enc=utf-8 :