From a4f5a950db6e89d67bb6533382050bff447617c0 Mon Sep 17 00:00:00 2001
From: Nikos Mavroyanopoulos <nmav@php.net>
Date: Tue, 17 Oct 2000 19:44:10 +0000
Subject: [PATCH] Updated the mhash documentation for the HMAC functionality.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@34014 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/mhash.xml | 56 +++++++++++++++++++++++++++------------------
 1 file changed, 34 insertions(+), 22 deletions(-)

diff --git a/functions/mhash.xml b/functions/mhash.xml
index 24d3f5e621..1514eec12f 100644
--- a/functions/mhash.xml
+++ b/functions/mhash.xml
@@ -19,29 +19,31 @@
     this extension.
    </para>
    <para>
-    Mhash can be used to create checksums, message digests, and
-    more.
+    Mhash can be used to create checksums, message digests, message
+    authentication codes, and more.
    </para>
    <para>
     <example>
-     <title>Compute the SHA1 key and print it out as hex</title>
+     <title>Compute the MD5 digest and hmac and print it out as hex</title>
      <programlisting role="php">
 &lt;?php
-$input = "Let us meet at 9 o' clock at the secret place.";
-$hash = mhash (MHASH_SHA1, $input);
-
-print "The hash is ".bin2hex ($hash)."\n";
+$input = "what do ya want for nothing?";
+$hash = mhash (MHASH_MD5, $input);
+print "The hash is ".bin2hex ($hash)."\n<br>";
+$hash = mhash (MHASH_MD5, $input, "Jefe");
+print "The hmac is ".bin2hex ($hash)."\n<br>";
 ?&gt;
      </programlisting>
     </example>
     This will produce:
     <programlisting>
-The hash is d3b85d710d8f6e4e5efd4d5e67d041f9cecedafe
+The hash is d03cb659cbf9192dcd066272249f8412 
+The hmac is 750c783e6ab0b503eaa86e310a5db738 
     </programlisting>
     For a complete list of supported hashes, refer to the
     documentation of mhash. The general rule is that you can access
     the hash algorithm from PHP with MHASH_HASHNAME. For example, to
-    access HAVAL you use the PHP constant MHASH_HAVAL.
+    access TIGER you use the PHP constant MHASH_TIGER.
    </para>
    <para>
     Here is a list of hashes which are currently supported by mhash. If a
@@ -60,7 +62,22 @@ The hash is d3b85d710d8f6e4e5efd4d5e67d041f9cecedafe
      </listitem>
      <listitem>
       <simpara>
-       MHASH_HAVAL
+       MHASH_HAVAL256
+      </simpara>
+     </listitem>
+     <listitem>
+      <simpara>
+       MHASH_HAVAL192
+      </simpara>
+     </listitem>
+     <listitem>
+      <simpara>
+       MHASH_HAVAL160
+      </simpara>
+     </listitem>
+     <listitem>
+      <simpara>
+       MHASH_HAVAL128
       </simpara>
      </listitem>
      <listitem>
@@ -70,12 +87,7 @@ The hash is d3b85d710d8f6e4e5efd4d5e67d041f9cecedafe
      </listitem>
      <listitem>
       <simpara>
-       MHASH_RIPEMD128
-      </simpara>
-     </listitem>
-     <listitem>
-      <simpara>
-       MHASH_SNEFRU
+       MHASH_GOST
       </simpara>
      </listitem>
      <listitem>
@@ -83,11 +95,6 @@ The hash is d3b85d710d8f6e4e5efd4d5e67d041f9cecedafe
        MHASH_TIGER
       </simpara>
      </listitem>
-     <listitem>
-      <simpara>
-       MHASH_GOST
-      </simpara>
-     </listitem>
      <listitem>
       <simpara>
        MHASH_CRC32
@@ -217,12 +224,17 @@ for ($i = 0; $i &lt;= $nr; $i++) {
       <funcdef>string <function>mhash</function></funcdef>
       <paramdef>int <parameter>hash</parameter></paramdef>
       <paramdef>string <parameter>data</parameter></paramdef>
+      <paramdef>string <parameter>[ key ]</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      <function>Mhash</function> applies a hash function specified by
      <parameter>hash</parameter> to the <parameter>data</parameter> and
-     returns the resulting hash (also called digest).
+     returns the resulting hash (also called digest). If the <parameter> key</parameter>
+     is specified it will return the resulting HMAC. HMAC is keyed hashing
+     for message authentication, or simply a message digest that depends on 
+     the specified key. Not all algorithms supported in mhash can be used in 
+     HMAC mode and will return an error.
     </para>
    </refsect1>
   </refentry>