php-doc-en/functions/mcrypt.sgml

 <reference id="ref.mcrypt">
  <title>Encryption functions</title>
  <titleabbrev>mcrypt</titleabbrev>
  
  <partintro>
   <para>
    These functions work using <ulink url="&url.mcrypt;">mcrypt</ulink>.

   <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>
    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.

   <para>
    mcrypt can be used to encrypt and decrypt using the above
    mentioned ciphers. 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 in ECB mode</title>
     <programlisting role="php">
&lt;?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_TripleDES, $key, $input, MCRYPT_ENCRYPT);
?&gt;
     </programlisting>
    </example>
	  
    This example will give you the encrypted data as a string in
    $encrypted_data. 

   <para>
    mcrypt can operate in four cipher modes (CBC, OFB, CFB, and ECB). We will
    outline the normal use for each of these modes. For a more complete
    reference and discussion see &book.applied.cryptography;.

    <itemizedlist>
     <listitem><simpara>
      ECB (electronic codebook) is suitable for random data, such as encrypting
      other keys. Since data there is short and random, the disadvantages of
      ECB have a favorable negative effect.

     <listitem><simpara>
      CBC (cipher block chaining) is especially suitable for encrypting files
      where the security is increased over ECB significantly. 

     <listitem><simpara>
      CFB (cipher feedback) is the best mode for encrypting byte streams where
      single bytes must be encrypted.

     <listitem><simpara>
      OFB (output feedback) is comparable to CFB, but can be used in
      applications where error propagation cannot be tolerated. 
    </itemizedlist>
    
   <para>
    PHP does not support encrypting/decrypting bit streams currently. As of
    now, PHP only supports handling of strings.

   <para>
    For a complete list of supported ciphers, see the defines at the end of
    mcrypt.h. The general rule is that you can access the cipher from PHP with
    MCRYPT_ciphername. 
   
   <para>
    Here is a short list of ciphers which are currently supported by the
    mcrypt extension. If a cipher is not listed here, but is listed by
    mcrypt as supported, you can safely assume that this documentation
    is outdated.

    <itemizedlist>

     <listitem><simpara>
      MCRYPT_BLOWFISH
     <listitem><simpara>
      MCRYPT_DES
     <listitem><simpara>
      MCRYPT_TripleDES
     <listitem><simpara>
      MCRYPT_ThreeWAY
     <listitem><simpara>
      MCRYPT_GOST
     <listitem><simpara>
      MCRYPT_CRYPT
     <listitem><simpara>
      MCRYPT_DES_COMPAT
     <listitem><simpara>
      MCRYPT_SAFER64
     <listitem><simpara>
      MCRYPT_SAFER128
     <listitem><simpara>
      MCRYPT_CAST128
     <listitem><simpara>
      MCRYPT_TEAN
     <listitem><simpara>
      MCRYPT_RC2
     <listitem><simpara>
      MCRYPT_TWOFISH (for older mcrypt 2.x versions)
     <listitem><simpara>
      MCRYPT_TWOFISH128 (TWOFISHxxx are available in newer 2.x versions)
     <listitem><simpara>
      MCRYPT_TWOFISH192
     <listitem><simpara>
      MCRYPT_TWOFISH256
     <listitem><simpara>
      MCRYPT_RC6
     <listitem><simpara>
      MCRYPT_IDEA

    </itemizedlist>

   <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).

  </partintro>
  
  <refentry id="function.mcrypt-get-cipher-name">
   <refnamediv>
    <refname>mcrypt_get_cipher_name</refname>
    <refpurpose>Get the name of the specified cipher</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>mcrypt_get_cipher_name</function></funcdef>
     <paramdef>int <parameter>cipher</parameter></paramdef>
    </funcsynopsis>
	
    <para>
     <function>mcrypt_get_cipher_name</function> is used to get the name of the
     specified cipher.

    <para>
     <function>mcrypt_get_cipher_name</function> takes the cipher number as an
     argument and returns the name of the cipher or false, if the cipher does
     not exist.
     
    <para>
     <example>
      <title>mcrypt_get_cipher_name example</title>
      <programlisting>
&lt;?php
$cipher = MCRYPT_TripleDES;

print mcrypt_get_cipher_name($cipher);
?&gt;
      </programlisting>
     </example>
	 
    <para>
     The above example will produce:
     <programlisting>
