auth/cas/CAS/CAS.php

   1 <?php
   2
   3 /*
   4  * Copyright © 2003-2010, The ESUP-Portail consortium & the JA-SIG Collaborative.
   5  * All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions are met:
   9  *
  10  *     * Redistributions of source code must retain the above copyright notice,
  11  *       this list of conditions and the following disclaimer.
  12  *     * Redistributions in binary form must reproduce the above copyright notice,
  13  *       this list of conditions and the following disclaimer in the documentation
  14  *       and/or other materials provided with the distribution.
  15  *     * Neither the name of the ESUP-Portail consortium & the JA-SIG
  16  *       Collaborative nor the names of its contributors may be used to endorse or
  17  *       promote products derived from this software without specific prior
  18  *       written permission.
  19
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  21  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  22  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  23  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
  24  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  25  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  27  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32 //
  33 // hack by Vangelis Haniotakis to handle the absence of $_SERVER['REQUEST_URI'] in IIS
  34 //
  35 if (!isset($_SERVER['REQUEST_URI'])) {
  36         $_SERVER['REQUEST_URI'] = $_SERVER['SCRIPT_NAME'] . '?' . $_SERVER['QUERY_STRING'];
  37 }
  38
  39 //
  40 // another one by Vangelis Haniotakis also to make phpCAS work with PHP5
  41 //
  42 if (version_compare(PHP_VERSION, '5', '>=') && !(function_exists('domxml_new_doc'))) {
  43         require_once (dirname(__FILE__) . '/CAS/domxml-php4-to-php5.php');
  44 }
  45
  46 /**
  47  * @file CAS/CAS.php
  48  * Interface class of the phpCAS library
  49  *
  50  * @ingroup public
  51  */
  52
  53 // ########################################################################
  54 //  CONSTANTS
  55 // ########################################################################
  56
  57 // ------------------------------------------------------------------------
  58 //  CAS VERSIONS
  59 // ------------------------------------------------------------------------
  60
  61 /**
  62  * phpCAS version. accessible for the user by phpCAS::getVersion().
  63  */
  64 define('PHPCAS_VERSION', '1.1.3');
  65
  66 // ------------------------------------------------------------------------
  67 //  CAS VERSIONS
  68 // ------------------------------------------------------------------------
  69 /**
  70  * @addtogroup public
  71  * @{
  72  */
  73
  74 /**
  75  * CAS version 1.0
  76  */
  77 define("CAS_VERSION_1_0", '1.0');
  78 /*!
  79  * CAS version 2.0
  80  */
  81 define("CAS_VERSION_2_0", '2.0');
  82
  83 // ------------------------------------------------------------------------
  84 //  SAML defines
  85 // ------------------------------------------------------------------------
  86
  87 /**
  88  * SAML protocol
  89  */
  90 define("SAML_VERSION_1_1", 'S1');
  91
  92 /**
  93  * XML header for SAML POST
  94  */
  95 define("SAML_XML_HEADER", '<?xml version="1.0" encoding="UTF-8"?>');
  96
  97 /**
  98  * SOAP envelope for SAML POST
  99  */
 100 define("SAML_SOAP_ENV", '<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Header/>');
 101
 102 /**
 103  * SOAP body for SAML POST
 104  */
 105 define("SAML_SOAP_BODY", '<SOAP-ENV:Body>');
 106
 107 /**
 108  * SAMLP request
 109  */
 110 define("SAMLP_REQUEST", '<samlp:Request xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"  MajorVersion="1" MinorVersion="1" RequestID="_192.168.16.51.1024506224022" IssueInstant="2002-06-19T17:03:44.022Z">');
 111 define("SAMLP_REQUEST_CLOSE", '</samlp:Request>');
 112
 113 /**
 114  * SAMLP artifact tag (for the ticket)
 115  */
 116 define("SAML_ASSERTION_ARTIFACT", '<samlp:AssertionArtifact>');
 117
 118 /**
 119  * SAMLP close
 120  */
 121 define("SAML_ASSERTION_ARTIFACT_CLOSE", '</samlp:AssertionArtifact>');
 122
 123 /**
 124  * SOAP body close
 125  */
 126 define("SAML_SOAP_BODY_CLOSE", '</SOAP-ENV:Body>');
 127
 128 /**
 129  * SOAP envelope close
 130  */
 131 define("SAML_SOAP_ENV_CLOSE", '</SOAP-ENV:Envelope>');
 132
 133 /**
 134  * SAML Attributes
 135  */
 136 define("SAML_ATTRIBUTES", 'SAMLATTRIBS');
 137
 138 /** @} */
 139 /**
 140  * @addtogroup publicPGTStorage
 141  * @{
 142  */
 143 // ------------------------------------------------------------------------
 144 //  FILE PGT STORAGE
 145 // ------------------------------------------------------------------------
 146 /**
 147  * Default path used when storing PGT's to file
 148  */
 149 define("CAS_PGT_STORAGE_FILE_DEFAULT_PATH", '/tmp');
 150 /**
 151  * phpCAS::setPGTStorageFile()'s 2nd parameter to write plain text files
 152  */
 153 define("CAS_PGT_STORAGE_FILE_FORMAT_PLAIN", 'plain');
 154 /**
 155  * phpCAS::setPGTStorageFile()'s 2nd parameter to write xml files
 156  */
 157 define("CAS_PGT_STORAGE_FILE_FORMAT_XML", 'xml');
 158 /**
 159  * Default format used when storing PGT's to file
 160  */
 161 define("CAS_PGT_STORAGE_FILE_DEFAULT_FORMAT", CAS_PGT_STORAGE_FILE_FORMAT_PLAIN);
 162 /** @} */
 163 // ------------------------------------------------------------------------
 164 // SERVICE ACCESS ERRORS
 165 // ------------------------------------------------------------------------
 166 /**
 167  * @addtogroup publicServices
 168  * @{
 169  */
 170
 171 /**
 172  * phpCAS::service() error code on success
 173  */
 174 define("PHPCAS_SERVICE_OK", 0);
 175 /**
 176  * phpCAS::service() error code when the PT could not retrieve because
 177  * the CAS server did not respond.
 178  */
 179 define("PHPCAS_SERVICE_PT_NO_SERVER_RESPONSE", 1);
 180 /**
 181  * phpCAS::service() error code when the PT could not retrieve because
 182  * the response of the CAS server was ill-formed.
 183  */
 184 define("PHPCAS_SERVICE_PT_BAD_SERVER_RESPONSE", 2);
 185 /**
 186  * phpCAS::service() error code when the PT could not retrieve because
 187  * the CAS server did not want to.
 188  */
 189 define("PHPCAS_SERVICE_PT_FAILURE", 3);
 190 /**
 191  * phpCAS::service() error code when the service was not available.
 192  */
 193 define("PHPCAS_SERVICE_NOT AVAILABLE", 4);
 194
 195 /** @} */
 196 // ------------------------------------------------------------------------
 197 //  LANGUAGES
 198 // ------------------------------------------------------------------------
 199 /**
 200  * @addtogroup publicLang
 201  * @{
 202  */
 203
 204 define("PHPCAS_LANG_ENGLISH", 'english');
 205 define("PHPCAS_LANG_FRENCH", 'french');
 206 define("PHPCAS_LANG_GREEK", 'greek');
 207 define("PHPCAS_LANG_GERMAN", 'german');
 208 define("PHPCAS_LANG_JAPANESE", 'japanese');
 209 define("PHPCAS_LANG_SPANISH", 'spanish');
 210 define("PHPCAS_LANG_CATALAN", 'catalan');
 211
 212 /** @} */
 213
 214 /**
 215  * @addtogroup internalLang
 216  * @{
 217  */
 218
 219 /**
 220  * phpCAS default language (when phpCAS::setLang() is not used)
 221  */
 222 define("PHPCAS_LANG_DEFAULT", PHPCAS_LANG_ENGLISH);
 223
 224 /** @} */
 225 // ------------------------------------------------------------------------
 226 //  DEBUG
 227 // ------------------------------------------------------------------------
 228 /**
 229  * @addtogroup publicDebug
 230  * @{
 231  */
 232
 233 /**
 234  * The default directory for the debug file under Unix.
 235  */
 236 define('DEFAULT_DEBUG_DIR', '/tmp/');
 237
 238 /** @} */
 239 // ------------------------------------------------------------------------
 240 //  MISC
 241 // ------------------------------------------------------------------------
 242 /**
 243  * @addtogroup internalMisc
 244  * @{
 245  */
 246
 247 /**
 248  * This global variable is used by the interface class phpCAS.
 249  *
 250  * @hideinitializer
 251  */
 252 $GLOBALS['PHPCAS_CLIENT'] = null;
 253
 254 /**
 255  * This global variable is used to store where the initializer is called from
 256  * (to print a comprehensive error in case of multiple calls).
 257  *
 258  * @hideinitializer
 259  */
 260 $GLOBALS['PHPCAS_INIT_CALL'] = array (
 261         'done' => FALSE,
 262         'file' => '?',
 263         'line' => -1,
 264         'method' => '?'
 265 );
 266
 267 /**
 268  * This global variable is used to store where the method checking
 269  * the authentication is called from (to print comprehensive errors)
 270  *
 271  * @hideinitializer
 272  */
 273 $GLOBALS['PHPCAS_AUTH_CHECK_CALL'] = array (
 274         'done' => FALSE,
 275         'file' => '?',
 276         'line' => -1,
 277         'method' => '?',
 278         'result' => FALSE
 279 );
 280
 281 /**
 282  * This global variable is used to store phpCAS debug mode.
 283  *
 284  * @hideinitializer
 285  */
 286 $GLOBALS['PHPCAS_DEBUG'] = array (
 287         'filename' => FALSE,
 288         'indent' => 0,
 289         'unique_id' => ''
 290 );
 291
 292 /** @} */
 293
 294 // ########################################################################
 295 //  CLIENT CLASS
 296 // ########################################################################
 297
 298 // include client class
 299 include_once (dirname(__FILE__) . '/CAS/client.php');
 300
 301 // ########################################################################
 302 //  INTERFACE CLASS
 303 // ########################################################################
 304
 305 /**
 306  * @class phpCAS
 307  * The phpCAS class is a simple container for the phpCAS library. It provides CAS
 308  * authentication for web applications written in PHP.
 309  *
 310  * @ingroup public
 311  * @author Pascal Aubry <pascal.aubry at univ-rennes1.fr>
 312  *
 313  * \internal All its methods access the same object ($PHPCAS_CLIENT, declared
 314  * at the end of CAS/client.php).
 315  */
 316
 317 class phpCAS {
 318
 319         // ########################################################################
 320         //  INITIALIZATION
 321         // ########################################################################
 322
 323         /**
 324          * @addtogroup publicInit
 325          * @{
 326          */
 327
 328         /**
 329          * phpCAS client initializer.
 330          * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
 331          * called, only once, and before all other methods (except phpCAS::getVersion()
 332          * and phpCAS::setDebug()).
 333          *
 334          * @param $server_version the version of the CAS server
 335          * @param $server_hostname the hostname of the CAS server
 336          * @param $server_port the port the CAS server is running on
 337          * @param $server_uri the URI the CAS server is responding on
 338          * @param $start_session Have phpCAS start PHP sessions (default true)
 339          *
 340          * @return a newly created CASClient object
 341          */
 342         function client($server_version, $server_hostname, $server_port, $server_uri, $start_session = true) {
 343                 global $PHPCAS_CLIENT, $PHPCAS_INIT_CALL;
 344
 345                 phpCAS :: traceBegin();
 346                 if (is_object($PHPCAS_CLIENT)) {
 347                         phpCAS :: error($PHPCAS_INIT_CALL['method'] . '() has already been called (at ' . $PHPCAS_INIT_CALL['file'] . ':' . $PHPCAS_INIT_CALL['line'] . ')');
 348                 }
 349                 if (gettype($server_version) != 'string') {
 350                         phpCAS :: error('type mismatched for parameter $server_version (should be `string\')');
 351                 }
 352                 if (gettype($server_hostname) != 'string') {
 353                         phpCAS :: error('type mismatched for parameter $server_hostname (should be `string\')');
 354                 }
 355                 if (gettype($server_port) != 'integer') {
 356                         phpCAS :: error('type mismatched for parameter $server_port (should be `integer\')');
 357                 }
 358                 if (gettype($server_uri) != 'string') {
 359                         phpCAS :: error('type mismatched for parameter $server_uri (should be `string\')');
 360                 }
 361
 362                 // store where the initializer is called from
 363                 $dbg = phpCAS :: backtrace();
 364                 $PHPCAS_INIT_CALL = array (
 365                         'done' => TRUE,
 366                         'file' => $dbg[0]['file'],
 367                         'line' => $dbg[0]['line'],
 368                         'method' => __CLASS__ . '::' . __FUNCTION__
 369                 );
 370
 371                 // initialize the global object $PHPCAS_CLIENT
 372                 $PHPCAS_CLIENT = new CASClient($server_version, FALSE /*proxy*/
 373                 , $server_hostname, $server_port, $server_uri, $start_session);
 374                 phpCAS :: traceEnd();
 375         }
 376
 377         /**
 378          * phpCAS proxy initializer.
 379          * @note Only one of the phpCAS::client() and phpCAS::proxy functions should be
 380          * called, only once, and before all other methods (except phpCAS::getVersion()
 381          * and phpCAS::setDebug()).
 382          *
 383          * @param $server_version the version of the CAS server
 384          * @param $server_hostname the hostname of the CAS server
 385          * @param $server_port the port the CAS server is running on
 386          * @param $server_uri the URI the CAS server is responding on
 387          * @param $start_session Have phpCAS start PHP sessions (default true)
 388          *
 389          * @return a newly created CASClient object
 390          */
 391         function proxy($server_version, $server_hostname, $server_port, $server_uri, $start_session = true) {
 392                 global $PHPCAS_CLIENT, $PHPCAS_INIT_CALL;
 393
 394                 phpCAS :: traceBegin();
 395                 if (is_object($PHPCAS_CLIENT)) {
 396                         phpCAS :: error($PHPCAS_INIT_CALL['method'] . '() has already been called (at ' . $PHPCAS_INIT_CALL['file'] . ':' . $PHPCAS_INIT_CALL['line'] . ')');
 397                 }
 398                 if (gettype($server_version) != 'string') {
 399                         phpCAS :: error('type mismatched for parameter $server_version (should be `string\')');
 400                 }
 401                 if (gettype($server_hostname) != 'string') {
 402                         phpCAS :: error('type mismatched for parameter $server_hostname (should be `string\')');
 403                 }
 404                 if (gettype($server_port) != 'integer') {
 405                         phpCAS :: error('type mismatched for parameter $server_port (should be `integer\')');
 406                 }
 407                 if (gettype($server_uri) != 'string') {
 408                         phpCAS :: error('type mismatched for parameter $server_uri (should be `string\')');
 409                 }
 410
 411                 // store where the initialzer is called from
 412                 $dbg = phpCAS :: backtrace();
 413                 $PHPCAS_INIT_CALL = array (
 414                         'done' => TRUE,
 415                         'file' => $dbg[0]['file'],
 416                         'line' => $dbg[0]['line'],
 417                         'method' => __CLASS__ . '::' . __FUNCTION__
 418                 );
 419
 420                 // initialize the global object $PHPCAS_CLIENT
 421                 $PHPCAS_CLIENT = new CASClient($server_version, TRUE /*proxy*/
 422                 , $server_hostname, $server_port, $server_uri, $start_session);
 423                 phpCAS :: traceEnd();
 424         }
 425
 426         /** @} */
 427         // ########################################################################
 428         //  DEBUGGING
 429         // ########################################################################
 430
 431         /**
 432          * @addtogroup publicDebug
 433          * @{
 434          */
 435
 436         /**
 437          * Set/unset debug mode
 438          *
 439          * @param $filename the name of the file used for logging, or FALSE to stop debugging.
 440          */
 441         function setDebug($filename = '') {
 442                 global $PHPCAS_DEBUG;
 443
 444                 if ($filename != FALSE && gettype($filename) != 'string') {
 445                         phpCAS :: error('type mismatched for parameter $dbg (should be FALSE or the name of the log file)');
 446                 }
 447
 448                 if (empty ($filename)) {
 449                         if (preg_match('/^Win.*/', getenv('OS'))) {
 450                                 if (isset ($_ENV['TMP'])) {
 451                                         $debugDir = $_ENV['TMP'] . '/';
 452                                 } else
 453                                         if (isset ($_ENV['TEMP'])) {
 454                                                 $debugDir = $_ENV['TEMP'] . '/';
 455                                         } else {
 456                                                 $debugDir = '';
 457                                         }
 458                         } else {
 459                                 $debugDir = DEFAULT_DEBUG_DIR;
 460                         }
 461                         $filename = $debugDir . 'phpCAS.log';
 462                 }
 463
 464                 if (empty ($PHPCAS_DEBUG['unique_id'])) {
 465                         $PHPCAS_DEBUG['unique_id'] = substr(strtoupper(md5(uniqid(''))), 0, 4);
 466                 }
 467
 468                 $PHPCAS_DEBUG['filename'] = $filename;
 469
 470                 phpCAS :: trace('START phpCAS-' . PHPCAS_VERSION . ' ******************');
 471         }
 472
 473         /** @} */
 474         /**
 475          * @addtogroup internalDebug
 476          * @{
 477          */
 478
 479         /**
 480          * This method is a wrapper for debug_backtrace() that is not available
 481          * in all PHP versions (>= 4.3.0 only)
 482          */
 483         function backtrace() {
 484                 if (function_exists('debug_backtrace')) {
 485                         return debug_backtrace();
 486                 } else {
 487                         // poor man's hack ... but it does work ...
 488                         return array ();
 489                 }
 490         }
 491
 492         /**
 493          * Logs a string in debug mode.
 494          *
 495          * @param $str the string to write
 496          *
 497          * @private
 498          */
 499         function log($str) {
 500                 $indent_str = ".";
 501                 global $PHPCAS_DEBUG;
 502
 503                 if ($PHPCAS_DEBUG['filename']) {
 504                         for ($i = 0; $i < $PHPCAS_DEBUG['indent']; $i++) {
 505                                 $indent_str .= '|    ';
 506                         }
 507                         error_log($PHPCAS_DEBUG['unique_id'] . ' ' . $indent_str . $str . "\n", 3, $PHPCAS_DEBUG['filename']);
 508                 }
 509
 510         }
 511
 512         /**
 513          * This method is used by interface methods to print an error and where the function
 514          * was originally called from.
 515          *
 516          * @param $msg the message to print
 517          *
 518          * @private
 519          */
 520         function error($msg) {
 521                 $dbg = phpCAS :: backtrace();
 522                 $function = '?';
 523                 $file = '?';
 524                 $line = '?';
 525                 if (is_array($dbg)) {
 526                         for ($i = 1; $i < sizeof($dbg); $i++) {
 527                                 if (is_array($dbg[$i])) {
 528                                         if ($dbg[$i]['class'] == __CLASS__) {
 529                                                 $function = $dbg[$i]['function'];
 530                                                 $file = $dbg[$i]['file'];
 531                                                 $line = $dbg[$i]['line'];
 532                                         }
 533                                 }
 534                         }
 535                 }
 536                 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";
 537                 phpCAS :: trace($msg);
 538                 phpCAS :: traceExit();
 539                 exit ();
 540         }
 541
 542         /**
 543          * This method is used to log something in debug mode.
 544          */
 545         function trace($str) {
 546                 $dbg = phpCAS :: backtrace();
 547                 phpCAS :: log($str . ' [' . basename($dbg[1]['file']) . ':' . $dbg[1]['line'] . ']');
 548         }
 549
 550         /**
 551          * This method is used to indicate the start of the execution of a function in debug mode.
 552          */
 553         function traceBegin() {
 554                 global $PHPCAS_DEBUG;
 555
 556                 $dbg = phpCAS :: backtrace();
 557                 $str = '=> ';
 558                 if (!empty ($dbg[2]['class'])) {
 559                         $str .= $dbg[2]['class'] . '::';
 560                 }
 561                 $str .= $dbg[2]['function'] . '(';
 562                 if (is_array($dbg[2]['args'])) {
 563                         foreach ($dbg[2]['args'] as $index => $arg) {
 564                                 if ($index != 0) {
 565                                         $str .= ', ';
 566                                 }
 567                                 $str .= str_replace("\n", "", var_export($arg, TRUE));
 568                         }
 569                 }
 570                 $str .= ') [' . basename($dbg[2]['file']) . ':' . $dbg[2]['line'] . ']';
 571                 phpCAS :: log($str);
 572                 $PHPCAS_DEBUG['indent']++;
 573         }
 574
 575         /**
 576          * This method is used to indicate the end of the execution of a function in debug mode.
 577          *
 578          * @param $res the result of the function
 579          */
 580         function traceEnd($res = '') {
 581                 global $PHPCAS_DEBUG;
 582
 583                 $PHPCAS_DEBUG['indent']--;
 584                 $dbg = phpCAS :: backtrace();
 585                 $str = '';
 586                 $str .= '<= ' . str_replace("\n", "", var_export($res, TRUE));
 587                 phpCAS :: log($str);
 588         }
 589
 590         /**
 591          * This method is used to indicate the end of the execution of the program
 592          */
 593         function traceExit() {
 594                 global $PHPCAS_DEBUG;
 595
 596                 phpCAS :: log('exit()');
 597                 while ($PHPCAS_DEBUG['indent'] > 0) {
 598                         phpCAS :: log('-');
 599                         $PHPCAS_DEBUG['indent']--;
 600                 }
 601         }
 602
 603         /** @} */
 604         // ########################################################################
 605         //  INTERNATIONALIZATION
 606         // ########################################################################
 607         /**
 608          * @addtogroup publicLang
 609          * @{
 610          */
 611
 612         /**
 613          * This method is used to set the language used by phpCAS.
 614          * @note Can be called only once.
 615          *
 616          * @param $lang a string representing the language.
 617          *
 618          * @sa PHPCAS_LANG_FRENCH, PHPCAS_LANG_ENGLISH
 619          */
 620         function setLang($lang) {
 621                 global $PHPCAS_CLIENT;
 622                 if (!is_object($PHPCAS_CLIENT)) {
 623                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
 624                 }
 625                 if (gettype($lang) != 'string') {
 626                         phpCAS :: error('type mismatched for parameter $lang (should be `string\')');
 627                 }
 628                 $PHPCAS_CLIENT->setLang($lang);
 629         }
 630
 631         /** @} */
 632         // ########################################################################
 633         //  VERSION
 634         // ########################################################################
 635         /**
 636          * @addtogroup public
 637          * @{
 638          */
 639
 640         /**
 641          * This method returns the phpCAS version.
 642          *
 643          * @return the phpCAS version.
 644          */
 645         function getVersion() {
 646                 return PHPCAS_VERSION;
 647         }
 648
 649         /** @} */
 650         // ########################################################################
 651         //  HTML OUTPUT
 652         // ########################################################################
 653         /**
 654          * @addtogroup publicOutput
 655          * @{
 656          */
 657
 658         /**
 659          * This method sets the HTML header used for all outputs.
 660          *
 661          * @param $header the HTML header.
 662          */
 663         function setHTMLHeader($header) {
 664                 global $PHPCAS_CLIENT;
 665                 if (!is_object($PHPCAS_CLIENT)) {
 666                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
 667                 }
 668                 if (gettype($header) != 'string') {
 669                         phpCAS :: error('type mismatched for parameter $header (should be `string\')');
 670                 }
 671                 $PHPCAS_CLIENT->setHTMLHeader($header);
 672         }
 673
 674         /**
 675          * This method sets the HTML footer used for all outputs.
 676          *
 677          * @param $footer the HTML footer.
 678          */
 679         function setHTMLFooter($footer) {
 680                 global $PHPCAS_CLIENT;
 681                 if (!is_object($PHPCAS_CLIENT)) {
 682                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
 683                 }
 684                 if (gettype($footer) != 'string') {
 685                         phpCAS :: error('type mismatched for parameter $footer (should be `string\')');
 686                 }
 687                 $PHPCAS_CLIENT->setHTMLFooter($footer);
 688         }
 689
 690         /** @} */
 691         // ########################################################################
 692         //  PGT STORAGE
 693         // ########################################################################
 694         /**
 695          * @addtogroup publicPGTStorage
 696          * @{
 697          */
 698
 699         /**
 700          * This method is used to tell phpCAS to store the response of the
 701          * CAS server to PGT requests onto the filesystem.
 702          *
 703          * @param $format the format used to store the PGT's (`plain' and `xml' allowed)
 704          * @param $path the path where the PGT's should be stored
 705          */
 706         function setPGTStorageFile($format = '', $path = '') {
 707                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 708
 709                 phpCAS :: traceBegin();
 710                 if (!is_object($PHPCAS_CLIENT)) {
 711                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
 712                 }
 713                 if (!$PHPCAS_CLIENT->isProxy()) {
 714                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
 715                 }
 716                 if ($PHPCAS_AUTH_CHECK_CALL['done']) {
 717                         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'] . ')');
 718                 }
 719                 if (gettype($format) != 'string') {
 720                         phpCAS :: error('type mismatched for parameter $format (should be `string\')');
 721                 }
 722                 if (gettype($path) != 'string') {
 723                         phpCAS :: error('type mismatched for parameter $format (should be `string\')');
 724                 }
 725                 $PHPCAS_CLIENT->setPGTStorageFile($format, $path);
 726                 phpCAS :: traceEnd();
 727         }
 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                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 754
 755                 phpCAS :: traceBegin();
 756                 if (!is_object($PHPCAS_CLIENT)) {
 757                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
 758                 }
 759                 if (!$PHPCAS_CLIENT->isProxy()) {
 760                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
 761                 }
 762                 if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
 763                         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()');
 764                 }
 765                 if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
 766                         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');
 767                 }
 768                 if (gettype($url) != 'string') {
 769                         phpCAS :: error('type mismatched for parameter $url (should be `string\')');
 770                 }
 771
 772                 $res = $PHPCAS_CLIENT->serviceWeb($url, $err_code, $output);
 773
 774                 phpCAS :: traceEnd($res);
 775                 return $res;
 776         }
 777
 778         /**
 779          * This method is used to access an IMAP/POP3/NNTP service.
 780          *
 781          * @param $url a string giving the URL of the service, including the mailing box
 782          * for IMAP URLs, as accepted by imap_open().
 783          * @param $service a string giving for CAS retrieve Proxy ticket
 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, $service, $flags, & $err_code, & $err_msg, & $pt) {
 796                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 797
 798                 phpCAS :: traceBegin();
 799                 if (!is_object($PHPCAS_CLIENT)) {
 800                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
 801                 }
 802                 if (!$PHPCAS_CLIENT->isProxy()) {
 803                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
 804                 }
 805                 if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
 806                         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()');
 807                 }
 808                 if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
 809                         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');
 810                 }
 811                 if (gettype($url) != 'string') {
 812                         phpCAS :: error('type mismatched for parameter $url (should be `string\')');
 813                 }
 814
 815                 if (gettype($flags) != 'integer') {
 816                         phpCAS :: error('type mismatched for parameter $flags (should be `integer\')');
 817                 }
 818
 819                 $res = $PHPCAS_CLIENT->serviceMail($url, $service, $flags, $err_code, $err_msg, $pt);
 820
 821                 phpCAS :: traceEnd($res);
 822                 return $res;
 823         }
 824
 825         /** @} */
 826         // ########################################################################
 827         //  AUTHENTICATION
 828         // ########################################################################
 829         /**
 830          * @addtogroup publicAuth
 831          * @{
 832          */
 833
 834         /**
 835          * Set the times authentication will be cached before really accessing the CAS server in gateway mode:
 836          * - -1: check only once, and then never again (until you pree login)
 837          * - 0: always check
 838          * - n: check every "n" time
 839          *
 840          * @param $n an integer.
 841          */
 842         function setCacheTimesForAuthRecheck($n) {
 843                 global $PHPCAS_CLIENT;
 844                 if (!is_object($PHPCAS_CLIENT)) {
 845                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
 846                 }
 847                 if (gettype($n) != 'integer') {
 848                         phpCAS :: error('type mismatched for parameter $header (should be `string\')');
 849                 }
 850                 $PHPCAS_CLIENT->setCacheTimesForAuthRecheck($n);
 851         }
 852
 853         /**
 854          * This method is called to check if the user is authenticated (use the gateway feature).
 855          * @return TRUE when the user is authenticated; otherwise FALSE.
 856          */
 857         function checkAuthentication() {
 858                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 859
 860                 phpCAS :: traceBegin();
 861                 if (!is_object($PHPCAS_CLIENT)) {
 862                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
 863                 }
 864
 865                 $auth = $PHPCAS_CLIENT->checkAuthentication();
 866
 867                 // store where the authentication has been checked and the result
 868                 $dbg = phpCAS :: backtrace();
 869                 $PHPCAS_AUTH_CHECK_CALL = array (
 870                         'done' => TRUE,
 871                         'file' => $dbg[0]['file'],
 872                         'line' => $dbg[0]['line'],
 873                         'method' => __CLASS__ . '::' . __FUNCTION__,
 874                         'result' => $auth
 875                 );
 876                 phpCAS :: traceEnd($auth);
 877                 return $auth;
 878         }
 879
 880         /**
 881          * This method is called to force authentication if the user was not already
 882          * authenticated. If the user is not authenticated, halt by redirecting to
 883          * the CAS server.
 884          */
 885         function forceAuthentication() {
 886                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 887
 888                 phpCAS :: traceBegin();
 889                 if (!is_object($PHPCAS_CLIENT)) {
 890                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
 891                 }
 892
 893                 $auth = $PHPCAS_CLIENT->forceAuthentication();
 894
 895                 // store where the authentication has been checked and the result
 896                 $dbg = phpCAS :: backtrace();
 897                 $PHPCAS_AUTH_CHECK_CALL = array (
 898                         'done' => TRUE,
 899                         'file' => $dbg[0]['file'],
 900                         'line' => $dbg[0]['line'],
 901                         'method' => __CLASS__ . '::' . __FUNCTION__,
 902                         'result' => $auth
 903                 );
 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 is called to renew the authentication.
 918          **/
 919         function renewAuthentication() {
 920                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 921
 922                 phpCAS :: traceBegin();
 923                 if (!is_object($PHPCAS_CLIENT)) {
 924                         phpCAS :: error('this method should not be called before' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
 925                 }
 926
 927                 // store where the authentication has been checked and the result
 928                 $dbg = phpCAS :: backtrace();
 929                 $PHPCAS_AUTH_CHECK_CALL = array (
 930                         'done' => TRUE,
 931                         'file' => $dbg[0]['file'],
 932                         'line' => $dbg[0]['line'],
 933                         'method' => __CLASS__ . '::' . __FUNCTION__,
 934                         'result' => $auth
 935                 );
 936
 937                 $PHPCAS_CLIENT->renewAuthentication();
 938                 phpCAS :: traceEnd();
 939         }
 940
 941         /**
 942          * This method has been left from version 0.4.1 for compatibility reasons.
 943          */
 944         function authenticate() {
 945                 phpCAS :: error('this method is deprecated. You should use ' . __CLASS__ . '::forceAuthentication() instead');
 946         }
 947
 948         /**
 949          * This method is called to check if the user is authenticated (previously or by
 950          * tickets given in the URL).
 951          *
 952          * @return TRUE when the user is authenticated.
 953          */
 954         function isAuthenticated() {
 955                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
 956
 957                 phpCAS :: traceBegin();
 958                 if (!is_object($PHPCAS_CLIENT)) {
 959                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
 960                 }
 961
 962                 // call the isAuthenticated method of the global $PHPCAS_CLIENT object
 963                 $auth = $PHPCAS_CLIENT->isAuthenticated();
 964
 965                 // store where the authentication has been checked and the result
 966                 $dbg = phpCAS :: backtrace();
 967                 $PHPCAS_AUTH_CHECK_CALL = array (
 968                         'done' => TRUE,
 969                         'file' => $dbg[0]['file'],
 970                         'line' => $dbg[0]['line'],
 971                         'method' => __CLASS__ . '::' . __FUNCTION__,
 972                         'result' => $auth
 973                 );
 974                 phpCAS :: traceEnd($auth);
 975                 return $auth;
 976         }
 977
 978         /**
 979          * Checks whether authenticated based on $_SESSION. Useful to avoid
 980          * server calls.
 981          * @return true if authenticated, false otherwise.
 982          * @since 0.4.22 by Brendan Arnold
 983          */
 984         function isSessionAuthenticated() {
 985                 global $PHPCAS_CLIENT;
 986                 if (!is_object($PHPCAS_CLIENT)) {
 987                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
 988                 }
 989                 return ($PHPCAS_CLIENT->isSessionAuthenticated());
 990         }
 991
 992         /**
 993          * This method returns the CAS user's login name.
 994          * @warning should not be called only after phpCAS::forceAuthentication()
 995          * or phpCAS::checkAuthentication().
 996          *
 997          * @return the login name of the authenticated user
 998          */
 999         function getUser() {
1000                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
1001                 if (!is_object($PHPCAS_CLIENT)) {
1002                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1003                 }
1004                 if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
1005                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::forceAuthentication() or ' . __CLASS__ . '::isAuthenticated()');
1006                 }
1007                 if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
1008                         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');
1009                 }
1010                 return $PHPCAS_CLIENT->getUser();
1011         }
1012
1013         /**
1014          * This method returns the CAS user's login name.
1015          * @warning should not be called only after phpCAS::forceAuthentication()
1016          * or phpCAS::checkAuthentication().
1017          *
1018          * @return the login name of the authenticated user
1019          */
1020         function getAttributes() {
1021                 global $PHPCAS_CLIENT, $PHPCAS_AUTH_CHECK_CALL;
1022                 if (!is_object($PHPCAS_CLIENT)) {
1023                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1024                 }
1025                 if (!$PHPCAS_AUTH_CHECK_CALL['done']) {
1026                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::forceAuthentication() or ' . __CLASS__ . '::isAuthenticated()');
1027                 }
1028                 if (!$PHPCAS_AUTH_CHECK_CALL['result']) {
1029                         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');
1030                 }
1031                 return $PHPCAS_CLIENT->getAttributes();
1032         }
1033         /**
1034          * Handle logout requests.
1035          */
1036         function handleLogoutRequests($check_client = true, $allowed_clients = false) {
1037                 global $PHPCAS_CLIENT;
1038                 if (!is_object($PHPCAS_CLIENT)) {
1039                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1040                 }
1041                 return ($PHPCAS_CLIENT->handleLogoutRequests($check_client, $allowed_clients));
1042         }
1043
1044         /**
1045          * This method returns the URL to be used to login.
1046          * or phpCAS::isAuthenticated().
1047          *
1048          * @return the login name of the authenticated user
1049          */
1050         function getServerLoginURL() {
1051                 global $PHPCAS_CLIENT;
1052                 if (!is_object($PHPCAS_CLIENT)) {
1053                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1054                 }
1055                 return $PHPCAS_CLIENT->getServerLoginURL();
1056         }
1057
1058         /**
1059          * Set the login URL of the CAS server.
1060          * @param $url the login URL
1061          * @since 0.4.21 by Wyman Chan
1062          */
1063         function setServerLoginURL($url = '') {
1064                 global $PHPCAS_CLIENT;
1065                 phpCAS :: traceBegin();
1066                 if (!is_object($PHPCAS_CLIENT)) {
1067                         phpCAS :: error('this method should only be called after
1068                                                         ' . __CLASS__ . '::client()');
1069                 }
1070                 if (gettype($url) != 'string') {
1071                         phpCAS :: error('type mismatched for parameter $url (should be
1072                                                 `string\')');
1073                 }
1074                 $PHPCAS_CLIENT->setServerLoginURL($url);
1075                 phpCAS :: traceEnd();
1076         }
1077
1078         /**
1079          * Set the serviceValidate URL of the CAS server.
1080          * Used only in CAS 1.0 validations
1081          * @param $url the serviceValidate URL
1082          * @since 1.1.0 by Joachim Fritschi
1083          */
1084         function setServerServiceValidateURL($url = '') {
1085                 global $PHPCAS_CLIENT;
1086                 phpCAS :: traceBegin();
1087                 if (!is_object($PHPCAS_CLIENT)) {
1088                         phpCAS :: error('this method should only be called after
1089                                                         ' . __CLASS__ . '::client()');
1090                 }
1091                 if (gettype($url) != 'string') {
1092                         phpCAS :: error('type mismatched for parameter $url (should be
1093                                                 `string\')');
1094                 }
1095                 $PHPCAS_CLIENT->setServerServiceValidateURL($url);
1096                 phpCAS :: traceEnd();
1097         }
1098
1099         /**
1100          * Set the proxyValidate URL of the CAS server.
1101          * Used for all CAS 2.0 validations
1102          * @param $url the proxyValidate URL
1103          * @since 1.1.0 by Joachim Fritschi
1104          */
1105         function setServerProxyValidateURL($url = '') {
1106                 global $PHPCAS_CLIENT;
1107                 phpCAS :: traceBegin();
1108                 if (!is_object($PHPCAS_CLIENT)) {
1109                         phpCAS :: error('this method should only be called after
1110                                                         ' . __CLASS__ . '::client()');
1111                 }
1112                 if (gettype($url) != 'string') {
1113                         phpCAS :: error('type mismatched for parameter $url (should be
1114                                                 `string\')');
1115                 }
1116                 $PHPCAS_CLIENT->setServerProxyValidateURL($url);
1117                 phpCAS :: traceEnd();
1118         }
1119
1120         /**
1121          * Set the samlValidate URL of the CAS server.
1122          * @param $url the samlValidate URL
1123          * @since 1.1.0 by Joachim Fritschi
1124          */
1125         function setServerSamlValidateURL($url = '') {
1126                 global $PHPCAS_CLIENT;
1127                 phpCAS :: traceBegin();
1128                 if (!is_object($PHPCAS_CLIENT)) {
1129                         phpCAS :: error('this method should only be called after
1130                                                         ' . __CLASS__ . '::client()');
1131                 }
1132                 if (gettype($url) != 'string') {
1133                         phpCAS :: error('type mismatched for parameter $url (should be
1134                                                 `string\')');
1135                 }
1136                 $PHPCAS_CLIENT->setServerSamlValidateURL($url);
1137                 phpCAS :: traceEnd();
1138         }
1139
1140         /**
1141          * This method returns the URL to be used to login.
1142          * or phpCAS::isAuthenticated().
1143          *
1144          * @return the login name of the authenticated user
1145          */
1146         function getServerLogoutURL() {
1147                 global $PHPCAS_CLIENT;
1148                 if (!is_object($PHPCAS_CLIENT)) {
1149                         phpCAS :: error('this method should not be called before ' . __CLASS__ . '::client() or ' . __CLASS__ . '::proxy()');
1150                 }
1151                 return $PHPCAS_CLIENT->getServerLogoutURL();
1152         }
1153
1154         /**
1155          * Set the logout URL of the CAS server.
1156          * @param $url the logout URL
1157          * @since 0.4.21 by Wyman Chan
1158          */
1159         function setServerLogoutURL($url = '') {
1160                 global $PHPCAS_CLIENT;
1161                 phpCAS :: traceBegin();
1162                 if (!is_object($PHPCAS_CLIENT)) {
1163                         phpCAS :: error('this method should only be called after
1164                                                         ' . __CLASS__ . '::client()');
1165                 }
1166                 if (gettype($url) != 'string') {
1167                         phpCAS :: error('type mismatched for parameter $url (should be
1168                                                 `string\')');
1169                 }
1170                 $PHPCAS_CLIENT->setServerLogoutURL($url);
1171                 phpCAS :: traceEnd();
1172         }
1173
1174         /**
1175          * This method is used to logout from CAS.
1176          * @params $params an array that contains the optional url and service parameters that will be passed to the CAS server
1177          * @public
1178          */
1179         function logout($params = "") {
1180                 global $PHPCAS_CLIENT;
1181                 phpCAS :: traceBegin();
1182                 if (!is_object($PHPCAS_CLIENT)) {
1183                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1184                 }
1185                 $parsedParams = array ();
1186                 if ($params != "") {
1187                         if (is_string($params)) {
1188                                 phpCAS :: error('method `phpCAS::logout($url)\' is now deprecated, use `phpCAS::logoutWithUrl($url)\' instead');
1189                         }
1190                         if (!is_array($params)) {
1191                                 phpCAS :: error('type mismatched for parameter $params (should be `array\')');
1192                         }
1193                         foreach ($params as $key => $value) {
1194                                 if ($key != "service" && $key != "url") {
1195                                         phpCAS :: error('only `url\' and `service\' parameters are allowed for method `phpCAS::logout($params)\'');
1196                                 }
1197                                 $parsedParams[$key] = $value;
1198                         }
1199                 }
1200                 $PHPCAS_CLIENT->logout($parsedParams);
1201                 // never reached
1202                 phpCAS :: traceEnd();
1203         }
1204
1205         /**
1206          * This method is used to logout from CAS. Halts by redirecting to the CAS server.
1207          * @param $service a URL that will be transmitted to the CAS server
1208          */
1209         function logoutWithRedirectService($service) {
1210                 global $PHPCAS_CLIENT;
1211                 phpCAS :: traceBegin();
1212                 if (!is_object($PHPCAS_CLIENT)) {
1213                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1214                 }
1215                 if (!is_string($service)) {
1216                         phpCAS :: error('type mismatched for parameter $service (should be `string\')');
1217                 }
1218                 $PHPCAS_CLIENT->logout(array (
1219                         "service" => $service
1220                 ));
1221                 // never reached
1222                 phpCAS :: traceEnd();
1223         }
1224
1225         /**
1226          * This method is used to logout from CAS. Halts by redirecting to the CAS server.
1227          * @param $url a URL that will be transmitted to the CAS server
1228          */
1229         function logoutWithUrl($url) {
1230                 global $PHPCAS_CLIENT;
1231                 phpCAS :: traceBegin();
1232                 if (!is_object($PHPCAS_CLIENT)) {
1233                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1234                 }
1235                 if (!is_string($url)) {
1236                         phpCAS :: error('type mismatched for parameter $url (should be `string\')');
1237                 }
1238                 $PHPCAS_CLIENT->logout(array (
1239                         "url" => $url
1240                 ));
1241                 // never reached
1242                 phpCAS :: traceEnd();
1243         }
1244
1245         /**
1246          * This method is used to logout from CAS. Halts by redirecting to the CAS server.
1247          * @param $service a URL that will be transmitted to the CAS server
1248          * @param $url a URL that will be transmitted to the CAS server
1249          */
1250         function logoutWithRedirectServiceAndUrl($service, $url) {
1251                 global $PHPCAS_CLIENT;
1252                 phpCAS :: traceBegin();
1253                 if (!is_object($PHPCAS_CLIENT)) {
1254                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1255                 }
1256                 if (!is_string($service)) {
1257                         phpCAS :: error('type mismatched for parameter $service (should be `string\')');
1258                 }
1259                 if (!is_string($url)) {
1260                         phpCAS :: error('type mismatched for parameter $url (should be `string\')');
1261                 }
1262                 $PHPCAS_CLIENT->logout(array (
1263                         "service" => $service,
1264                         "url" => $url
1265                 ));
1266                 // never reached
1267                 phpCAS :: traceEnd();
1268         }
1269
1270         /**
1271          * Set the fixed URL that will be used by the CAS server to transmit the PGT.
1272          * When this method is not called, a phpCAS script uses its own URL for the callback.
1273          *
1274          * @param $url the URL
1275          */
1276         function setFixedCallbackURL($url = '') {
1277                 global $PHPCAS_CLIENT;
1278                 phpCAS :: traceBegin();
1279                 if (!is_object($PHPCAS_CLIENT)) {
1280                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
1281                 }
1282                 if (!$PHPCAS_CLIENT->isProxy()) {
1283                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
1284                 }
1285                 if (gettype($url) != 'string') {
1286                         phpCAS :: error('type mismatched for parameter $url (should be `string\')');
1287                 }
1288                 $PHPCAS_CLIENT->setCallbackURL($url);
1289                 phpCAS :: traceEnd();
1290         }
1291
1292         /**
1293          * Set the fixed URL that will be set as the CAS service parameter. When this
1294          * method is not called, a phpCAS script uses its own URL.
1295          *
1296          * @param $url the URL
1297          */
1298         function setFixedServiceURL($url) {
1299                 global $PHPCAS_CLIENT;
1300                 phpCAS :: traceBegin();
1301                 if (!is_object($PHPCAS_CLIENT)) {
1302                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
1303                 }
1304                 if (gettype($url) != 'string') {
1305                         phpCAS :: error('type mismatched for parameter $url (should be `string\')');
1306                 }
1307                 $PHPCAS_CLIENT->setURL($url);
1308                 phpCAS :: traceEnd();
1309         }
1310
1311         /**
1312          * Get the URL that is set as the CAS service parameter.
1313          */
1314         function getServiceURL() {
1315                 global $PHPCAS_CLIENT;
1316                 if (!is_object($PHPCAS_CLIENT)) {
1317                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
1318                 }
1319                 return ($PHPCAS_CLIENT->getURL());
1320         }
1321
1322         /**
1323          * Retrieve a Proxy Ticket from the CAS server.
1324          */
1325         function retrievePT($target_service, & $err_code, & $err_msg) {
1326                 global $PHPCAS_CLIENT;
1327                 if (!is_object($PHPCAS_CLIENT)) {
1328                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::proxy()');
1329                 }
1330                 if (gettype($target_service) != 'string') {
1331                         phpCAS :: error('type mismatched for parameter $target_service(should be `string\')');
1332                 }
1333                 return ($PHPCAS_CLIENT->retrievePT($target_service, $err_code, $err_msg));
1334         }
1335
1336         /**
1337          * Set the certificate of the CAS server.
1338          *
1339          * @param $cert the PEM certificate
1340          */
1341         function setCasServerCert($cert) {
1342                 global $PHPCAS_CLIENT;
1343                 phpCAS :: traceBegin();
1344                 if (!is_object($PHPCAS_CLIENT)) {
1345                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1346                 }
1347                 if (gettype($cert) != 'string') {
1348                         phpCAS :: error('type mismatched for parameter $cert (should be `string\')');
1349                 }
1350                 $PHPCAS_CLIENT->setCasServerCert($cert);
1351                 phpCAS :: traceEnd();
1352         }
1353
1354         /**
1355          * Set the certificate of the CAS server CA.
1356          *
1357          * @param $cert the CA certificate
1358          */
1359         function setCasServerCACert($cert) {
1360                 global $PHPCAS_CLIENT;
1361                 phpCAS :: traceBegin();
1362                 if (!is_object($PHPCAS_CLIENT)) {
1363                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1364                 }
1365                 if (gettype($cert) != 'string') {
1366                         phpCAS :: error('type mismatched for parameter $cert (should be `string\')');
1367                 }
1368                 $PHPCAS_CLIENT->setCasServerCACert($cert);
1369                 phpCAS :: traceEnd();
1370         }
1371
1372         /**
1373          * Set no SSL validation for the CAS server.
1374          */
1375         function setNoCasServerValidation() {
1376                 global $PHPCAS_CLIENT;
1377                 phpCAS :: traceBegin();
1378                 if (!is_object($PHPCAS_CLIENT)) {
1379                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1380                 }
1381                 $PHPCAS_CLIENT->setNoCasServerValidation();
1382                 phpCAS :: traceEnd();
1383         }
1384
1385         /** @} */
1386
1387         /**
1388          * Change CURL options.
1389          * CURL is used to connect through HTTPS to CAS server
1390          * @param $key the option key
1391          * @param $value the value to set
1392          */
1393         function setExtraCurlOption($key, $value) {
1394                 global $PHPCAS_CLIENT;
1395                 phpCAS :: traceBegin();
1396                 if (!is_object($PHPCAS_CLIENT)) {
1397                         phpCAS :: error('this method should only be called after ' . __CLASS__ . '::client() or' . __CLASS__ . '::proxy()');
1398                 }
1399                 $PHPCAS_CLIENT->setExtraCurlOption($key, $value);
1400                 phpCAS :: traceEnd();
1401         }
1402
1403 }
1404
1405 // ########################################################################
1406 // DOCUMENTATION
1407 // ########################################################################
1408
1409 // ########################################################################
1410 //  MAIN PAGE
1411
1412 /**
1413  * @mainpage
1414  *
1415  * The following pages only show the source documentation.
1416  *
1417  */
1418
1419 // ########################################################################
1420 //  MODULES DEFINITION
1421
1422 /** @defgroup public User interface */
1423
1424 /** @defgroup publicInit Initialization
1425  *  @ingroup public */
1426
1427 /** @defgroup publicAuth Authentication
1428  *  @ingroup public */
1429
1430 /** @defgroup publicServices Access to external services
1431  *  @ingroup public */
1432
1433 /** @defgroup publicConfig Configuration
1434  *  @ingroup public */
1435
1436 /** @defgroup publicLang Internationalization
1437  *  @ingroup publicConfig */
1438
1439 /** @defgroup publicOutput HTML output
1440  *  @ingroup publicConfig */
1441
1442 /** @defgroup publicPGTStorage PGT storage
1443  *  @ingroup publicConfig */
1444
1445 /** @defgroup publicDebug Debugging
1446  *  @ingroup public */
1447
1448 /** @defgroup internal Implementation */
1449
1450 /** @defgroup internalAuthentication Authentication
1451  *  @ingroup internal */
1452
1453 /** @defgroup internalBasic CAS Basic client features (CAS 1.0, Service Tickets)
1454  *  @ingroup internal */
1455
1456 /** @defgroup internalProxy CAS Proxy features (CAS 2.0, Proxy Granting Tickets)
1457  *  @ingroup internal */
1458
1459 /** @defgroup internalPGTStorage PGT storage
1460  *  @ingroup internalProxy */
1461
1462 /** @defgroup internalPGTStorageFile PGT storage on the filesystem
1463  *  @ingroup internalPGTStorage */
1464
1465 /** @defgroup internalCallback Callback from the CAS server
1466  *  @ingroup internalProxy */
1467
1468 /** @defgroup internalProxied CAS proxied client features (CAS 2.0, Proxy Tickets)
1469  *  @ingroup internal */
1470
1471 /** @defgroup internalConfig Configuration
1472  *  @ingroup internal */
1473
1474 /** @defgroup internalOutput HTML output
1475  *  @ingroup internalConfig */
1476
1477 /** @defgroup internalLang Internationalization
1478  *  @ingroup internalConfig
1479  *
1480  * To add a new language:
1481  * - 1. define a new constant PHPCAS_LANG_XXXXXX in CAS/CAS.php
1482  * - 2. copy any file from CAS/languages to CAS/languages/XXXXXX.php
1483  * - 3. Make the translations
1484  */
1485
1486 /** @defgroup internalDebug Debugging
1487  *  @ingroup internal */
1488
1489 /** @defgroup internalMisc Miscellaneous
1490  *  @ingroup internal */
1491
1492 // ########################################################################
1493 //  EXAMPLES
1494
1495 /**
1496  * @example example_simple.php
1497  */
1498 /**
1499  * @example example_proxy.php
1500  */
1501 /**
1502  * @example example_proxy2.php
1503  */
1504 /**
1505  * @example example_lang.php
1506  */
1507 /**
1508  * @example example_html.php
1509  */
1510 /**
1511  * @example example_file.php
1512  */
1513 /**
1514  * @example example_db.php
1515  */
1516 /**
1517  * @example example_service.php
1518  */
1519 /**
1520  * @example example_session_proxy.php
1521  */
1522 /**
1523  * @example example_session_service.php
1524  */
1525 /**
1526  * @example example_gateway.php
1527  */
1528 /**
1529  * @example example_custom_urls.php
1530  */
1531 ?>