<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
 <reference id="ref.mhash">
  <title>Mhash Functions</title>
  <titleabbrev>mhash</titleabbrev>
  
  <partintro>
   <para>
    Estas funes tem a inteno de funcionar com
    <ulink url="&url.mhash;">mhash</ulink>.</para>
   <para>
    Esta  uma interface para a biblioteca mhash. mhash suporta
    uma grande variedade de algoritmos hash como MD5, SHA1, GOST e
    vrios outros.
   </para>
   <para>
    Para usalas, faa o download da distribuio mhash do <ulink
    url="&url.mhash;">web site deles</ulink> e siga as instrues
    de instalao inclusas. Voc precisar compilar o PHP com o
    parametro <option role="configure">--with-mhash</option> para
    habilitar esta extenso.
   </para>
   <para>
    Mhash pode ser usado para criar checksums, message digests, cdigos
    de autenticao e mais.
   </para>
   <para>
    <example>
     <title>Computar o MD5 digest e hmac e imprimir como hex</title>
     <programlisting role="php">
<![CDATA[
<?php
$input = "o que voc quer por nada?";
$hash = mhash (MHASH_MD5, $input);
print "A hash  ".bin2hex ($hash)."\n&lt;br>";
$hash = mhash (MHASH_MD5, $input, "Jefe");
print "A hmac  ".bin2hex ($hash)."\n&lt;br>";
?>
]]>
     </programlisting>
     <para>
      Este cdigo ir produzir:
      <screen>
<![CDATA[
A hash  d03cb659cbf9192dcd066272249f8412 
A hmac  750c783e6ab0b503eaa86e310a5db738 
]]>
      </screen>
     </para>
    </example>
    Para uma lista completa de hashes suportadas, refira-se para a
    documentao do mhash. A regra geral  que voc pode acessar o
    algoritmo hash do PHP com MHASH_HASHNAME. Por exemplo, para
    accessar TIGER se usa a constante do PHP MHASH_TIGER.
   </para>
   <para>
    Aqui est a lista de hashes que so atualmente suportadas por mhash.
    Se uma hash no est listada aqui, mas  listada por mhash como
    suportada, voc pode com seguranca presumir que esta documentao est
    desatualizada.
    <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>Ler o nome da hash especificada</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descrio</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>  usada para obter o nome
     da hash especificada.
    </para>
    <para>
     <function>mhash_get_hash_name</function> recebe a id da hash como um
     argumento e retorna o nome da hash ou &false;, se a hash no existe.
    </para>
    <para>
     <example>
      <title>Exemplo do <function>mhash_get_hash_name</function></title>
      <programlisting>
<![CDATA[
<?php
$hash = MHASH_MD5;

print mhash_get_hash_name ($hash);
?>
]]>
      </programlisting>
      <para>
       O exemplo acima ir imprimir:
       <screen>
<![CDATA[
      MD5
]]>
       </screen>
      </para>
     </example>
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.mhash-get-block-size">
   <refnamediv>
    <refname>mhash_get_block_size</refname>
    <refpurpose>Ler o tamanho do bloco da hash especficada</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descrio</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>  usada para obter o
     tamanho de um blobo da <parameter>hash</parameter> especficada.
    </para>
    <para>
     <function>mhash_get_block_size</function> recebe um argumento, a
     <parameter>hash</parameter> e retorna o tamanho em bytes ou
     &false;, se o parametro <parameter>hash</parameter> no existe.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.mhash-count">
   <refnamediv>
    <refname>mhash_count</refname>
    <refpurpose>Ler o mais alto hash id disponvel</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descrio</title>
     <methodsynopsis>
      <type>int</type><methodname>mhash_count</methodname>
      <void/>
     </methodsynopsis>
    <para>
     <function>mhash_count</function> retorna a mais alta hash id disponvel.
     As hashes so numeradas de 0 at esta hash id.
    </para>
    <para>
     <example>
      <title>Listando todas as hashes</title>
      <programlisting role="php">
<![CDATA[
<?php

$nr = mhash_count();

for ($i = 0; $i <= $nr; $i++) {
    echo sprintf ("O tamanho do bloco de %s  %d\n", 
        mhash_get_hash_name ($i),
        mhash_get_block_size ($i));
}
?>
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>
    
  <refentry id="function.mhash">
   <refnamediv>
    <refname>mhash</refname>
    <refpurpose>Computar a hash</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descrio</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> applica a funo hash especificada por
     <parameter>hash</parameter> para o parametro <parameter>data</parameter>
     e retorna a hash resultante (tambm chamada de digest). Se a
     <parameter>key</parameter> for especificada a funo ir retornar o
     HMAC resultante. HMAC  o hashing com chave (keyed) para autenticaes
     de mensagens, ou simplesmente um digest de mensagens que depende na
     chave (key) especficada. Nem todos os algortmos suportados em mhash
     podem ser usados em modo HMAC. Em caso de erro retorna &false;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mhash-keygen-s2k">
   <refnamediv>
    <refname>mhash_keygen_s2k</refname>
    <refpurpose>Gerar uma chave</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descrio</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> gera um chave que tem
     <parameter>bytes</parameter> de comprimento, apartir de uma
     senha (password) do usurio. Este  o algoritmo Salted S2K
     como especificado no documento OpenPGP (RFC 2440). Este 
     algoritmo usar o algoritmo <parameter>hash</parameter> 
     para criar a chave. O <parameter>salt</parameter> deve ser
     diferente e aleatrio o suficiente para que cada chave que
     voc gere seja diferente. Este salt tem que ser sabido quando
     voc checar as suas chaves (keys), logo  uma boa ideia
     que a chave siga o salt. O salt tem o comprimento fixo de 8
     bytes e ser completado com zeros se voce fornecer menos bytes.
     Tenha em mente que as senhas fornecidas pelos usurios no so
     boas para serem usadas como chaves em algoritmos criptogrficos,
     pois usurios normalmente escolhem chaves que eles podem escrever
     no teclado. Estas senhas usam somente 6 a 7 bits por caracter
     (ou menos).  altamente recomendado usar algum tipo de 
     transformao (como esta funo) na chave dada pelo usurio.
    </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
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->