TripleDES
     </programlisting>
	
   </refsect1>
  </refentry>
  
  <refentry id="function.mcrypt-get-block-size">
   <refnamediv>
    <refname>mcrypt_get_block_size</refname>
    <refpurpose>Get the block size of the specified cipher</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mcrypt_get_block_size</function></funcdef>
     <paramdef>int <parameter>cipher</parameter></paramdef>
    </funcsynopsis>
	
    <para>
     <function>mcrypt_get_block_size</function> is used to get the size of a
     block of the specified <parameter>cipher</parameter>.

    <para>
     <function>mcrypt_get_block_size</function> takes one argument, the
     <parameter>cipher</parameter> and returns the size in bytes. 

    <para>
     See also: <function>mcrypt_get_key_size</function>

   </refsect1>
  </refentry>
  
  <refentry id="function.mcrypt-get-key-size">
   <refnamediv>
    <refname>mcrypt_get_key_size</refname>
    <refpurpose>Get the key size of the specified cipher</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mcrypt_get_key_size</function></funcdef>
     <paramdef>int <parameter>cipher</parameter></paramdef>
    </funcsynopsis>
	
    <para>
     <function>mcrypt_get_key_size</function> is used to get the size of a key
     of the specified <parameter>cipher</parameter>.

    <para>
     <function>mcrypt_get_key_size</function> takes one argument, the
     <parameter>cipher</parameter> and returns the size in bytes. 

    <para>
     See also: <function>mcrypt_get_block_size</function>

   </refsect1>
  </refentry>
  
  <refentry id="function.mcrypt-create-iv">
   <refnamediv>
    <refname>mcrypt_create_iv</refname>
    <refpurpose>Create an initialization vector (IV) from a random source</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string
     <function>mcrypt_create_iv</function></funcdef>
     <paramdef>int <parameter>size</parameter></paramdef>
     <paramdef>int <parameter>source</parameter></paramdef>
    </funcsynopsis>
	
    <para>
     <function>mcrypt_create_iv</function> is used to create an IV.

    <para>
     <function>mcrypt_create_iv</function> takes two arguments,
     <parameter>size</parameter> determines the size of the IV,
     <parameter>source</parameter> specifies the source of the IV. 
     
    <para>
     The source can be MCRYPT_RAND (system random number generator),
     MCRYPT_DEV_RANDOM (read data from /dev/random) and MCRYPT_DEV_URANDOM
     (read data from /dev/urandom). If you use MCRYPT_RAND, make sure to call
     srand() before to initialize the random number generator.

    <para>
     <example>
      <title>mcrypt_create_iv example</title>
      <programlisting>
