<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
 <reference id="ref.mcrypt">
  <title>Mcrypt Encryption Functions</title>
  <titleabbrev>mcrypt</titleabbrev>
  
  <partintro>
   <section id="mcrypt.intro">
    &reftitle.intro;
    <para>
     This is an interface to the mcrypt library, which supports a wide
     variety of block algorithms such as DES, TripleDES, Blowfish
     (default), 3-WAY, SAFER-SK64, SAFER-SK128, TWOFISH, TEA, RC2 and
     GOST in CBC, OFB, CFB and ECB cipher modes. Additionally, it
     supports RC6 and IDEA which are considered "non-free".
    </para>
   </section>

   <section id="mcrypt.requirements">
    &reftitle.required;
    <para>
     These functions work using <ulink url="&url.mcrypt;">mcrypt</ulink>.
    </para>
    <para>
     If you linked against libmcrypt 2.4.x or higher, the following additional
     block algorithms are supported: CAST, LOKI97, RIJNDAEL, SAFERPLUS,
     SERPENT and the following stream ciphers: ENIGMA (crypt), PANAMA, RC4 and
     WAKE. With libmcrypt 2.4.x or higher another cipher mode is also
     available; nOFB.
    </para>
   </section>

   <section id="mcrypt.installation">
    &reftitle.install;
    <para>
     To use it, download libmcrypt-x.x.tar.gz from <ulink
     url="&url.mcrypt;">here</ulink> and follow the included installation
     instructions. You need to compile PHP with the <option
     role="configure">--with-mcrypt</option> parameter to enable this
     extension. Make sure you compile libmcrypt with the option <option
     role="configure">--disable-posix-threads</option>.
    </para>
   </section>

   &reference.mcrypt.ini;

   <section id="mcrypt.resources">
    &reftitle.resources;
    &no.resource;
   </section>

   &reference.mcrypt.constants;
   
   <section id="mcrypt.ciphers">
    <title>Mcrypt ciphers</title>
    <para>
     Here is a list of ciphers which are currently supported by the mcrypt
     extension.  For a complete list of supported ciphers, see the defines at
     the end of <filename>mcrypt.h</filename>. The general rule with the
     mcrypt-2.2.x API is that you can access the cipher from PHP with
     MCRYPT_ciphername. With the libmcrypt-2.4.x and libmcrypt-2.5.x API these constants also work,
     but it is possible to specify the name of the cipher as a string with a
     call to <function>mcrypt_module_open</function>.
     <itemizedlist>
      <listitem><simpara>MCRYPT_3DES</simpara></listitem>
      <listitem><simpara>MCRYPT_ARCFOUR_IV (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_ARCFOUR (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_BLOWFISH</simpara></listitem>
      <listitem><simpara>MCRYPT_CAST_128</simpara></listitem>
      <listitem><simpara>MCRYPT_CAST_256</simpara></listitem>
      <listitem><simpara>MCRYPT_CRYPT</simpara></listitem>
      <listitem><simpara>MCRYPT_DES</simpara></listitem>
      <listitem><simpara>MCRYPT_DES_COMPAT (libmcrypt 2.2.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_ENIGMA (libmcrypt > 2.4.x only, alias for MCRYPT_CRYPT)</simpara></listitem>
      <listitem><simpara>MCRYPT_GOST</simpara></listitem>
      <listitem><simpara>MCRYPT_IDEA (non-free)</simpara></listitem>
      <listitem><simpara>MCRYPT_LOKI97 (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_MARS (libmcrypt > 2.4.x only, non-free)</simpara></listitem>
      <listitem><simpara>MCRYPT_PANAMA (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_RIJNDAEL_128 (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_RIJNDAEL_192 (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_RIJNDAEL_256 (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_RC2</simpara></listitem>
      <listitem><simpara>MCRYPT_RC4 (libmcrypt 2.2.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_RC6 (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_RC6_128 (libmcrypt 2.2.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_RC6_192 (libmcrypt 2.2.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_RC6_256 (libmcrypt 2.2.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_SAFER64</simpara></listitem>
      <listitem><simpara>MCRYPT_SAFER128</simpara></listitem>
      <listitem><simpara>MCRYPT_SAFERPLUS (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_SERPENT(libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_SERPENT_128 (libmcrypt 2.2.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_SERPENT_192 (libmcrypt 2.2.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_SERPENT_256 (libmcrypt 2.2.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_SKIPJACK (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_TEAN (libmcrypt 2.2.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_THREEWAY</simpara></listitem>
      <listitem><simpara>MCRYPT_TRIPLEDES (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_TWOFISH (for older mcrypt 2.x versions, or mcrypt > 2.4.x )</simpara></listitem>
      <listitem><simpara>MCRYPT_TWOFISH128 (TWOFISHxxx are available in newer 2.x versions, but not in the 2.4.x versions)</simpara></listitem>
      <listitem><simpara>MCRYPT_TWOFISH192</simpara></listitem>
      <listitem><simpara>MCRYPT_TWOFISH256</simpara></listitem>
      <listitem><simpara>MCRYPT_WAKE (libmcrypt > 2.4.x only)</simpara></listitem>
      <listitem><simpara>MCRYPT_XTEA (libmcrypt > 2.4.x only)</simpara></listitem>
     </itemizedlist>
    </para>
    <para>
     You must (in CFB and OFB mode) or can (in CBC mode) supply an
     initialization vector (IV) to the respective cipher function. The
     IV must be unique and must be the same when
     decrypting/encrypting. With data which is stored encrypted, you
     can take the output of a function of the index under which the
     data is stored (e.g.  the MD5 key of the filename).
     Alternatively, you can transmit the IV together with the encrypted
     data (see chapter 9.3 of &book.applied.cryptography; for a
     discussion of this topic).
    </para>
   </section>
   
   <section id="mcrypt.examples">
    &reftitle.examples;
    <para>
     Mcrypt can be used to encrypt and decrypt using the above
     mentioned ciphers. If you linked against libmcrypt-2.2.x, the
     four important mcrypt commands (<function>mcrypt_cfb</function>,
     <function>mcrypt_cbc</function>, <function>mcrypt_ecb</function>,
     and <function>mcrypt_ofb</function>) can operate in both modes
     which are named MCRYPT_ENCRYPT and MCRYPT_DECRYPT, respectively.
     <example>
      <title>Encrypt an input value with TripleDES under 2.2.x in ECB mode</title>
      <programlisting role="php">
<![CDATA[
<?php
$key = "this is a very secret key";
$input = "Let us meet at 9 o'clock at the secret place.";

$encrypted_data = mcrypt_ecb (MCRYPT_3DES, $key, $input, MCRYPT_ENCRYPT);
?>
]]>
      </programlisting>
     </example>
     This example will give you the encrypted data as a string in
     <literal>$encrypted_data</literal>.
    </para>
    <para>
     If you linked against libmcrypt 2.4.x or 2.5.x, these functions are still
     available, but it is recommended that you use the advanced functions.
     <example>
      <title>Encrypt an input value with TripleDES under 2.4.x and higher in ECB mode</title>
      <programlisting role="php">
<![CDATA[
<?php
    $key = "this is a very secret key";
    $input = "Let us meet at 9 o'clock at the secret place.";

    $td = mcrypt_module_open ('tripledes', '', 'ecb', '');
    $iv = mcrypt_create_iv (mcrypt_enc_get_iv_size ($td), MCRYPT_RAND);
    mcrypt_generic_init ($td, $key, $iv);
    $encrypted_data = mcrypt_generic ($td, $input);
    mcrypt_generic_end ($td);
?>
]]>
      </programlisting>
     </example>
     This example will give you the encrypted data as a string in
     <literal>$encrypted_data</literal>.  For a full example see
     <function>mcrypt_module_open</function>.
    </para>
   </section>
  </partintro>

&reference.mcrypt.functions;

 </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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->