auth/cas/CAS/CAS.php

   1 <?php
   2
   3 // commented in 0.4.22-RC2 for Sylvain Derosiaux
   4 // error_reporting(E_ALL ^ E_NOTICE);
   5
   6 //
   7 // hack by Vangelis Haniotakis to handle the absence of $_SERVER['REQUEST_URI'] in IIS
   8 //
   9 if (!$_SERVER['REQUEST_URI']) {
  10      $_SERVER['REQUEST_URI'] = $_SERVER['SCRIPT_NAME'].'?'.$_SERVER['QUERY_STRING'];
  11 }
  12
  13 //
  14 // another one by Vangelis Haniotakis also to make phpCAS work with PHP5
  15 //
  16 if (version_compare(PHP_VERSION,'5','>=')) {
  17     require_once(dirname(__FILE__).'/domxml-php4-php5.php');
  18 }
  19
  20 /**
  21  * @file CAS/CAS.php
  22  * Interface class of the phpCAS library
  23  *
  24  * @ingroup public
  25  */
  26
  27 // ########################################################################
  28 //  CONSTANTS
  29 // ########################################################################
  30
  31 // ------------------------------------------------------------------------
  32 //  CAS VERSIONS
  33 // ------------------------------------------------------------------------
  34
  35 /**
  36  * phpCAS version. accessible for the user by phpCAS::getVersion().
  37  */
  38 define('PHPCAS_VERSION','0.5.1-1');
  39
  40 // ------------------------------------------------------------------------
  41 //  CAS VERSIONS
  42 // ------------------------------------------------------------------------
  43 /**
  44  * @addtogroup public
  45  * @{
  46  */
  47
  48 /**
  49  * CAS version 1.0
  50  */
  51 define("CAS_VERSION_1_0",'1.0');
  52 /*!
  53  * CAS version 2.0
  54  */
  55 define("CAS_VERSION_2_0",'2.0');
  56
  57 /** @} */
  58 /**
  59  * @addtogroup publicPGTStorage
  60  * @{
  61  */
  62 // ------------------------------------------------------------------------
  63 //  FILE PGT STORAGE
  64 // ------------------------------------------------------------------------
  65 /**
  66  * Default path used when storing PGT's to file
  67  */
  68 define("CAS_PGT_STORAGE_FILE_DEFAULT_PATH",'/tmp');
  69 /**
  70  * phpCAS::setPGTStorageFile()'s 2nd parameter to write plain text files
  71  */
  72 define("CAS_PGT_STORAGE_FILE_FORMAT_PLAIN",'plain');
  73 /**
  74  * phpCAS::setPGTStorageFile()'s 2nd parameter to write xml files
  75  */
  76 define("CAS_PGT_STORAGE_FILE_FORMAT_XML",'xml');
  77 /**
  78  * Default format used when storing PGT's to file
  79  */
  80 define("CAS_PGT_STORAGE_FILE_DEFAULT_FORMAT",CAS_PGT_STORAGE_FILE_FORMAT_PLAIN);
  81 // ------------------------------------------------------------------------
  82 //  DATABASE PGT STORAGE
  83 // ------------------------------------------------------------------------
  84 /**
  85  * default database type when storing PGT's to database
  86  */
  87 define("CAS_PGT_STORAGE_DB_DEFAULT_DATABASE_TYPE",'mysql');
  88 /**
  89  * default host when storing PGT's to database
  90  */
  91 define("CAS_PGT_STORAGE_DB_DEFAULT_HOSTNAME",'localhost');
  92 /**
  93  * default port when storing PGT's to database
  94  */
  95 define("CAS_PGT_STORAGE_DB_DEFAULT_PORT",'');
  96 /**
  97  * default database when storing PGT's to database
  98  */
  99 define("CAS_PGT_STORAGE_DB_DEFAULT_DATABASE",'phpCAS');
 100 /**
 101  * default table when storing PGT's to database
 102  */
 103 define("CAS_PGT_STORAGE_DB_DEFAULT_TABLE",'pgt');
 104
 105 /** @} */
 106 // ------------------------------------------------------------------------
 107 // SERVICE ACCESS ERRORS
 108 // ------------------------------------------------------------------------
 109 /**
 110  * @addtogroup publicServices
 111  * @{
 112  */
 113
 114 /**
 115  * phpCAS::service() error code on success
 116  */
 117 define("PHPCAS_SERVICE_OK",0);
 118 /**
 119  * phpCAS::service() error code when the PT could not retrieve because
 120  * the CAS server did not respond.
 121  */
 122 define("PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE",1);
 123 /**
 124  * phpCAS::service() error code when the PT could not retrieve because
 125  * the response of the CAS server was ill-formed.
 126  */
 127 define("PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE",2);
 128 /**
 129  * phpCAS::service() error code when the PT could not retrieve because
 130  * the CAS server did not want to.
 131  */
 132 define("PHPCAS_SERVICE_PT_FAILURE",3);
 133 /**
 134  * phpCAS::service() error code when the service was not available.
 135  */
 136 define("PHPCAS_SERVICE_NOT AVAILABLE",4);
 137
 138 /** @} */
 139 // ------------------------------------------------------------------------
 140 //  LANGUAGES
 141 // ------------------------------------------------------------------------
 142 /**
 143  * @addtogroup publicLang
 144  * @{
 145  */
 146
 147 define("PHPCAS_LANG_ENGLISH",    'english');
 148 define("PHPCAS_LANG_FRENCH",     'french');
 149 define("PHPCAS_LANG_GREEK",      'greek');
 150 define("PHPCAS_LANG_GERMAN",     'german');
 151 define("PHPCAS_LANG_JAPANESE",   'japanese');
 152
 153 /** @} */
 154
 155 /**
 156  * @addtogroup internalLang
 157  * @{
 158  */
 159
 160 /**
 161  * phpCAS default language (when phpCAS::setLang() is not used)
 162  */
 163 define("PHPCAS_LANG_DEFAULT", PHPCAS_LANG_ENGLISH);
 164
 165 /** @} */
 166 // ------------------------------------------------------------------------
 167 //  MISC
 168 // ------------------------------------------------------------------------
 169 /**
 170  * @addtogroup internalMisc
 171  * @{
 172  */
 173
 174 /**
 175  * This global variable is used by the interface class phpCAS.
 176  *
 177  * @hideinitializer
 178  */
 179 $PHPCAS_CLIENT  = null;
 180
 181 /**
 182  * This global variable is used to store where the initializer is called from
 183  * (to print a comprehensive error in case of multiple calls).
 184  *
 185  * @hideinitializer
 186  */
 187 $PHPCAS_INIT_CALL = array('done' => FALSE,
 188                           'file' => '?',
 189                           'line' => -1,
 190                           'method' => '?');
 191
 192 /**
 193  * This global variable is used to store where the method checking
 194  * the authentication is called from (to print comprehensive errors)
 195  *
 196  * @hideinitializer
 197  */
 198 $PHPCAS_AUTH_CHECK_CALL = array('done' => FALSE,
 199                                 'file' => '?',
 200                                 'line' => -1,
 201                                 'method' => '?',
 202                                 'result' => FALSE);
 203
 204 /**
 205  * This global variable is used to store phpCAS debug mode.
 206  *
 207  * @hideinitializer
 208  */
 209 $PHPCAS_DEBUG  = array('filename' => FALSE,
 210                        'indent' => 0,
 211                        'unique_id' => '');
 212
 213 /** @} */
 214
 215 // ########################################################################
 216 //  CLIENT CLASS
 217 // ########################################################################
 218
 219 // include client class
 220 include_once(dirname(__FILE__).'/client.php');
 221
 222 // ########################################################################
 223 //  INTERFACE CLASS
 224 // ########################################################################
 225
 226 /**
 227  * @class phpCAS
 228  * The phpCAS class is a simple container for the phpCAS library. It provides CAS
 229  * authentication for web applications written in PHP.
 230  *
 231  * @ingroup public
 232  * @author Pascal Aubry <pascal.aubry at univ-rennes1.fr>
 233  *
 234  * \internal All its methods access the same object ($PHPCAS_CLIENT, declared
 235  * at the end of CAS/client.php).
 236  */
 237
 238
 239
 240 class phpCAS
 241 {
 242
 243   // ########################################################################
 244   //  INITIALIZATION
 245   // ########################################################################
 246
 247   /**
 248    * @addtogroup publicInit
 249    * @{
 250    */
 251
 252   /**
 253    * phpCAS client initializer.
 254    * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
 255    * called, only once, and before all other methods (except phpCAS::getVersion()
 256    * and phpCAS::setDebug()).
 257    *
 258    * @param $server_version the version of the CAS server
 259    * @param $server_hostname the hostname of the CAS server
 260    * @param $server_port the port the CAS server is running on
 261    * @param $server_uri the URI the CAS server is responding on
 262    * @param $start_session Have phpCAS start PHP sessions (default true)
 263    *
 264    * @return a newly created CASClient object
 265    */
 266   function client($server_version,
 267                   $server_hostname,
 268                   $server_port,
 269                   $server_uri,
 270                   $start_session = true)
 271     {
 272       global $PHPCAS_CLIENT, $PHPCAS_INIT_CALL;
 273
 274       phpCAS::traceBegin();
 275       if ( is_object($PHPCAS_CLIENT) ) {
 276         phpCAS::error($PHPCAS_INIT_CALL['method'].'() has already been called (at '.$PHPCAS_INIT_CALL['file'].':'.$PHPCAS_INIT_CALL['line'].')');
 277       }
 278       if ( gettype($server_version) != 'string' ) {
 279         phpCAS::error('type mismatched for parameter $server_version (should be `string\')');
 280       }
 281       if ( gettype($server_hostname) != 'string' ) {
 282         phpCAS::error('type mismatched for parameter $server_hostname (should be `string\')');
 283       }
 284       if ( gettype($server_port) != 'integer' ) {
 285         phpCAS::error('type mismatched for parameter $server_port (should be `integer\')');
 286       }
 287       if ( gettype($server_uri) != 'string' ) {
 288         phpCAS::error('type mismatched for parameter $server_uri (should be `string\')');
 289       }
 290
 291       // store where the initialzer is called from
 292       $dbg = phpCAS::backtrace();
 293       $PHPCAS_INIT_CALL = array('done' => TRUE,
 294                                 'file' => $dbg[0]['file'],
 295                                 'line' => $dbg[0]['line'],
 296                                 'method' => __CLASS__.'::'.__FUNCTION__);
 297
 298       // initialize the global object $PHPCAS_CLIENT
 299       $PHPCAS_CLIENT = new CASClient($server_version,FALSE/*proxy*/,$server_hostname,$server_port,$server_uri,$start_session);
 300       phpCAS::traceEnd();
 301     }
 302
 303   /**
 304    * phpCAS proxy initializer.
 305    * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
 306    * called, only once, and before all other methods (except phpCAS::getVersion()
 307    * and phpCAS::setDebug()).
 308    *
 309    * @param $server_version the version of the CAS server
 310    * @param $server_hostname the hostname of the CAS server
 311    * @param $server_port the port the CAS server is running on
 312    * @param $server_uri the URI the CAS server is responding on
 313    * @param $start_session Have phpCAS start PHP sessions (default true)
 314    *
 315    * @return a newly created CASClient object
 316    */
 317   function proxy($server_version,
 318                  $server_hostname,
 319                  $server_port,
 320                  $server_uri,
 321                  $start_session = true)
 322     {
 323       global $PHPCAS_CLIENT, $PHPCAS_INIT_CALL;
 324
 325       phpCAS::traceBegin();
 326       if ( is_object($PHPCAS_CLIENT) ) {
 327         phpCAS::error($PHPCAS_INIT_CALL['method'].'() has already been called (at '.$PHPCAS_INIT_CALL['file'].':'.$PHPCAS_INIT_CALL['line'].')');
 328       }
 329       if ( gettype($server_version) != 'string' ) {
 330         phpCAS::error('type mismatched for parameter $server_version (should be `string\')');
 331       }
 332       if ( gettype($server_hostname) != 'string' ) {
 333         phpCAS::error('type mismatched for parameter $server_hostname (should be `string\')');
 334       }
 335       if ( gettype($server_port) != 'integer' ) {
 336         phpCAS::error('type mismatched for parameter $server_port (should be `integer\')');
 337       }
 338       if ( gettype($server_uri) != 'string' ) {
 339         phpCAS::error('type mismatched for parameter $server_uri (should be `string\')');
 340       }
 341
 342       // store where the initialzer is called from
 343       $dbg = phpCAS::backtrace();
 344       $PHPCAS_INIT_CALL = array('done' => TRUE,
 345                                 'file' => $dbg[0]['file'],
 346                                 'line' => $dbg[0]['line'],
 347                                 'method' => __CLASS__.'::'.__FUNCTION__);
 348
 349       // initialize the global object $PHPCAS_CLIENT
 350       $PHPCAS_CLIENT = new CASClient($server_version,TRUE/*proxy*/,$server_hostname,$server_port,$server_uri,$start_session);
 351       phpCAS::traceEnd();
 352     }
 353
 354   /** @} */
 355   // ########################################################################
 356   //  DEBUGGING
 357   // ########################################################################
 358
 359   /**
 360    * @addtogroup publicDebug
 361    * @{
 362    */
 363
 364   /**
 365    * Set/unset debug mode
 366    *
 367    * @param $filename the name of the file used for logging, or FALSE to stop debugging.
 368    */
 369   function setDebug($filename='')
 370     {
 371       global $PHPCAS_DEBUG;
 372
 373       if ( $filename != FALSE && gettype($filename) != 'string' ) {
 374         phpCAS::error('type mismatched for parameter $dbg (should be FALSE or the name of the log file)');
 375       }
 376
 377       if ( empty($filename) ) {
 378         if ( preg_match('/^Win.*/',getenv('OS')) ) {
 379           if ( isset($_ENV['TMP']) ) {
 380             $debugDir = $_ENV['TMP'].'/';
 381           } else if ( isset($_ENV['TEMP']) ) {
 382             $debugDir = $_ENV['TEMP'].'/';
 383           } else {
 384             $debugDir = '';
 385           }
 386         } else {
 387           $debugDir = '/tmp/';
 388         }
 389         $filename = $debugDir . 'phpCAS.log';
 390       }
 391
 392       if ( empty($PHPCAS_DEBUG['unique_id']) ) {
 393         $PHPCAS_DEBUG['unique_id'] = substr(strtoupper(md5(uniqid(''))),0,4);
 394       }
 395
 396       $PHPCAS_DEBUG['filename'] = $filename;
 397
 398       phpCAS::trace('START ******************');
 399     }
 400
 401   /** @} */
 402   /**
 403    * @addtogroup internalDebug
 404    * @{
 405    */
 406
 407   /**
 408    * This method is a wrapper for debug_backtrace() that is not available
 409    * in all PHP versions (>= 4.3.0 only)
 410    */
 411   function backtrace()
 412     {
 413       if ( function_exists('debug_backtrace') ) {
 414         return debug_backtrace();
 415       } else {
 416         // poor man's hack ... but it does work ...
 417         return array();
 418       }
 419     }
 420
 421   /**
 422    * Logs a string in debug mode.
 423    *
 424    * @param $str the string to write
 425    *
 426    * @private
 427    */
 428   function log($str)
 429     {
 430       $indent_str = ".";
 431       global $PHPCAS_DEBUG;
 432
 433       if ( $PHPCAS_DEBUG['filename'] ) {
 434         for ($i=0;$i<$PHPCAS_DEBUG['indent'];$i++) {
 435           $indent_str .= '|    ';
 436         }
 437         error_log($PHPCAS_DEBUG['unique_id'].' '.$indent_str.$str."\n",3,$PHPCAS_DEBUG['filename']);
 438       }
 439
 440     }
 441
 442   /**
 443    * This method is used by interface methods to print an error and where the function
 444    * was originally called from.
 445    *
 446    * @param $msg the message to print
 447    *
 448    * @private
 449    */
 450   function error($msg)
 451     {
 452       $dbg = phpCAS::backtrace();
 453       $function = '?';
 454       $file = '?';
 455       $line = '?';
 456       if ( is_array($dbg) ) {
 457         for ( $i=1; $i<sizeof($dbg); $i++) {
 458           if ( is_array($dbg[$i]) ) {
 459             if ( $dbg[$i]['class'] == __CLASS__ ) {
 460               $function = $dbg[$i]['function'];
 461               $file = $dbg[$i]['file'];
 462               $line = $dbg[$i]['line'];
 463             }
 464           }
 465         }
 466       }
 467       echo "<br />\n<b>phpCAS error</b>: <font color=\"FF0000\"><b>".__CLASS__."::".$function.'(): '.htmlentities($msg)."</b></font> in <b>".$file."</b> on line <b>".$line."</b><br />\n";
 468       phpCAS::trace($msg);
 469       phpCAS::traceExit();
 470       exit();
 471     }
 472
 473   /**
 474    * This method is used to log something in debug mode.
 475    */
 476   function trace($str)
 477     {
 478       $dbg = phpCAS::backtrace();
 479       phpCAS::log($str.' ['.basename($dbg[1]['file']).':'.$dbg[1]['line'].']');
 480     }
 481
 482   /**
 483    * This method is used to indicate the start of the execution of a function in debug mode.
 484    */
 485   function traceBegin()
 486     {
 487       global $PHPCAS_DEBUG;
 488
 489       $dbg = phpCAS::backtrace();
 490       $str = '=> ';
 491       if ( !empty($dbg[2]['class']) ) {
 492         $str .= $dbg[2]['class'].'::';
 493       }
 494       $str .= $dbg[2]['function'].'(';
 495       if ( is_array($dbg[2]['args']) ) {
 496         foreach ($dbg[2]['args'] as $index => $arg) {
 497           if ( $index != 0 ) {
 498             $str .= ', ';
 499           }
 500           $str .= str_replace("\n","",var_export($arg,TRUE));
 501         }
 502       }
 503       $str .= ') ['.basename($dbg[2]['file']).':'.$dbg[2]['line'].']';
 504       phpCAS::log($str);
 505       $PHPCAS_DEBUG['indent'] ++;
 506     }
 507
 508   /**
 509    * This method is used to indicate the end of the execution of a function in debug mode.
 510    *
 511    * @param $res the result of the function
 512    */
 513   function traceEnd($res='')
 514     {
 515       global $PHPCAS_DEBUG;
 516
 517       $PHPCAS_DEBUG['indent'] --;
 518       $dbg = phpCAS::backtrace();
 519       $str = '';
 520       $str .= '<= '.str_replace("\n","",var_export($res,TRUE));
 521       phpCAS::log($str);
 522     }
 523
 524   /**
 525    * This method is used to indicate the end of the execution of the program
 526    */
 527   function traceExit()
 528     {
 529       global $PHPCAS_DEBUG;
 530
 531       phpCAS::log('exit()');
 532       while ( $PHPCAS_DEBUG['indent'] > 0 ) {
 533         phpCAS::log('-');
 534         $PHPCAS_DEBUG['indent'] --;
 535       }
 536     }
 537
 538   /** @} */
 539   // ########################################################################
 540   //  INTERNATIONALIZATION
 541   // ########################################################################
 542   /**
 543    * @addtogroup publicLang
 544    * @{
 545    */
 546
 547   /**
 548    * This method is used to set the language used by phpCAS.
 549    * @note Can be called only once.
 550    *
 551    * @param $lang a string representing the language.
 552    *
 553    * @sa PHPCAS_LANG_FRENCH, PHPCAS_LANG_ENGLISH
 554    */
 555   function setLang($lang)
 556     {
 557       global $PHPCAS_CLIENT;
 558       if ( !is_object($PHPCAS_CLIENT) ) {
 559         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 560       }
 561       if ( gettype($lang) != 'string' ) {
 562         phpCAS::error('type mismatched for parameter $lang (should be `string\')');
 563       }
 564       $PHPCAS_CLIENT->setLang($lang);
 565     }
 566
 567   /** @} */
 568   // ########################################################################
 569   //  VERSION
 570   // ########################################################################
 571   /**
 572    * @addtogroup public
 573    * @{
 574    */
 575
 576   /**
 577    * This method returns the phpCAS version.
 578    *
 579    * @return the phpCAS version.
 580    */
 581   function getVersion()
 582     {
 583       return PHPCAS_VERSION;
 584     }
 585
 586   /** @} */
 587   // ########################################################################
 588   //  HTML OUTPUT
 589   // ########################################################################
 590   /**
 591    * @addtogroup publicOutput
 592    * @{
 593    */
 594
 595   /**
 596    * This method sets the HTML header used for all outputs.
 597    *
 598    * @param $header the HTML header.
 599    */
 600   function setHTMLHeader($header)
 601     {
 602       global $PHPCAS_CLIENT;
 603       if ( !is_object($PHPCAS_CLIENT) ) {
 604         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 605       }
 606       if ( gettype($header) != 'string' ) {
 607         phpCAS::error('type mismatched for parameter $header (should be `string\')');
 608       }
 609       $PHPCAS_CLIENT->setHTMLHeader($header);
 610     }
 611
 612   /**
 613    * This method sets the HTML footer used for all outputs.
 614    *
 615    * @param $footer the HTML footer.
 616    */
 617   function setHTMLFooter($footer)
 618     {
 619       global $PHPCAS_CLIENT;
 620       if ( !is_object($PHPCAS_CLIENT) ) {
 621         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 622       }
 623       if ( gettype($footer) != 'string' ) {
 624         phpCAS::error('type mismatched for parameter $footer (should be `string\')');
 625       }
 626       $PHPCAS_CLIENT->setHTMLFooter($footer);
 627     }
 628
 629   /** @} */
 630   // ########################################################################
 631   //  PGT STORAGE
 632   // ########################################################################
 633   /**
 634    * @addtogroup publicPGTStorage
 635    * @{
 636    */
 637
 638   /**
 639    * This method is used to tell phpCAS to store the response of the
 640    * CAS server to PGT requests onto the filesystem.
 641    *
 642    * @param $format the format used to store the PGT's (`plain' and `xml' allowed)
 643    * @param $path the path where the PGT's should be stored
 644    */
 645   function setPGTStorageFile($format='',
 646                              $path='')
 647     {
 648       global $PHPCAS_CLIENT,$PHPCAS_AUTH_CHECK_CALL;
 649
 650       phpCAS::traceBegin();
 651       if ( !is_object($PHPCAS_CLIENT) ) {
 652         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 653       }
 654       if ( !$PHPCAS_CLIENT->isProxy() ) {
 655         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 656       }
 657       if ( $PHPCAS_AUTH_CHECK_CALL['done'] ) {
 658         phpCAS::error('this method should only be called before '.$PHPCAS_AUTH_CHECK_CALL['method'].'() (called at '.$PHPCAS_AUTH_CHECK_CALL['file'].':'.$PHPCAS_AUTH_CHECK_CALL['line'].')');
 659       }
 660       if ( gettype($format) != 'string' ) {
 661         phpCAS::error('type mismatched for parameter $format (should be `string\')');
 662       }
 663       if ( gettype($path) != 'string' ) {
 664         phpCAS::error('type mismatched for parameter $format (should be `string\')');
 665       }
 666       $PHPCAS_CLIENT->setPGTStorageFile($format,$path);
 667       phpCAS::traceEnd();
 668     }
 669
 670   /**
 671    * This method is used to tell phpCAS to store the response of the
 672    * CAS server to PGT requests into a database.
 673    * @note The connection to the database is done only when needed.
 674    * As a consequence, bad parameters are detected only when
 675    * initializing PGT storage, except in debug mode.
 676    *
 677    * @param $user the user to access the data with
 678    * @param $password the user's password
 679    * @param $database_type the type of the database hosting the data
 680    * @param $hostname the server hosting the database
 681    * @param $port the port the server is listening on
 682    * @param $database the name of the database
 683    * @param $table the name of the table storing the data
 684    */
 685   function setPGTStorageDB($user,
 686                            $password,
 687                            $database_type='',
 688                            $hostname='',
 689                            $port=0,
 690                            $database='',
 691                            $table='')
 692     {
 693       global $PHPCAS_CLIENT,$PHPCAS_AUTH_CHECK_CALL;
 694
 695       phpCAS::traceBegin();
 696       if ( !is_object($PHPCAS_CLIENT) ) {
 697         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 698       }
 699       if ( !$PHPCAS_CLIENT->isProxy() ) {
 700         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 701       }
 702       if ( $PHPCAS_AUTH_CHECK_CALL['done'] ) {
 703         phpCAS::error('this method should only be called before '.$PHPCAS_AUTH_CHECK_CALL['method'].'() (called at '.$PHPCAS_AUTH_CHECK_CALL['file'].':'.$PHPCAS_AUTH_CHECK_CALL['line'].')');
 704       }
 705       if ( gettype($user) != 'string' ) {
 706         phpCAS::error('type mismatched for parameter $user (should be `string\')');
 707       }
 708       if ( gettype($password) != 'string' ) {
 709         phpCAS::error('type mismatched for parameter $password (should be `string\')');
 710       }
 711       if ( gettype($database_type) != 'string' ) {
 712         phpCAS::error('type mismatched for parameter $database_type (should be `string\')');
 713       }
 714       if ( gettype($hostname) != 'string' ) {
 715         phpCAS::error('type mismatched for parameter $hostname (should be `string\')');
 716       }
 717       if ( gettype($port) != 'integer' ) {
 718         phpCAS::error('type mismatched for parameter $port (should be `integer\')');
 719       }
 720       if ( gettype($database) != 'string' ) {
 721         phpCAS::error('type mismatched for parameter $database (should be `string\')');
 722       }
 723       if ( gettype($table) != 'string' ) {
 724         phpCAS::error('type mismatched for parameter $table (should be `string\')');
 725       }
 726       $PHPCAS_CLIENT->setPGTStorageDB($this,$user,$password,$hostname,$port,$database,$table);
 727       phpCAS::traceEnd();
 728     }
 729
 730   /** @} */
 731   // ########################################################################
 732   // ACCESS TO EXTERNAL SERVICES
 733   // ########################################################################
 734   /**
 735    * @addtogroup publicServices
 736    * @{
 737    */
 738
 739   /**
 740    * This method is used to access an HTTP[S] service.
 741    *
 742    * @param $url the service to access.
 743    * @param $err_code an error code Possible values are PHPCAS_SERVICE_OK (on
 744    * success), PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE, PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE,
 745    * PHPCAS_SERVICE_PT_FAILURE, PHPCAS_SERVICE_NOT AVAILABLE.
 746    * @param $output the output of the service (also used to give an error
 747    * message on failure).
 748    *
 749    * @return TRUE on success, FALSE otherwise (in this later case, $err_code
 750    * gives the reason why it failed and $output contains an error message).
 751    */
 752   function serviceWeb($url,&$err_code,&$output)
 753     {
 754       global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 755
 756       phpCAS::traceBegin();
 757       if ( !is_object($PHPCAS_CLIENT) ) {
 758         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 759       }
 760       if ( !$PHPCAS_CLIENT->isProxy() ) {
 761         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 762       }
 763       if ( !$PHPCAS_AUTH_CHECK_CALL['done'] ) {
 764         phpCAS::error('this method should only be called after the programmer is sure the user has been authenticated (by calling '.__CLASS__.'::checkAuthentication() or '.__CLASS__.'::forceAuthentication()');
 765       }
 766       if ( !$PHPCAS_AUTH_CHECK_CALL['result'] ) {
 767         phpCAS::error('authentication was checked (by '.$PHPCAS_AUTH_CHECK_CALL['method'].'() at '.$PHPCAS_AUTH_CHECK_CALL['file'].':'.$PHPCAS_AUTH_CHECK_CALL['line'].') but the method returned FALSE');
 768       }
 769       if ( gettype($url) != 'string' ) {
 770         phpCAS::error('type mismatched for parameter $url (should be `string\')');
 771       }
 772
 773       $res = $PHPCAS_CLIENT->serviceWeb($url,$err_code,$output);
 774
 775       phpCAS::traceEnd($res);
 776       return $res;
 777     }
 778
 779   /**
 780    * This method is used to access an IMAP/POP3/NNTP service.
 781    *
 782    * @param $url a string giving the URL of the service, including the mailing box
 783    * for IMAP URLs, as accepted by imap_open().
 784    * @param $flags options given to imap_open().
 785    * @param $err_code an error code Possible values are PHPCAS_SERVICE_OK (on
 786    * success), PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE, PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE,
 787    * PHPCAS_SERVICE_PT_FAILURE, PHPCAS_SERVICE_NOT AVAILABLE.
 788    * @param $err_msg an error message on failure
 789    * @param $pt the Proxy Ticket (PT) retrieved from the CAS server to access the URL
 790    * on success, FALSE on error).
 791    *
 792    * @return an IMAP stream on success, FALSE otherwise (in this later case, $err_code
 793    * gives the reason why it failed and $err_msg contains an error message).
 794    */
 795   function serviceMail($url,$flags,&$err_code,&$err_msg,&$pt)
 796     {
 797       global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 798
 799       phpCAS::traceBegin();
 800       if ( !is_object($PHPCAS_CLIENT) ) {
 801         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 802       }
 803       if ( !$PHPCAS_CLIENT->isProxy() ) {
 804         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
 805       }
 806       if ( !$PHPCAS_AUTH_CHECK_CALL['done'] ) {
 807         phpCAS::error('this method should only be called after the programmer is sure the user has been authenticated (by calling '.__CLASS__.'::checkAuthentication() or '.__CLASS__.'::forceAuthentication()');
 808       }
 809       if ( !$PHPCAS_AUTH_CHECK_CALL['result'] ) {
 810         phpCAS::error('authentication was checked (by '.$PHPCAS_AUTH_CHECK_CALL['method'].'() at '.$PHPCAS_AUTH_CHECK_CALL['file'].':'.$PHPCAS_AUTH_CHECK_CALL['line'].') but the method returned FALSE');
 811       }
 812       if ( gettype($url) != 'string' ) {
 813         phpCAS::error('type mismatched for parameter $url (should be `string\')');
 814       }
 815
 816       if ( gettype($flags) != 'integer' ) {
 817         phpCAS::error('type mismatched for parameter $flags (should be `integer\')');
 818       }
 819
 820       $res = $PHPCAS_CLIENT->serviceMail($url,$flags,$err_code,$err_msg,$pt);
 821
 822       phpCAS::traceEnd($res);
 823       return $res;
 824     }
 825
 826   /** @} */
 827   // ########################################################################
 828   //  AUTHENTICATION
 829   // ########################################################################
 830   /**
 831    * @addtogroup publicAuth
 832    * @{
 833    */
 834
 835   /**
 836    * Set the times authentication will be cached before really accessing the CAS server in gateway mode:
 837    * - -1: check only once, and then never again (until you pree login)
 838    * - 0: always check
 839    * - n: check every "n" time
 840    *
 841    * @param $n an integer.
 842    */
 843   function setCacheTimesForAuthRecheck($n)
 844     {
 845       global $PHPCAS_CLIENT;
 846       if ( !is_object($PHPCAS_CLIENT) ) {
 847         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 848       }
 849       if ( gettype($header) != 'integer' ) {
 850         phpCAS::error('type mismatched for parameter $header (should be `string\')');
 851       }
 852       $PHPCAS_CLIENT->setCacheTimesForAuthRecheck($n);
 853     }
 854
 855   /**
 856    * This method is called to check if the user is authenticated (use the gateway feature).
 857    * @return TRUE when the user is authenticated; otherwise FALSE.
 858    */
 859   function checkAuthentication()
 860     {
 861       global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 862
 863       phpCAS::traceBegin();
 864       if ( !is_object($PHPCAS_CLIENT) ) {
 865         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 866       }
 867
 868       $auth = $PHPCAS_CLIENT->checkAuthentication();
 869
 870       // store where the authentication has been checked and the result
 871       $dbg = phpCAS::backtrace();
 872       $PHPCAS_AUTH_CHECK_CALL = array('done' => TRUE,
 873                                       'file' => $dbg[0]['file'],
 874                                       'line' => $dbg[0]['line'],
 875                                       'method' => __CLASS__.'::'.__FUNCTION__,
 876                                       'result' => $auth );
 877       phpCAS::traceEnd($auth);
 878       return $auth;
 879     }
 880
 881   /**
 882    * This method is called to force authentication if the user was not already
 883    * authenticated. If the user is not authenticated, halt by redirecting to
 884    * the CAS server.
 885    */
 886   function forceAuthentication()
 887     {
 888       global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 889
 890       phpCAS::traceBegin();
 891       if ( !is_object($PHPCAS_CLIENT) ) {
 892         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 893       }
 894
 895       $auth = $PHPCAS_CLIENT->forceAuthentication();
 896
 897       // store where the authentication has been checked and the result
 898       $dbg = phpCAS::backtrace();
 899       $PHPCAS_AUTH_CHECK_CALL = array('done' => TRUE,
 900                                       'file' => $dbg[0]['file'],
 901                                       'line' => $dbg[0]['line'],
 902                                       'method' => __CLASS__.'::'.__FUNCTION__,
 903                                       'result' => $auth );
 904
 905       if ( !$auth ) {
 906         phpCAS::trace('user is not authenticated, redirecting to the CAS server');
 907         $PHPCAS_CLIENT->forceAuthentication();
 908       } else {
 909         phpCAS::trace('no need to authenticate (user `'.phpCAS::getUser().'\' is already authenticated)');
 910       }
 911
 912       phpCAS::traceEnd();
 913       return $auth;
 914     }
 915
 916   /**
 917    * This method has been left from version 0.4.1 for compatibility reasons.
 918    */
 919   function authenticate()
 920     {
 921       phpCAS::error('this method is deprecated. You should use '.__CLASS__.'::forceAuthentication() instead');
 922     }
 923
 924   /**
 925    * This method is called to check if the user is authenticated (previously or by
 926    * tickets given in the URL).
 927    *
 928    * @return TRUE when the user is authenticated.
 929    */
 930   function isAuthenticated()
 931     {
 932       global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 933
 934       phpCAS::traceBegin();
 935       if ( !is_object($PHPCAS_CLIENT) ) {
 936         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 937       }
 938
 939       // call the isAuthenticated method of the global $PHPCAS_CLIENT object
 940       $auth = $PHPCAS_CLIENT->isAuthenticated();
 941
 942       // store where the authentication has been checked and the result
 943       $dbg = phpCAS::backtrace();
 944       $PHPCAS_AUTH_CHECK_CALL = array('done' => TRUE,
 945                                      'file' => $dbg[0]['file'],
 946                                      'line' => $dbg[0]['line'],
 947                                      'method' => __CLASS__.'::'.__FUNCTION__,
 948                                      'result' => $auth );
 949       phpCAS::traceEnd($auth);
 950       return $auth;
 951     }
 952
 953   /**
 954    * Checks whether authenticated based on $_SESSION. Useful to avoid
 955    * server calls.
 956    * @return true if authenticated, false otherwise.
 957    * @since 0.4.22 by Brendan Arnold
 958    */
 959   function isSessionAuthenticated ()
 960         {
 961       global $PHPCAS_CLIENT;
 962       if ( !is_object($PHPCAS_CLIENT) ) {
 963         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 964       }
 965       return($PHPCAS_CLIENT->isSessionAuthenticated());
 966     }
 967
 968   /**
 969    * This method returns the CAS user's login name.
 970    * @warning should not be called only after phpCAS::forceAuthentication()
 971    * or phpCAS::checkAuthentication().
 972    *
 973    * @return the login name of the authenticated user
 974    */
 975   function getUser()
 976     {
 977       global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 978       if ( !is_object($PHPCAS_CLIENT) ) {
 979         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
 980       }
 981       if ( !$PHPCAS_AUTH_CHECK_CALL['done'] ) {
 982         phpCAS::error('this method should only be called after '.__CLASS__.'::forceAuthentication() or '.__CLASS__.'::isAuthenticated()');
 983       }
 984       if ( !$PHPCAS_AUTH_CHECK_CALL['result'] ) {
 985         phpCAS::error('authentication was checked (by '.$PHPCAS_AUTH_CHECK_CALL['method'].'() at '.$PHPCAS_AUTH_CHECK_CALL['file'].':'.$PHPCAS_AUTH_CHECK_CALL['line'].') but the method returned FALSE');
 986       }
 987       return $PHPCAS_CLIENT->getUser();
 988     }
 989
 990   /**
 991    * This method returns the URL to be used to login.
 992    * or phpCAS::isAuthenticated().
 993    *
 994    * @return the login name of the authenticated user
 995    */
 996   function getServerLoginURL()
 997     {
 998       global $PHPCAS_CLIENT;
 999       if ( !is_object($PHPCAS_CLIENT) ) {
1000         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
1001       }
1002       return $PHPCAS_CLIENT->getServerLoginURL();
1003     }
1004
1005   /**
1006    * Set the login URL of the CAS server.
1007    * @param $url the login URL
1008    * @since 0.4.21 by Wyman Chan
1009    */
1010   function setServerLoginURL($url='')
1011    {
1012      global $PHPCAS_CLIENT;
1013      phpCAS::traceBegin();
1014      if ( !is_object($PHPCAS_CLIENT) ) {
1015         phpCAS::error('this method should only be called after
1016 '.__CLASS__.'::client()');
1017      }
1018      if ( gettype($url) != 'string' ) {
1019         phpCAS::error('type mismatched for parameter $url (should be
1020 `string\')');
1021      }
1022      $PHPCAS_CLIENT->setServerLoginURL($url);
1023      phpCAS::traceEnd();
1024    }
1025
1026   /**
1027    * This method returns the URL to be used to login.
1028    * or phpCAS::isAuthenticated().
1029    *
1030    * @return the login name of the authenticated user
1031    */
1032   function getServerLogoutURL()
1033     {
1034       global $PHPCAS_CLIENT;
1035       if ( !is_object($PHPCAS_CLIENT) ) {
1036         phpCAS::error('this method should not be called before '.__CLASS__.'::client() or '.__CLASS__.'::proxy()');
1037       }
1038       return $PHPCAS_CLIENT->getServerLogoutURL();
1039     }
1040
1041   /**
1042    * Set the logout URL of the CAS server.
1043    * @param $url the logout URL
1044    * @since 0.4.21 by Wyman Chan
1045    */
1046   function setServerLogoutURL($url='')
1047    {
1048      global $PHPCAS_CLIENT;
1049      phpCAS::traceBegin();
1050      if ( !is_object($PHPCAS_CLIENT) ) {
1051         phpCAS::error('this method should only be called after
1052 '.__CLASS__.'::client()');
1053      }
1054      if ( gettype($url) != 'string' ) {
1055         phpCAS::error('type mismatched for parameter $url (should be
1056 `string\')');
1057      }
1058      $PHPCAS_CLIENT->setServerLogoutURL($url);
1059      phpCAS::traceEnd();
1060    }
1061
1062   /**
1063    * This method is used to logout from CAS. Halts by redirecting to the CAS server.
1064    * @param $url a URL that will be transmitted to the CAS server (to come back to when logged out)
1065    */
1066   function logout($url = "")
1067     {
1068       global $PHPCAS_CLIENT;
1069
1070       phpCAS::traceBegin();
1071       if ( !is_object($PHPCAS_CLIENT) ) {
1072         phpCAS::error('this method should only be called after '.__CLASS__.'::client() or'.__CLASS__.'::proxy()');
1073       }
1074       $PHPCAS_CLIENT->logout($url);
1075       // never reached
1076       phpCAS::traceEnd();
1077     }
1078
1079   /**
1080    * Set the fixed URL that will be used by the CAS server to transmit the PGT.
1081    * When this method is not called, a phpCAS script uses its own URL for the callback.
1082    *
1083    * @param $url the URL
1084    */
1085   function setFixedCallbackURL($url='')
1086    {
1087      global $PHPCAS_CLIENT;
1088      phpCAS::traceBegin();
1089      if ( !is_object($PHPCAS_CLIENT) ) {
1090         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
1091      }
1092      if ( !$PHPCAS_CLIENT->isProxy() ) {
1093         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
1094      }
1095      if ( gettype($url) != 'string' ) {
1096         phpCAS::error('type mismatched for parameter $url (should be `string\')');
1097      }
1098      $PHPCAS_CLIENT->setCallbackURL($url);
1099      phpCAS::traceEnd();
1100    }
1101
1102   /**
1103    * Set the fixed URL that will be set as the CAS service parameter. When this
1104    * method is not called, a phpCAS script uses its own URL.
1105    *
1106    * @param $url the URL
1107    */
1108    function setFixedServiceURL($url)
1109    {
1110      global $PHPCAS_CLIENT;
1111      phpCAS::traceBegin();
1112      if ( !is_object($PHPCAS_CLIENT) ) {
1113          phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
1114      }
1115      if ( gettype($url) != 'string' ) {
1116         phpCAS::error('type mismatched for parameter $url (should be `string\')');
1117      }
1118      $PHPCAS_CLIENT->setURL($url);
1119      phpCAS::traceEnd();
1120    }
1121
1122   /**
1123    * Get the URL that is set as the CAS service parameter.
1124    */
1125    function getServiceURL()
1126    {
1127      global $PHPCAS_CLIENT;
1128      if ( !is_object($PHPCAS_CLIENT) ) {
1129         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
1130      }
1131      return($PHPCAS_CLIENT->getURL());
1132    }
1133
1134   /**
1135    * Retrieve a Proxy Ticket from the CAS server.
1136    */
1137    function retrievePT($target_service,&$err_code,&$err_msg)
1138    {
1139      global $PHPCAS_CLIENT;
1140      if ( !is_object($PHPCAS_CLIENT) ) {
1141         phpCAS::error('this method should only be called after '.__CLASS__.'::proxy()');
1142      }
1143      if ( gettype($target_service) != 'string' ) {
1144         phpCAS::error('type mismatched for parameter $target_service(should be `string\')');
1145      }
1146      return($PHPCAS_CLIENT->retrievePT($target_service,$err_code,$err_msg));
1147    }
1148   /** @} */
1149
1150 }
1151
1152 // ########################################################################
1153 // DOCUMENTATION
1154 // ########################################################################
1155
1156 // ########################################################################
1157 //  MAIN PAGE
1158
1159 /**
1160  * @mainpage
1161  *
1162  * The following pages only show the source documentation.
1163  *
1164  * For more information on phpCAS, please refer to http://esup-phpcas.sourceforge.net
1165  *
1166  */
1167
1168 // ########################################################################
1169 //  MODULES DEFINITION
1170
1171 /** @defgroup public User interface */
1172
1173 /** @defgroup publicInit Initialization
1174  *  @ingroup public */
1175
1176 /** @defgroup publicAuth Authentication
1177  *  @ingroup public */
1178
1179 /** @defgroup publicServices Access to external services
1180  *  @ingroup public */
1181
1182 /** @defgroup publicConfig Configuration
1183  *  @ingroup public */
1184
1185 /** @defgroup publicLang Internationalization
1186  *  @ingroup publicConfig */
1187
1188 /** @defgroup publicOutput HTML output
1189  *  @ingroup publicConfig */
1190
1191 /** @defgroup publicPGTStorage PGT storage
1192  *  @ingroup publicConfig */
1193
1194 /** @defgroup publicDebug Debugging
1195  *  @ingroup public */
1196
1197
1198 /** @defgroup internal Implementation */
1199
1200 /** @defgroup internalAuthentication Authentication
1201  *  @ingroup internal */
1202
1203 /** @defgroup internalBasic CAS Basic client features (CAS 1.0, Service Tickets)
1204  *  @ingroup internal */
1205
1206 /** @defgroup internalProxy CAS Proxy features (CAS 2.0, Proxy Granting Tickets)
1207  *  @ingroup internal */
1208
1209 /** @defgroup internalPGTStorage PGT storage
1210  *  @ingroup internalProxy */
1211
1212 /** @defgroup internalPGTStorageDB PGT storage in a database
1213  *  @ingroup internalPGTStorage */
1214
1215 /** @defgroup internalPGTStorageFile PGT storage on the filesystem
1216  *  @ingroup internalPGTStorage */
1217
1218 /** @defgroup internalCallback Callback from the CAS server
1219  *  @ingroup internalProxy */
1220
1221 /** @defgroup internalProxied CAS proxied client features (CAS 2.0, Proxy Tickets)
1222  *  @ingroup internal */
1223
1224 /** @defgroup internalConfig Configuration
1225  *  @ingroup internal */
1226
1227 /** @defgroup internalOutput HTML output
1228  *  @ingroup internalConfig */
1229
1230 /** @defgroup internalLang Internationalization
1231  *  @ingroup internalConfig
1232  *
1233  * To add a new language:
1234  * - 1. define a new constant PHPCAS_LANG_XXXXXX in CAS/CAS.php
1235  * - 2. copy any file from CAS/languages to CAS/languages/XXXXXX.php
1236  * - 3. Make the translations
1237  */
1238
1239 /** @defgroup internalDebug Debugging
1240  *  @ingroup internal */
1241
1242 /** @defgroup internalMisc Miscellaneous
1243  *  @ingroup internal */
1244
1245 // ########################################################################
1246 //  EXAMPLES
1247
1248 /**
1249  * @example example_simple.php
1250  */
1251 /**
1252  * @example example_proxy.php
1253  */
1254 /**
1255  * @example example_proxy2.php
1256  */
1257 /**
1258  * @example example_lang.php
1259  */
1260 /**
1261  * @example example_html.php
1262  */
1263 /**
1264  * @example example_file.php
1265  */
1266 /**
1267  * @example example_db.php
1268  */
1269 /**
1270  * @example example_service.php
1271  */
1272 /**
1273  * @example example_session_proxy.php
1274  */
1275 /**
1276  * @example example_session_service.php
1277  */
1278 /**
1279  * @example example_gateway.php
1280  */
1281
1282
1283
1284 ?>