<?xml version="1.0" encoding="utf-8"?>
 <reference id="ref.mhash">
  <title>Mhash Functions</title>
  <titleabbrev>mhash</titleabbrev>
  
  <partintro>
   <para>
    These functions are intended to work with <ulink
    url="&url.mhash;">mhash</ulink>.</para>
   <para>
    This is an interface to the mhash library. mhash supports a wide
    variety of hash algorithms such as MD5, SHA1, GOST, and many
    others.
   </para>
   <para>
    To use it, download the mhash distribution from <ulink
    url="&url.mhash;">its web site</ulink> and follow the included
    installation instructions. You need to compile PHP with the
    <option role="configure">--with-mhash</option> parameter to enable
    this extension.
   </para>
   <para>
    Mhash can be used to create checksums, message digests, message
    authentication codes, and more.
   </para>
   <para>
    <example>
     <title>Compute the MD5 digest and hmac and print it out as hex</title>
     <programlisting role="php">
&lt;?php
$input = "what do ya want for nothing?";
$hash = mhash (MHASH_MD5, $input);
print "The hash is ".bin2hex ($hash)."\n&lt;br>";
$hash = mhash (MHASH_MD5, $input, "Jefe");
print "The hmac is ".bin2hex ($hash)."\n&lt;br>";
?&gt;
     </programlisting>
    </example>
    This will produce:
    <programlisting>
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 TIGER you use the PHP constant MHASH_TIGER.
   </para>
   <para>
    Here is a list of hashes which are currently supported by mhash. If a
    hash is not listed here, but is listed by mhash as supported, you can
    safely assume that this documentation is outdated.
    <itemizedlist>
     <listitem>
      <simpara>
       MHASH_MD5
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       MHASH_SHA1
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       MHASH_HAVAL256
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       MHASH_HAVAL192
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       MHASH_HAVAL160
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       MHASH_HAVAL128
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       MHASH_RIPEMD160
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       MHASH_GOST
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       MHASH_TIGER
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       MHASH_CRC32
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       MHASH_CRC32B
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
  </partintro>
  
  <refentry id="function.mhash-get-hash-name">
   <refnamediv>
    <refname>mhash_get_hash_name</refname>
    <refpurpose>Get the name of the specified hash</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mhash_get_hash_name</methodname>
      <methodparam><type>int</type><parameter>hash</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>mhash_get_hash_name</function> is used to get the name
     of the specified hash.
    </para>
    <para>
     <function>mhash_get_hash_name</function> takes the hash id as an
     argument and returns the name of the hash or &false;, if the hash
     does not exist.
    </para>
    <para>
     <example>
      <title><function>mhash_get_hash_name</function> Example</title>
      <programlisting>
&lt;?php
$hash = MHASH_MD5;

print mhash_get_hash_name ($hash);
?&gt;
      </programlisting>
     </example>
     The above example will print out:
     <programlisting>
MD5
     </programlisting>
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.mhash-get-block-size">
   <refnamediv>
    <refname>mhash_get_block_size</refname>
    <refpurpose>Get the block size of the specified hash</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mhash_get_block_size</methodname>
      <methodparam><type>int</type><parameter>hash</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>mhash_get_block_size</function> is used to get the size
     of a block of the specified <parameter>hash</parameter>.
    </para>
    <para>
     <function>mhash_get_block_size</function> takes one argument, the
     <parameter>hash</parameter> and returns the size in bytes or
     &false;, if the <parameter>hash</parameter> does not exist.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.mhash-count">
   <refnamediv>
    <refname>mhash_count</refname>
    <refpurpose>Get the highest available hash id</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mhash_count</methodname>
      <void/>
     </methodsynopsis>
    <para>
     <function>mhash_count</function> returns the highest available hash
     id. Hashes are numbered from 0 to this hash id.
    </para>
    <para>
     <example>
      <title>Traversing all hashes</title>
      <programlisting role="php">
&lt;?php

$nr = mhash_count();

for ($i = 0; $i &lt;= $nr; $i++) {
    echo sprintf ("The blocksize of %s is %d\n", 
        mhash_get_hash_name ($i),
        mhash_get_block_size ($i));
}
?&gt;
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>
    
  <refentry id="function.mhash">
   <refnamediv>
    <refname>mhash</refname>
    <refpurpose>Compute hash</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mhash</methodname>
      <methodparam><type>int</type><parameter>hash</parameter></methodparam>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
      <methodparam><type>string</type><parameter>[ key ]</parameter></methodparam>
     </methodsynopsis>
    <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). 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. In case of an error returns &false;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mhash-keygen-s2k">
   <refnamediv>
    <refname>mhash_keygen_s2k</refname>
    <refpurpose>Generates a key</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mhash_keygen_s2k</methodname>
      <methodparam><type>int</type><parameter>hash</parameter></methodparam>
      <methodparam><type>string</type><parameter>password</parameter></methodparam>
      <methodparam><type>string</type><parameter>salt</parameter></methodparam>
      <methodparam><type>int</type><parameter>bytes</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>mhash_keygen_s2k</function> generates a key that is
     <parameter>bytes</parameter> long, from a user given password.
     This is the Salted S2K algorithm as specified in the OpenPGP
     document (RFC 2440). That algorithm will use the specified
     <parameter>hash</parameter> algorithm to create the key.
     The <parameter>salt</parameter> must be different and random
     enough for every key you generate in order to create different keys.
     That salt must be known when you check the keys, thus it is
     a good idea to append the key to it. Salt has a fixed length
     of 8 bytes and will be padded with zeros if you supply less bytes.
     Keep in mind that user supplied passwords are not really suitable
     to be used as keys in cryptographic algorithms, since users normally
     choose keys they can write on keyboard. These passwords use
     only 6 to 7 bits per character (or less). It is highly recommended
     to use some kind of tranformation (like this function) to the user 
     supplied key.
    </para>
   </refsect1>
  </refentry>

 </reference> 

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->