library/classes/smtp/sasl.php

   1 <?php
   2 /*
   3  * sasl.php
   4  *
   5  * @(#) $Id$
   6  *
   7  */
   8
   9 define("SASL_INTERACT", 2);
  10 define("SASL_CONTINUE", 1);
  11 define("SASL_OK",       0);
  12 define("SASL_FAIL",    -1);
  13 define("SASL_NOMECH",  -4);
  14
  15 class sasl_interact_class
  16 {
  17         var $id;
  18         var $challenge;
  19         var $prompt;
  20         var $default_result;
  21         var $result;
  22 };
  23
  24 /*
  25 {metadocument}<?xml version="1.0" encoding="ISO-8859-1" ?>
  26 <class>
  27
  28         <package>net.manuellemos.sasl</package>
  29
  30         <version>@(#) $Id$</version>
  31         <copyright>Copyright © (C) Manuel Lemos 2004</copyright>
  32         <title>Simple Authentication and Security Layer client</title>
  33         <author>Manuel Lemos</author>
  34         <authoraddress>mlemos-at-acm.org</authoraddress>
  35
  36         <documentation>
  37                 <idiom>en</idiom>
  38                 <purpose>Provide a common interface to plug-in driver classes that
  39                         implement different mechanisms for authentication used by clients of
  40                         standard protocols like SMTP, POP3, IMAP, HTTP, etc.. Currently the
  41                         supported authentication mechanisms are: <tt>PLAIN</tt>,
  42                         <tt>LOGIN</tt>, <tt>CRAM-MD5</tt>, <tt>Digest</tt> and <tt>NTML</tt>
  43                         (Windows or Samba).</purpose>
  44                 <usage>.</usage>
  45         </documentation>
  46
  47 {/metadocument}
  48 */
  49
  50 class sasl_client_class
  51 {
  52         /* Public variables */
  53
  54 /*
  55 {metadocument}
  56         <variable>
  57                 <name>error</name>
  58                 <type>STRING</type>
  59                 <value></value>
  60                 <documentation>
  61                         <purpose>Store the message that is returned when an error
  62                                 occurs.</purpose>
  63                         <usage>Check this variable to understand what happened when a call to
  64                                 any of the class functions has failed.<paragraphbreak />
  65                                 This class uses cumulative error handling. This means that if one
  66                                 class functions that may fail is called and this variable was
  67                                 already set to an error message due to a failure in a previous call
  68                                 to the same or other function, the function will also fail and does
  69                                 not do anything.<paragraphbreak />
  70                                 This allows programs using this class to safely call several
  71                                 functions that may fail and only check the failure condition after
  72                                 the last function call.<paragraphbreak />
  73                                 Just set this variable to an empty string to clear the error
  74                                 condition.</usage>
  75                 </documentation>
  76         </variable>
  77 {/metadocument}
  78 */
  79         var $error='';
  80
  81 /*
  82 {metadocument}
  83         <variable>
  84                 <name>mechanism</name>
  85                 <type>STRING</type>
  86                 <value></value>
  87                 <documentation>
  88                         <purpose>Store the name of the mechanism that was selected during the
  89                                 call to the <functionlink>Start</functionlink> function.</purpose>
  90                         <usage>You can access this variable but do not change it.</usage>
  91                 </documentation>
  92         </variable>
  93 {/metadocument}
  94 */
  95         var $mechanism='';
  96
  97 /*
  98 {metadocument}
  99         <variable>
 100                 <name>encode_response</name>
 101                 <type>BOOLEAN</type>
 102                 <value>1</value>
 103                 <documentation>
 104                         <purpose>Let the drivers inform the applications whether responses
 105                                 need to be encoded.</purpose>
 106                         <usage>Applications should check this variable before sending
 107                                 authentication responses to the server to determine if the
 108                                 responses need to be encoded, eventually with base64 algorithm.</usage>
 109                 </documentation>
 110         </variable>
 111 {/metadocument}
 112 */
 113         var $encode_response=1;
 114
 115         /* Private variables */
 116
 117         var $driver;
 118         var $drivers=array(
 119                 "Digest"   => array("digest_sasl_client_class",   "digest_sasl_client.php"   ),
 120                 "CRAM-MD5" => array("cram_md5_sasl_client_class", "cram_md5_sasl_client.php" ),
 121                 "LOGIN"    => array("login_sasl_client_class",    "login_sasl_client.php"    ),
 122                 "NTLM"     => array("ntlm_sasl_client_class",     "ntlm_sasl_client.php"     ),
 123                 "PLAIN"    => array("plain_sasl_client_class",    "plain_sasl_client.php"    ),
 124                 "Basic"    => array("basic_sasl_client_class",    "basic_sasl_client.php"    )
 125         );
 126         var $credentials=array();
 127
 128         /* Public functions */
 129
 130 /*
 131 {metadocument}
 132         <function>
 133                 <name>SetCredential</name>
 134                 <type>VOID</type>
 135                 <documentation>
 136                         <purpose>Store the value of a credential that may be used by any of
 137                          the supported mechanisms to process the authentication messages and
 138                          responses.</purpose>
 139                         <usage>Call this function before starting the authentication dialog
 140                                 to pass all the credential values that be needed to use the type
 141                                 of authentication that the applications may need.</usage>
 142                         <returnvalue>.</returnvalue>
 143                 </documentation>
 144                 <argument>
 145                         <name>key</name>
 146                         <type>STRING</type>
 147                         <documentation>
 148                                 <purpose>Specify the name of the credential key.</purpose>
 149                         </documentation>
 150                 </argument>
 151                 <argument>
 152                         <name>value</name>
 153                         <type>STRING</type>
 154                         <documentation>
 155                                 <purpose>Specify the value for the credential.</purpose>
 156                         </documentation>
 157                 </argument>
 158                 <do>
 159 {/metadocument}
 160 */
 161         Function SetCredential($key,$value)
 162         {
 163                 $this->credentials[$key]=$value;
 164         }
 165 /*
 166 {metadocument}
 167                 </do>
 168         </function>
 169 {/metadocument}
 170 */
 171
 172 /*
 173 {metadocument}
 174         <function>
 175                 <name>GetCredentials</name>
 176                 <type>INTEGER</type>
 177                 <documentation>
 178                         <purpose>Retrieve the values of one or more credentials to be used by
 179                                 the authentication mechanism classes.</purpose>
 180                         <usage>This is meant to be used by authentication mechanism driver
 181                                 classes to retrieve the credentials that may be neede.</usage>
 182                         <returnvalue>The function may return <tt>SASL_CONTINUE</tt> if it
 183                                 succeeded, or <tt>SASL_NOMECH</tt> if it was not possible to
 184                                 retrieve one of the requested credentials.</returnvalue>
 185                 </documentation>
 186                 <argument>
 187                         <name>credentials</name>
 188                         <type>HASH</type>
 189                         <documentation>
 190                                 <purpose>Reference to an associative array variable with all the
 191                                         credentials that are being requested. The function initializes
 192                                         this associative array values.</purpose>
 193                         </documentation>
 194                 </argument>
 195                 <argument>
 196                         <name>defaults</name>
 197                         <type>HASH</type>
 198                         <documentation>
 199                                 <purpose>Associative arrays with default values for credentials
 200                                         that may have not been defined.</purpose>
 201                         </documentation>
 202                 </argument>
 203                 <argument>
 204                         <name>interactions</name>
 205                         <type>ARRAY</type>
 206                         <documentation>
 207                                 <purpose>Not yet in use. It is meant to provide context
 208                                         information to retrieve credentials that may be obtained
 209                                         interacting with the user.</purpose>
 210                         </documentation>
 211                 </argument>
 212                 <do>
 213 {/metadocument}
 214 */
 215         Function GetCredentials(&$credentials,$defaults,&$interactions)
 216         {
 217                 Reset($credentials);
 218                 $end=(GetType($key=Key($credentials))!="string");
 219                 for(;!$end;)
 220                 {
 221                         if(!IsSet($this->credentials[$key]))
 222                         {
 223                                 if(IsSet($defaults[$key]))
 224                                         $credentials[$key]=$defaults[$key];
 225                                 else
 226                                 {
 227                                         $this->error="the requested credential ".$key." is not defined";
 228                                         return(SASL_NOMECH);
 229                                 }
 230                         }
 231                         else
 232                                 $credentials[$key]=$this->credentials[$key];
 233                         Next($credentials);
 234                         $end=(GetType($key=Key($credentials))!="string");
 235                 }
 236                 return(SASL_CONTINUE);
 237         }
 238 /*
 239 {metadocument}
 240                 </do>
 241         </function>
 242 {/metadocument}
 243 */
 244
 245 /*
 246 {metadocument}
 247         <function>
 248                 <name>Start</name>
 249                 <type>INTEGER</type>
 250                 <documentation>
 251                         <purpose>Process the initial authentication step initializing the
 252                                 driver class that implements the first of the list of requested
 253                                 mechanisms that is supported by this SASL client library
 254                                 implementation.</purpose>
 255                         <usage>Call this function specifying a list of mechanisms that the
 256                                 server supports. If the <argumentlink>
 257                                         <argument>message</argument>
 258                                         <function>Start</function>
 259                                 </argumentlink> argument returns a string, it should be sent to
 260                                 the server as initial message. Check the
 261                                 <variablelink>encode_response</variablelink> variable to determine
 262                                 whether the initial message needs to be encoded, eventually with
 263                                 base64 algorithm, before it is sent to the server.</usage>
 264                         <returnvalue>The function may return <tt>SASL_CONTINUE</tt> if it
 265                                 could start one of the requested authentication mechanisms. It
 266                                 may return <tt>SASL_NOMECH</tt> if it was not possible to start
 267                                 any of the requested mechanisms. It returns <tt>SASL_FAIL</tt> or
 268                                 other value in case of error.</returnvalue>
 269                 </documentation>
 270                 <argument>
 271                         <name>mechanisms</name>
 272                         <type>ARRAY</type>
 273                         <inout />
 274                         <documentation>
 275                                 <purpose>Define the list of names of authentication mechanisms
 276                                         supported by the that should be tried.</purpose>
 277                         </documentation>
 278                 </argument>
 279                 <argument>
 280                         <name>message</name>
 281                         <type>STRING</type>
 282                         <out />
 283                         <documentation>
 284                                 <purpose>Return the initial message that should be sent to the
 285                                         server to start the authentication dialog. If this value is
 286                                         undefined, no message should be sent to the server.</purpose>
 287                         </documentation>
 288                 </argument>
 289                 <argument>
 290                         <name>interactions</name>
 291                         <type>ARRAY</type>
 292                         <documentation>
 293                                 <purpose>Not yet in use. It is meant to provide context
 294                                         information to interact with the end user.</purpose>
 295                         </documentation>
 296                 </argument>
 297                 <do>
 298 {/metadocument}
 299 */
 300         Function Start($mechanisms, &$message, &$interactions)
 301         {
 302                 if(strlen($this->error))
 303                         return(SASL_FAIL);
 304                 if(IsSet($this->driver))
 305                         return($this->driver->Start($this,$message,$interactions));
 306                 $no_mechanism_error="";
 307                 for($m=0;$m<count($mechanisms);$m++)
 308                 {
 309                         $mechanism=$mechanisms[$m];
 310                         if(IsSet($this->drivers[$mechanism]))
 311                         {
 312                                 if(!class_exists($this->drivers[$mechanism][0]))
 313                                         require(dirname(__FILE__)."/".$this->drivers[$mechanism][1]);
 314                                 $this->driver=new $this->drivers[$mechanism][0];
 315                                 if($this->driver->Initialize($this))
 316                                 {
 317                                         $this->encode_response=1;
 318                                         $status=$this->driver->Start($this,$message,$interactions);
 319                                         switch($status)
 320                                         {
 321                                                 case SASL_NOMECH:
 322                                                         Unset($this->driver);
 323                                                         if(strlen($no_mechanism_error)==0)
 324                                                                 $no_mechanism_error=$this->error;
 325                                                         $this->error="";
 326                                                         break;
 327                                                 case SASL_CONTINUE:
 328                                                         $this->mechanism=$mechanism;
 329                                                         return($status);
 330                                                 default:
 331                                                         Unset($this->driver);
 332                                                         $this->error="";
 333                                                         return($status);
 334                                         }
 335                                 }
 336                                 else
 337                                 {
 338                                         Unset($this->driver);
 339                                         if(strlen($no_mechanism_error)==0)
 340                                                 $no_mechanism_error=$this->error;
 341                                         $this->error="";
 342                                 }
 343                         }
 344                 }
 345                 $this->error=(strlen($no_mechanism_error) ? $no_mechanism_error : "it was not requested any of the authentication mechanisms that are supported");
 346                 return(SASL_NOMECH);
 347         }
 348 /*
 349 {metadocument}
 350                 </do>
 351         </function>
 352 {/metadocument}
 353 */
 354
 355 /*
 356 {metadocument}
 357         <function>
 358                 <name>Step</name>
 359                 <type>INTEGER</type>
 360                 <documentation>
 361                         <purpose>Process the authentication steps after the initial step,
 362                                 until the authetication iteration dialog is complete.</purpose>
 363                         <usage>Call this function iteratively after a successful initial
 364                                 step calling the <functionlink>Start</functionlink> function.</usage>
 365                         <returnvalue>The function returns <tt>SASL_CONTINUE</tt> if step was
 366                                 processed successfully, or returns <tt>SASL_FAIL</tt> in case of
 367                                 error.</returnvalue>
 368                 </documentation>
 369                 <argument>
 370                         <name>response</name>
 371                         <type>STRING</type>
 372                         <in />
 373                         <documentation>
 374                                 <purpose>Pass the response returned by the server to the previous
 375                                         step.</purpose>
 376                         </documentation>
 377                 </argument>
 378                 <argument>
 379                         <name>message</name>
 380                         <type>STRING</type>
 381                         <out />
 382                         <documentation>
 383                                 <purpose>Return the message that should be sent to the server to
 384                                         continue the authentication dialog. If this value is undefined,
 385                                         no message should be sent to the server.</purpose>
 386                         </documentation>
 387                 </argument>
 388                 <argument>
 389                         <name>interactions</name>
 390                         <type>ARRAY</type>
 391                         <documentation>
 392                                 <purpose>Not yet in use. It is meant to provide context
 393                                         information to interact with the end user.</purpose>
 394                         </documentation>
 395                 </argument>
 396                 <do>
 397 {/metadocument}
 398 */
 399         Function Step($response, &$message, &$interactions)
 400         {
 401                 if(strlen($this->error))
 402                         return(SASL_FAIL);
 403                 return($this->driver->Step($this,$response,$message,$interactions));
 404         }
 405 /*
 406 {metadocument}
 407                 </do>
 408         </function>
 409 {/metadocument}
 410 */
 411
 412 };
 413
 414 /*
 415
 416 {metadocument}
 417 </class>
 418 {/metadocument}
 419
 420 */
 421
 422 ?>