From 3671b425c901ec57a48504b23aa32c3d03c59eab Mon Sep 17 00:00:00 2001
From: Nuno Lopes <nlopess@php.net>
Date: Sun, 10 Apr 2005 09:56:39 +0000
Subject: [PATCH] document the HTTP Digest auth update the PHP_AUTH_* vars to
 reflect the IIS change

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@184058 c90b9560-bf6c-de11-be94-00142212c4b1
---
 appendices/reserved.xml | 24 +++++++++++++----
 features/http-auth.xml  | 59 +++++++++++++++++++++++++++++++++++++----
 2 files changed, 73 insertions(+), 10 deletions(-)

diff --git a/appendices/reserved.xml b/appendices/reserved.xml
index bc687ed43c..10b07a1f07 100755
--- a/appendices/reserved.xml
+++ b/appendices/reserved.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.54 $ -->
+<!-- $Revision: 1.55 $ -->
 
  <appendix id="reserved">
   <title>List of Reserved Words</title>
@@ -685,12 +685,25 @@
        </listitem>
       </varlistentry>
 
+      <varlistentry>
+       <term>'<varname>PHP_AUTH_DIGEST</varname>'</term>
+       <listitem>
+        <simpara>
+         When running under Apache as module doing Digest HTTP authentication
+         this variable is set to the 'Authorization' header sent by the
+         client (which you should then use to make the appropriate
+         validation).
+        </simpara>
+       </listitem>
+      </varlistentry>
+
       <varlistentry>
        <term>'<varname>PHP_AUTH_USER</varname>'</term>
        <listitem>
         <simpara>
-         When running under Apache as module doing HTTP authentication this
-         variable is set to the username provided by the user.
+         When running under Apache or IIS (ISAPI on PHP 5) as module doing
+         HTTP authentication this variable is set to the username provided by
+         the user.
         </simpara>
        </listitem>
       </varlistentry>
@@ -699,8 +712,9 @@
        <term>'<varname>PHP_AUTH_PW</varname>'</term>
        <listitem>
         <simpara>
-         When running under Apache as module doing HTTP authentication this
-         variable is set to the password provided by the user.
+         When running under Apache or IIS (ISAPI on PHP 5) as module doing
+         HTTP authentication this variable is set to the password provided by
+         the user.
         </simpara>
        </listitem>
       </varlistentry>
diff --git a/features/http-auth.xml b/features/http-auth.xml
index 561d4b6fce..88c93e8aa8 100644
--- a/features/http-auth.xml
+++ b/features/http-auth.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.41 $ -->
+<!-- $Revision: 1.42 $ -->
  <chapter id="features.http-auth">
   <title>HTTP authentication with PHP</title>
 
@@ -16,9 +16,9 @@
    and <varname>AUTH_TYPE</varname> set to the user name, password and 
    authentication type respectively.  These predefined variables are found 
    in the <link linkend="reserved.variables.server">$_SERVER</link> and 
-   <varname>$HTTP_SERVER_VARS</varname> arrays.  Only "Basic" authentication 
-   is supported. See the <function>header</function> function for more 
-   information.
+   <varname>$HTTP_SERVER_VARS</varname> arrays. Both "Basic" and "Digest"
+   (since PHP 5.1.0) authentication methods are supported. See the
+   <function>header</function> function for more information.
   </simpara>
 
   <note>
@@ -37,7 +37,7 @@
   </para>
   <para>
    <example>
-    <title>HTTP Authentication example</title>
+    <title>Basic HTTP Authentication example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -50,6 +50,55 @@
     echo "<p>Hello {$_SERVER['PHP_AUTH_USER']}.</p>";
     echo "<p>You entered {$_SERVER['PHP_AUTH_PW']} as your password.</p>";
   }
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+
+  <para>
+   <example>
+    <title>Digest HTTP Authentication example</title>
+    <para>
+     This example shows you how to implement a simple Digest HTTP
+     authentication script. For more information read the <ulink
+      url="&url.rfc;2617">RFC 2617</ulink>.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$realm = 'Restricted area';
+
+//user => password
+$users = array('admin' => 'mypass', 'guest' => 'guest');
+
+
+if (!isset($_SERVER['PHP_AUTH_DIGEST'])) {
+    header('HTTP/1.1 401 Unauthorized');
+    header('WWW-Authenticate: Digest realm="'.$realm.
+           '" qop="auth" nonce="'.uniqid().'" opaque="'.md5($realm).'"');
+
+    die('Text to send if user hits Cancel button');
+}
+
+// analise the PHP_AUTH_DIGEST variable
+preg_match('/username="(?P<username>.*)",\s*realm="(?P<realm>.*)",\s*nonce="(?P<nonce>.*)",\s*uri="(?P<uri>.*)",\s*response="(?P<response>.*)",\s*opaque="(?P<opaque>.*)",\s*qop=(?P<qop>.*),\s*nc=(?P<nc>.*),\s*cnonce="(?P<cnonce>.*)"/', $_SERVER['PHP_AUTH_DIGEST'], $digest);
+
+if (!isset($users[$digest['username']]))
+    die('Username not valid!');
+
+
+// generate the valid response
+$A1 = md5($digest['username'] . ':' . $realm . ':' . $users[$digest['username']]);
+$A2 = md5($_SERVER['REQUEST_METHOD'].':'.$digest['uri']);
+$valid_response = md5($A1.':'.$digest['nonce'].':'.$digest['nc'].':'.$digest['cnonce'].':'.$digest['qop'].':'.$A2);
+
+if ($digest['response'] != $valid_response)
+    die('Wrong Credentials!');
+
+// ok, valid username & password
+echo 'Your are logged in as: ' . $digest['username'];
+
 ?>
 ]]>
     </programlisting>