diff --git a/functions/mcrypt.xml b/functions/mcrypt.xml index 17e7a7fc03..817a6f6d5d 100644 --- a/functions/mcrypt.xml +++ b/functions/mcrypt.xml @@ -4,20 +4,22 @@ - These functions work using mcrypt. - + These functions work using mcrypt. + 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". - + supports RC6 and IDEA which are considered "non-free". + - To use it, download libmcrypt-x.x.tar.gz from here and follow the included - installation instructions. You need to compile PHP with the parameter to enable this - extension. - + To use it, download libmcrypt-x.x.tar.gz from here and follow the included + installation instructions. You need to compile PHP with the + parameter to + enable this extension. + mcrypt can be used to encrypt and decrypt using the above mentioned ciphers. The four important mcrypt commands @@ -25,7 +27,6 @@ mcrypt_ecb, and mcrypt_ofb) can operate in both modes which are named MCRYPT_ENCRYPT and MCRYPT_DECRYPT, respectively. - Encrypt an input value with TripleDES in ECB mode @@ -37,100 +38,163 @@ $encrypted_data = mcrypt_ecb(MCRYPT_TripleDES, $key, $input, MCRYPT_ENCRYPT); ?> - This example will give you the encrypted data as a string in - $encrypted_data. - + $encrypted_data. + - 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;. - + 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;. - - 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. - - - CBC (cipher block chaining) is especially suitable for encrypting files - where the security is increased over ECB significantly. - - - CFB (cipher feedback) is the best mode for encrypting byte streams where - single bytes must be encrypted. - - - OFB (output feedback) is comparable to CFB, but can be used in - applications where error propagation cannot be tolerated. - - + + + 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. + + + + + CBC (cipher block chaining) is especially suitable for + encrypting files where the security is increased over ECB + significantly. + + + + + CFB (cipher feedback) is the best mode for encrypting byte + streams where single bytes must be encrypted. + + + + + OFB (output feedback) is comparable to CFB, but can be used in + applications where error propagation cannot be + tolerated. + + + + - PHP does not support encrypting/decrypting bit streams currently. As of - now, PHP only supports handling of strings. - + PHP does not support encrypting/decrypting bit streams + currently. As of now, PHP only supports handling of strings. + - 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. - + 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. + - 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. - + 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. - - - MCRYPT_BLOWFISH - - MCRYPT_DES - - MCRYPT_TripleDES - - MCRYPT_ThreeWAY - - MCRYPT_GOST - - MCRYPT_CRYPT - - MCRYPT_DES_COMPAT - - MCRYPT_SAFER64 - - MCRYPT_SAFER128 - - MCRYPT_CAST128 - - MCRYPT_TEAN - - MCRYPT_RC2 - - MCRYPT_TWOFISH (for older mcrypt 2.x versions) - - MCRYPT_TWOFISH128 (TWOFISHxxx are available in newer 2.x versions) - - MCRYPT_TWOFISH192 - - MCRYPT_TWOFISH256 - - MCRYPT_RC6 - - MCRYPT_IDEA - - - + + + MCRYPT_BLOWFISH + + + + + MCRYPT_DES + + + + + MCRYPT_TripleDES + + + + + MCRYPT_ThreeWAY + + + + + MCRYPT_GOST + + + + + MCRYPT_CRYPT + + + + + MCRYPT_DES_COMPAT + + + + + MCRYPT_SAFER64 + + + + + MCRYPT_SAFER128 + + + + + MCRYPT_CAST128 + + + + + MCRYPT_TEAN + + + + + MCRYPT_RC2 + + + + + MCRYPT_TWOFISH (for older mcrypt 2.x versions) + + + + + MCRYPT_TWOFISH128 (TWOFISHxxx are available in newer 2.x versions) + + + + + MCRYPT_TWOFISH192 + + + + + MCRYPT_TWOFISH256 + + + + + MCRYPT_RC6 + + + + + MCRYPT_IDEA + + + + 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). - + 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). + @@ -144,34 +208,33 @@ $encrypted_data = mcrypt_ecb(MCRYPT_TripleDES, $key, $input, MCRYPT_ENCRYPT); string mcrypt_get_cipher_name int cipher - - mcrypt_get_cipher_name is used to get the name of the - specified cipher. - + Mcrypt_get_cipher_name is used to get the + name of the specified cipher. + - mcrypt_get_cipher_name takes the cipher number as an - argument and returns the name of the cipher or false, if the cipher does - not exist. - + Mcrypt_get_cipher_name takes the cipher + number as an argument and returns the name of the cipher or + false, if the cipher does not exist. + - mcrypt_get_cipher_name example - + <function>Mcrypt_get_cipher_name</function> example + <?php $cipher = MCRYPT_TripleDES; -print mcrypt_get_cipher_name($cipher); +print mcrypt_get_cipher_name ($cipher); ?> - - + + The above example will produce: TripleDES - - + + @@ -186,18 +249,17 @@ TripleDES int mcrypt_get_block_size int cipher - - mcrypt_get_block_size is used to get the size of a - block of the specified cipher. - + Mcrypt_get_block_size is used to get the size of a + block of the specified cipher. + - mcrypt_get_block_size takes one argument, the - cipher and returns the size in bytes. - + Mcrypt_get_block_size takes one argument, the + cipher and returns the size in bytes. + - See also: mcrypt_get_key_size - + See also: mcrypt_get_key_size. + @@ -212,25 +274,26 @@ TripleDES int mcrypt_get_key_size int cipher - - mcrypt_get_key_size is used to get the size of a key - of the specified cipher. - + Mcrypt_get_key_size is used to get the size + of a key of the specified cipher. + mcrypt_get_key_size takes one argument, the - cipher and returns the size in bytes. - + cipher and returns the size in bytes. + - See also: mcrypt_get_block_size - + See also: mcrypt_get_block_size. + mcrypt_create_iv - Create an initialization vector (IV) from a random source + + Create an initialization vector (IV) from a random source + Description @@ -240,33 +303,33 @@ TripleDES int size int source - - mcrypt_create_iv is used to create an IV. - + Mcrypt_create_iv is used to create an IV. + mcrypt_create_iv takes two arguments, size determines the size of the IV, - source specifies the source of the IV. - + source specifies the source of the IV. + 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. - + 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. + - mcrypt_create_iv example - + <function>Mcrypt_create_iv</function> example + <?php $cipher = MCRYPT_TripleDES; -$block_size = mcrypt_get_block_size($cipher); -$iv = mcrypt_create_iv($block_size, MCRYPT_DEV_RANDOM); +$block_size = mcrypt_get_block_size ($cipher); +$iv = mcrypt_create_iv ($block_size, MCRYPT_DEV_RANDOM); ?> - - + + @@ -283,38 +346,39 @@ $iv = mcrypt_create_iv($block_size, MCRYPT_DEV_RANDOM); string key string data int mode - string iv + string + iv + - - mcrypt_cbc encrypts or decrypts (depending on - mode) the data with - cipher and key in CBC cipher - mode and returns the resulting string. - + Mcrypt_cbc encrypts or decrypts (depending + on mode) the data + with cipher and key + in CBC cipher mode and returns the resulting string. + - cipher is one of the MCRYPT_ciphername constants. - + Cipher is one of the MCRYPT_ciphername + constants. + - key is the key supplied to the algorithm. It must - be kept secret. - + Key is the key supplied to the + algorithm. It must be kept secret. + - data is the data which shall be - encrypted/decrypted. - + Data is the data which shall be + encrypted/decrypted. + - mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. - + Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. + - iv is the optional initialization vector. - + IV is the optional initialization vector. + - See also: - mcrypt_cfb, - mcrypt_ecb, - mcrypt_ofb - + See also: mcrypt_cfb, + mcrypt_ecb, and + mcrypt_ofb. + @@ -333,36 +397,35 @@ $iv = mcrypt_create_iv($block_size, MCRYPT_DEV_RANDOM); int mode string iv - - mcrypt_cfb encrypts or decrypts (depending on - mode) the data with - cipher and key in CFB cipher - mode and returns the resulting string. - + Mcrypt_cfb encrypts or decrypts (depending + on mode) the data + with cipher and key + in CFB cipher mode and returns the resulting string. + - cipher is one of the MCRYPT_ciphername constants. - + Cipher is one of the MCRYPT_ciphername + constants. + - key is the key supplied to the algorithm. It must - be kept secret. - + Key is the key supplied to the + algorithm. It must be kept secret. + - data is the data which shall be - encrypted/decrypted. - + Data is the data which shall be + encrypted/decrypted. + - mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. - + Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. + - iv is the initialization vector. - + IV is the initialization vector. + - See also: - mcrypt_cbc, - mcrypt_ecb, - mcrypt_ofb - + See also: mcrypt_cbc, + mcrypt_ecb, and + mcrypt_ofb. + @@ -380,33 +443,32 @@ $iv = mcrypt_create_iv($block_size, MCRYPT_DEV_RANDOM); string data int mode - - mcrypt_ecb encrypts or decrypts (depending on - mode) the data with - cipher and key in ECB cipher - mode and returns the resulting string. - + Mcrypt_ecb encrypts or decrypts (depending + on mode) the data + with cipher and key + in ECB cipher mode and returns the resulting string. + - cipher is one of the MCRYPT_ciphername constants. - + Cipher is one of the MCRYPT_ciphername + constants. + - key is the key supplied to the algorithm. It must - be kept secret. - + Key is the key supplied to the + algorithm. It must be kept secret. + - data is the data which shall be - encrypted/decrypted. - + Data is the data which shall be + encrypted/decrypted. + - mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. - + Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. + - See also: - mcrypt_cbc, - mcrypt_cfb, - mcrypt_ofb - + See also: mcrypt_cbc, + mcrypt_cfb, and + mcrypt_ofb. + @@ -424,37 +486,36 @@ $iv = mcrypt_create_iv($block_size, MCRYPT_DEV_RANDOM); string data int mode string iv - - + - mcrypt_ofb encrypts or decrypts (depending on - mode) the data with - cipher and key in OFB cipher - mode and returns the resulting string. - + Mcrypt_ofb encrypts or decrypts (depending + on mode) the data + with cipher and key + in OFB cipher mode and returns the resulting string. + - cipher is one of the MCRYPT_ciphername constants. - + Cipher is one of the MCRYPT_ciphername + constants. + - key is the key supplied to the algorithm. It must - be kept secret. - + Key is the key supplied to the + algorithm. It must be kept secret. + - data is the data which shall be - encrypted/decrypted. - + Data is the data which shall be + encrypted/decrypted. + - mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. - + Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. + - iv is the initialization vector. - + IV is the initialization vector. + - See also: - mcrypt_cbc, - mcrypt_cfb, - mcrypt_ecb - + See also: mcrypt_cbc, + mcrypt_cfb, and + mcrypt_ecb. + @@ -470,7 +531,7 @@ sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil -sgml-default-dtd-file:"../manual.ced" +sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil