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