mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 02:18:56 +00:00
56cc0f7774
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@26901 c90b9560-bf6c-de11-be94-00142212c4b1
556 lines
17 KiB
XML
556 lines
17 KiB
XML
<reference id="ref.mcrypt">
|
|
<title>Mcrypt Encryption Functions</title>
|
|
<titleabbrev>mcrypt</titleabbrev>
|
|
|
|
<partintro>
|
|
<para>
|
|
These functions work using <ulink
|
|
url="&url.mcrypt;">mcrypt</ulink>.
|
|
</para>
|
|
<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>
|
|
<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>
|
|
<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">
|
|
<?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);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
This example will give you the encrypted data as a string in
|
|
<literal>$encrypted_data</literal>.
|
|
</para>
|
|
<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.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
CBC (cipher block chaining) is especially suitable for
|
|
encrypting files where the security is increased over ECB
|
|
significantly.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
CFB (cipher feedback) is the best mode for encrypting byte
|
|
streams where single bytes must be encrypted.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
OFB (output feedback) is comparable to CFB, but can be used in
|
|
applications where error propagation cannot be
|
|
tolerated.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
PHP does not support encrypting/decrypting bit streams
|
|
currently. As of now, PHP only supports handling of strings.
|
|
</para>
|
|
<para>
|
|
For a complete list of supported ciphers, see the defines at the
|
|
end of <filename>mcrypt.h</filename>. The general rule is that you
|
|
can access the cipher from PHP with MCRYPT_ciphername.
|
|
</para>
|
|
<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
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_DES
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_TripleDES
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_ThreeWAY
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_GOST
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_CRYPT
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_DES_COMPAT
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_SAFER64
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_SAFER128
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_CAST128
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_TEAN
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_RC2
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_TWOFISH (for older mcrypt 2.x versions)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_TWOFISH128 (TWOFISHxxx are available in newer 2.x versions)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_TWOFISH192
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_TWOFISH256
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_RC6
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
MCRYPT_IDEA
|
|
</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>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>string <function>mcrypt_get_cipher_name</function></funcdef>
|
|
<paramdef>int <parameter>cipher</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>Mcrypt_get_cipher_name</function> is used to get the
|
|
name of the specified cipher.
|
|
</para>
|
|
<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>
|
|
<para>
|
|
<example>
|
|
<title><function>Mcrypt_get_cipher_name</function> Example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
$cipher = MCRYPT_TripleDES;
|
|
|
|
print mcrypt_get_cipher_name ($cipher);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
The above example will produce:
|
|
<programlisting>
|
|
TripleDES
|
|
</programlisting>
|
|
</para>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>int <function>mcrypt_get_block_size</function></funcdef>
|
|
<paramdef>int <parameter>cipher</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>Mcrypt_get_block_size</function> is used to get the
|
|
size of a block of the specified <parameter>cipher</parameter>.
|
|
</para>
|
|
<para>
|
|
<function>Mcrypt_get_block_size</function> takes one argument, the
|
|
<parameter>cipher</parameter> and returns the size in bytes.
|
|
</para>
|
|
<para>
|
|
See also: <function>mcrypt_get_key_size</function>.
|
|
</para>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>int <function>mcrypt_get_key_size</function></funcdef>
|
|
<paramdef>int <parameter>cipher</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>Mcrypt_get_key_size</function> is used to get the size
|
|
of a key of the specified <parameter>cipher</parameter>.
|
|
</para>
|
|
<para>
|
|
<function>mcrypt_get_key_size</function> takes one argument, the
|
|
<parameter>cipher</parameter> and returns the size in bytes.
|
|
</para>
|
|
<para>
|
|
See also: <function>mcrypt_get_block_size</function>.
|
|
</para>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>string
|
|
<function>mcrypt_create_iv</function></funcdef>
|
|
<paramdef>int <parameter>size</parameter></paramdef>
|
|
<paramdef>int <parameter>source</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>Mcrypt_create_iv</function> is used to create an IV.
|
|
</para>
|
|
<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>
|
|
<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>
|
|
<para>
|
|
<example>
|
|
<title><function>Mcrypt_create_iv</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
$cipher = MCRYPT_TripleDES;
|
|
$block_size = mcrypt_get_block_size ($cipher);
|
|
$iv = mcrypt_create_iv ($block_size, MCRYPT_DEV_RANDOM);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>string <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>
|
|
</funcprototype>
|
|
</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>
|
|
<para>
|
|
<parameter>Cipher</parameter> is one of the MCRYPT_ciphername
|
|
constants.
|
|
</para>
|
|
<para>
|
|
<parameter>Key</parameter> is the key supplied to the
|
|
algorithm. It must be kept secret.
|
|
</para>
|
|
<para>
|
|
<parameter>Data</parameter> is the data which shall be
|
|
encrypted/decrypted.
|
|
</para>
|
|
<para>
|
|
<parameter>Mode</parameter> is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.
|
|
</para>
|
|
<para>
|
|
<parameter>IV</parameter> is the optional initialization vector.
|
|
</para>
|
|
<para>
|
|
See also: <function>mcrypt_cfb</function>,
|
|
<function>mcrypt_ecb</function>, and
|
|
<function>mcrypt_ofb</function>.
|
|
</para>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>string <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>
|
|
</funcprototype>
|
|
</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>
|
|
<para>
|
|
<parameter>Cipher</parameter> is one of the MCRYPT_ciphername
|
|
constants.
|
|
</para>
|
|
<para>
|
|
<parameter>Key</parameter> is the key supplied to the
|
|
algorithm. It must be kept secret.
|
|
</para>
|
|
<para>
|
|
<parameter>Data</parameter> is the data which shall be
|
|
encrypted/decrypted.
|
|
</para>
|
|
<para>
|
|
<parameter>Mode</parameter> is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.
|
|
</para>
|
|
<para>
|
|
<parameter>IV</parameter> is the initialization vector.
|
|
</para>
|
|
<para>
|
|
See also: <function>mcrypt_cbc</function>,
|
|
<function>mcrypt_ecb</function>, and
|
|
<function>mcrypt_ofb</function>.
|
|
</para>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>string <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>
|
|
</funcprototype>
|
|
</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>
|
|
<para>
|
|
<parameter>Cipher</parameter> is one of the MCRYPT_ciphername
|
|
constants.
|
|
</para>
|
|
<para>
|
|
<parameter>Key</parameter> is the key supplied to the
|
|
algorithm. It must be kept secret.
|
|
</para>
|
|
<para>
|
|
<parameter>Data</parameter> is the data which shall be
|
|
encrypted/decrypted.
|
|
</para>
|
|
<para>
|
|
<parameter>Mode</parameter> is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.
|
|
</para>
|
|
<para>
|
|
See also: <function>mcrypt_cbc</function>,
|
|
<function>mcrypt_cfb</function>, and
|
|
<function>mcrypt_ofb</function>.
|
|
</para>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>string <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>
|
|
</funcprototype>
|
|
</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>
|
|
<para>
|
|
<parameter>Cipher</parameter> is one of the MCRYPT_ciphername
|
|
constants.
|
|
</para>
|
|
<para>
|
|
<parameter>Key</parameter> is the key supplied to the
|
|
algorithm. It must be kept secret.
|
|
</para>
|
|
<para>
|
|
<parameter>Data</parameter> is the data which shall be
|
|
encrypted/decrypted.
|
|
</para>
|
|
<para>
|
|
<parameter>Mode</parameter> is MCRYPT_ENCRYPT or MCRYPT_DECRYPT.
|
|
</para>
|
|
<para>
|
|
<parameter>IV</parameter> is the initialization vector.
|
|
</para>
|
|
<para>
|
|
See also: <function>mcrypt_cbc</function>,
|
|
<function>mcrypt_cfb</function>, and
|
|
<function>mcrypt_ecb</function>.
|
|
</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:
|
|
-->
|