documentation/manual/en/module_specs/Zend_Auth_Adapter_Digest.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.auth.adapter.digest">
   4     <title>Digest Authentication</title>
   5
   6     <sect2 id="zend.auth.adapter.digest.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <ulink url="http://en.wikipedia.org/wiki/Digest_access_authentication">Digest
  11                 authentication</ulink> is a method of <acronym>HTTP</acronym> authentication that
  12             improves upon <ulink
  13                 url="http://en.wikipedia.org/wiki/Basic_authentication_scheme">Basic
  14                 authentication</ulink> by providing a way to authenticate without having to
  15             transmit the password in clear text across the network.
  16         </para>
  17
  18         <para>
  19             This adapter allows authentication against text files containing lines having the basic
  20             elements of Digest authentication:
  21         </para>
  22
  23         <itemizedlist>
  24             <listitem>
  25                 <para>
  26                     username, such as "<emphasis><filename>joe.user</filename></emphasis>"
  27                 </para>
  28             </listitem>
  29
  30             <listitem>
  31                 <para>
  32                     realm, such as "<emphasis>Administrative Area</emphasis>"
  33                 </para>
  34             </listitem>
  35
  36             <listitem>
  37                 <para>
  38                     <acronym>MD5</acronym> hash of the username, realm, and password, separated
  39                     by colons
  40                 </para>
  41             </listitem>
  42         </itemizedlist>
  43
  44         <para>
  45             The above elements are separated by colons, as in the following example (in which the
  46             password is "<emphasis>somePassword</emphasis>"):
  47         </para>
  48
  49         <programlisting language="txt"><![CDATA[
  50 someUser:Some Realm:fde17b91c3a510ecbaf7dbd37f59d4f8
  51 ]]></programlisting>
  52     </sect2>
  53
  54     <sect2 id="zend.auth.adapter.digest.specifics">
  55         <title>Specifics</title>
  56
  57         <para>
  58             The digest authentication adapter, <classname>Zend_Auth_Adapter_Digest</classname>,
  59             requires several input parameters:
  60         </para>
  61
  62         <itemizedlist>
  63             <listitem>
  64                 <para>
  65                     filename - Filename against which authentication queries are performed
  66                 </para>
  67             </listitem>
  68
  69             <listitem>
  70                 <para>
  71                     realm - Digest authentication realm
  72                 </para>
  73             </listitem>
  74
  75             <listitem>
  76                 <para>
  77                     username - Digest authentication user
  78                 </para>
  79             </listitem>
  80
  81             <listitem>
  82                 <para>
  83                     password - Password for the user of the realm
  84                 </para>
  85             </listitem>
  86         </itemizedlist>
  87
  88         <para>
  89             These parameters must be set prior to calling <methodname>authenticate()</methodname>.
  90         </para>
  91     </sect2>
  92
  93     <sect2 id="zend.auth.adapter.digest.identity">
  94         <title>Identity</title>
  95
  96         <para>
  97             The digest authentication adapter returns a <classname>Zend_Auth_Result</classname>
  98             object, which has been populated with the identity as an array having keys of
  99             <emphasis>realm</emphasis> and <emphasis>username</emphasis>. The respective array
 100             values associated with these keys correspond to the values set before
 101             <methodname>authenticate()</methodname> is called.
 102         </para>
 103
 104         <programlisting language="php"><![CDATA[
 105 $adapter = new Zend_Auth_Adapter_Digest($filename,
 106                                         $realm,
 107                                         $username,
 108                                         $password);
 109
 110 $result = $adapter->authenticate();
 111
 112 $identity = $result->getIdentity();
 113
 114 print_r($identity);
 115
 116 /*
 117 Array
 118 (
 119     [realm] => Some Realm
 120     [username] => someUser
 121 )
 122 */
 123 ]]></programlisting>
 124     </sect2>
 125 </sect1>
 126 <!--
 127 vim:se ts=4 sw=4 et:
 128 -->