mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-20 02:48:56 +00:00
baf0dab17e
newly documented functions git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@82020 c90b9560-bf6c-de11-be94-00142212c4b1
244 lines
10 KiB
XML
244 lines
10 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.3 $ -->
|
|
<reference id="ref.mcrypt">
|
|
<title>Mcrypt Encryption Functions</title>
|
|
<titleabbrev>mcrypt</titleabbrev>
|
|
|
|
<partintro>
|
|
<para id="mcrypt.intro">
|
|
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>
|
|
<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 id="mcrypt.requirements">
|
|
<title>Requirements</title>
|
|
<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">
|
|
<title>Installation</title>
|
|
<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>
|
|
|
|
<section id="mcrypt.configuration">
|
|
<title>Runtime Configuration</title>
|
|
<para>
|
|
<!-- add configuration directives -->
|
|
</para>
|
|
</section>
|
|
|
|
<section id="mcrypt.resources">
|
|
<title>Resource types</title>
|
|
&no.resource;
|
|
</section>
|
|
|
|
<section id="mcrypt.constants">
|
|
<title>Predefined constants</title>
|
|
|
|
<para>
|
|
Mcrypt can operate in four block cipher modes (CBC, OFB, CFB, and
|
|
ECB). If linked against libmcrypt-2.4.x or higher the functions can also operate
|
|
in the block cipher mode nOFB and in STREAM mode. Below you find a list
|
|
with all supported encryption modes together with the constants that are
|
|
defines for the encryption mode. For a more complete reference and
|
|
discussion see &book.applied.cryptography;.
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_MODE_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.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_MODE_CBC (cipher block chaining) is especially suitable for
|
|
encrypting files where the security is increased over ECB
|
|
significantly.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_MODE_CFB (cipher feedback) is the best mode for encrypting byte
|
|
streams where single bytes must be encrypted.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_MODE_OFB (output feedback, in 8bit) is comparable to CFB, but
|
|
can be used in applications where error propagation cannot
|
|
be tolerated. It's insecure (because it operates in 8bit
|
|
mode) so it is not recommended to use it.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_MODE_NOFB (output feedback, in nbit) is comparable to OFB, but
|
|
more secure because it operates on the block size of the algorithm.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_MODE_STREAM is an extra mode to include some stream algorithms
|
|
like WAKE or RC4.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<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>
|
|
</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
|
|
-->
|
|
|