&lt;?php
$cipher = MCRYPT_TripleDES;
$block_size = mcrypt_get_block_size($cipher);
$iv = mcrypt_create_iv($block_size, MCRYPT_DEV_RANDOM);
?&gt;
      </programlisting>
     </example>

   </refsect1>
  </refentry>
 
  <refentry id="function.mcrypt-cbc">
   <refnamediv>
    <refname>mcrypt_cbc</refname>
    <refpurpose>Encrypt/decrypt data in CBC mode</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mcrypt_cbc</function></funcdef>
     <paramdef>int <parameter>cipher</parameter></paramdef>
     <paramdef>string <parameter>key</parameter></paramdef>
     <paramdef>string <parameter>data</parameter></paramdef>
     <paramdef>int <parameter>mode</parameter></paramdef>
     <paramdef>string <parameter><optional>iv</optional></parameter></paramdef>
    </funcsynopsis>
	
    <para>
     <function>mcrypt_cbc</function> encrypts or decrypts (depending on
     <parameter>mode</parameter>) the <parameter>data</parameter> with
     <parameter>cipher</parameter> and <parameter>key</parameter> in CBC cipher
     mode and returns the resulting string.
    
    <para>
     <parameter>cipher</parameter> is one of the MCRYPT_ciphername constants.

    <para>
     <parameter>key</parameter> is the key supplied to the algorithm. It must
     be kept secret.  

    <para>
     <parameter>data</parameter> is the data which shall be
     encrypted/decrypted. 
     
    <para>
     <parameter>mode</parameter> is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.

    <para>
     <parameter>iv</parameter> is the optional initialization vector.

    <para>
     See also:
     <function>mcrypt_cfb</function>,
     <function>mcrypt_ecb</function>,
     <function>mcrypt_ofb</function>
	 
   </refsect1>
  </refentry>

  <refentry id="function.mcrypt-cfb">
   <refnamediv>
    <refname>mcrypt_cfb</refname>
    <refpurpose>Encrypt/decrypt data in CFB mode</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mcrypt_cfb</function></funcdef>
     <paramdef>int <parameter>cipher</parameter></paramdef>
     <paramdef>string <parameter>key</parameter></paramdef>
     <paramdef>string <parameter>data</parameter></paramdef>
     <paramdef>int <parameter>mode</parameter></paramdef>
     <paramdef>string <parameter>iv</parameter></paramdef>
    </funcsynopsis>
	
    <para>
     <function>mcrypt_cfb</function> encrypts or decrypts (depending on
     <parameter>mode</parameter>) the <parameter>data</parameter> with
     <parameter>cipher</parameter> and <parameter>key</parameter> in CFB cipher
     mode and returns the resulting string.
    
    <para>
     <parameter>cipher</parameter> is one of the MCRYPT_ciphername constants.

    <para>
     <parameter>key</parameter> is the key supplied to the algorithm. It must
     be kept secret.  

    <para>
     <parameter>data</parameter> is the data which shall be
     encrypted/decrypted. 
     
    <para>
     <parameter>mode</parameter> is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.

    <para>
     <parameter>iv</parameter> is the initialization vector.

    <para>
     See also:
     <function>mcrypt_cbc</function>,
     <function>mcrypt_ecb</function>,
     <function>mcrypt_ofb</function>
	 
   </refsect1>
  </refentry>
  
  <refentry id="function.mcrypt-ecb">
   <refnamediv>
    <refname>mcrypt_ecb</refname>
    <refpurpose>Encrypt/decrypt data in ECB mode</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mcrypt_ecb</function></funcdef>
     <paramdef>int <parameter>cipher</parameter></paramdef>
     <paramdef>string <parameter>key</parameter></paramdef>
     <paramdef>string <parameter>data</parameter></paramdef>
     <paramdef>int <parameter>mode</parameter></paramdef>
    </funcsynopsis>
	
    <para>
     <function>mcrypt_ecb</function> encrypts or decrypts (depending on
     <parameter>mode</parameter>) the <parameter>data</parameter> with
     <parameter>cipher</parameter> and <parameter>key</parameter> in ECB cipher
     mode and returns the resulting string.
    
    <para>
     <parameter>cipher</parameter> is one of the MCRYPT_ciphername constants.

    <para>
     <parameter>key</parameter> is the key supplied to the algorithm. It must
     be kept secret.  

    <para>
     <parameter>data</parameter> is the data which shall be
     encrypted/decrypted. 
     
    <para>
     <parameter>mode</parameter> is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.

    <para>
     See also:
     <function>mcrypt_cbc</function>,
     <function>mcrypt_cfb</function>,
     <function>mcrypt_ofb</function>
	 
   </refsect1>
  </refentry>

  <refentry id="function.mcrypt-ofb">
   <refnamediv>
    <refname>mcrypt_ofb</refname>
    <refpurpose>Encrypt/decrypt data in OFB mode</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mcrypt_ofb</function></funcdef>
     <paramdef>int <parameter>cipher</parameter></paramdef>
     <paramdef>string <parameter>key</parameter></paramdef>
     <paramdef>string <parameter>data</parameter></paramdef>
     <paramdef>int <parameter>mode</parameter></paramdef>
     <paramdef>string <parameter>iv</parameter></paramdef>
    </funcsynopsis>
	
    <para>
     <function>mcrypt_ofb</function> encrypts or decrypts (depending on
     <parameter>mode</parameter>) the <parameter>data</parameter> with
     <parameter>cipher</parameter> and <parameter>key</parameter> in OFB cipher
     mode and returns the resulting string.
    
    <para>
     <parameter>cipher</parameter> is one of the MCRYPT_ciphername constants.

    <para>
     <parameter>key</parameter> is the key supplied to the algorithm. It must
     be kept secret.  

    <para>
     <parameter>data</parameter> is the data which shall be
     encrypted/decrypted. 
     
    <para>
     <parameter>mode</parameter> is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.

    <para>
     <parameter>iv</parameter> is the initialization vector.

    <para>
     See also:
     <function>mcrypt_cbc</function>,
     <function>mcrypt_cfb</function>,
     <function>mcrypt_ecb</function>
	 
   </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:
-->