MFB: Upgrade to the new-reference-structure

- (Created missing setup sections in setup.xml, if any)
 - Moved the intro to book.xml
 - Changed the intro ID from <extname>.intro to intro.<extname>
 - Moved the constants entity to book.xml
 - Changed constants.xml to be an appendix
 - Moved the mcrypt.ciphers section into its own chapter (ciphers.xml)
 - Moved the mcrypt.examples section into its own chapter (examples.xml)
 - Moved the requirements and resources sections to setup.xml
 - Moved the configure and ini entities to setup.xml


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@248996 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Hannes Magnusson 2007-12-26 13:23:26 +00:00
parent 84aa551004
commit 1b05071ab0
6 changed files with 295 additions and 177 deletions

50
reference/mcrypt/book.xml Normal file
View file

@ -0,0 +1,50 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<!-- Purpose: mathcrypto.crypto -->
<!-- Membership: bundled, external -->
<book xml:id="book.mcrypt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Mcrypt Encryption</title>
<!-- {{{ preface -->
<preface xml:id="intro.mcrypt">
&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>
</preface>
<!-- }}} -->
&reference.mcrypt.setup;
&reference.mcrypt.constants;
&reference.mcrypt.ciphers;
&reference.mcrypt.examples;
&reference.mcrypt.reference;
</book>
<!-- 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
-->

View file

@ -0,0 +1,91 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<appendix xml:id="mcrypt.ciphers" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<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>
</appendix>
<!-- 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
-->

View file

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<section xml:id="mcrypt.constants" xmlns="http://docbook.org/ns/docbook">
<!-- $Revision: 1.4 $ -->
<appendix xml:id="mcrypt.constants" xmlns="http://docbook.org/ns/docbook">
&reftitle.constants;
&extension.constants;
<para>
@ -114,7 +114,7 @@
</varlistentry>
</variablelist>
</para>
</section>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:

View file

@ -0,0 +1,75 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<appendix xml:id="mcrypt.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&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 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 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_deinit($td);
mcrypt_module_close($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>
</appendix>
<!-- 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
-->

View file

@ -1,182 +1,14 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.21 $ -->
<!-- Purpose: mathcrypto.crypto -->
<!-- Membership: bundled, external -->
<!-- $Revision: 1.22 $ -->
<reference xml:id="ref.mcrypt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Mcrypt Encryption Functions</title>
<titleabbrev>mcrypt</titleabbrev>
<partintro>
<section xml: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>
<reference xml:id="ref.mcrypt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Mcrypt Encryption &Functions;</title>
<titleabbrev>mcrypt</titleabbrev>
<section xml:id="mcrypt.requirements">
&reftitle.required;
<para>
These functions work using <link xlink:href="&url.mcrypt;">mcrypt</link>.
To use it, download <filename>libmcrypt-x.x.tar.gz</filename> from <link
xlink:href="&url.mcrypt;">&url.mcrypt;</link> and follow the included
installation instructions. Windows users will find all the
needed compiled mcrypt binaries at
<link xlink:href="&url.mcrypt.windows;">&url.mcrypt.windows;</link>.
</para>
<simpara>
As of PHP 5.0.0 you will need libmcrypt Version 2.5.6 or greater.
</simpara>
<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>
&reference.mcrypt.entities.functions;
&reference.mcrypt.configure;
</reference>
&reference.mcrypt.ini;
<section xml:id="mcrypt.resources">
&reftitle.resources;
<para>
<function>mcrypt_module_open</function> returns an encryption descriptor.
</para>
</section>
&reference.mcrypt.constants;
<section xml: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 xml: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 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 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_deinit($td);
mcrypt_module_close($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.entities.functions;
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

View file

@ -0,0 +1,70 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="mcrypt.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<!-- {{{ Requirements -->
<section xml:id="mcrypt.requirements">
&reftitle.required;
<para>
These functions work using <link xlink:href="&url.mcrypt;">mcrypt</link>.
To use it, download <filename>libmcrypt-x.x.tar.gz</filename> from <link
xlink:href="&url.mcrypt;">&url.mcrypt;</link> and follow the included
installation instructions. Windows users will find all the
needed compiled mcrypt binaries at
<link xlink:href="&url.mcrypt.windows;">&url.mcrypt.windows;</link>.
</para>
<simpara>
As of PHP 5.0.0 you will need libmcrypt Version 2.5.6 or greater.
</simpara>
<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>
<!-- }}} -->
<!-- {{{ Installation -->
&reference.mcrypt.configure;
<!-- }}} -->
<!-- {{{ Configuration -->
&reference.mcrypt.ini;
<!-- }}} -->
<!-- {{{ Resources -->
<section xml:id="mcrypt.resources">
&reftitle.resources;
<para>
<function>mcrypt_module_open</function> returns an encryption descriptor.
</para>
</section>
<!-- }}} -->
</chapter>
<!-- 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
-->