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". 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 (mcrypt_cfb, mcrypt_cbc, mcrypt_ecb, and mcrypt_ofb) can operate in both modes which are named MCRYPT_ENCRYPT and MCRYPT_DECRYPT, respectively. ]]> This example will give you the encrypted data as a string in $encrypted_data. If you linked against libmcrypt 2.4.x, these functions are still available, but it is recommended that you use the advanced functions. ]]> This example will give you the encrypted data as a string in $encrypted_data.

These functions work using mcrypt. If you linked against libmcrypt 2.4.x, 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 another cipher mode is also available; nOFB.

To use it, download libmcrypt-x.x.tar.gz from here and follow the included installation instructions. You need to compile PHP with the --with-mcrypt parameter to enable this extension. Make sure you compile libmcrypt with the option --disable-posix-threads.

&no.resource;

Mcrypt can operate in four block cipher modes (CBC, OFB, CFB, and ECB). If linked against libmcrypt-2.4.x mcrypt 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;. 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. MCRYPT_MODE_CBC (cipher block chaining) is especially suitable for encrypting files where the security is increased over ECB significantly. MCRYPT_MODE_CFB (cipher feedback) is the best mode for encrypting byte streams where single bytes must be encrypted. 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. MCRYPT_MODE_NOFB (output feedback, in nbit) is comparable to OFB, but more secure because it operates on the block size of the algorithm. MCRYPT_MODE_STREAM is an extra mode to include some stream algorithms like WAKE or RC4. 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 mcrypt.h. The general rule with the mcrypt-2.2.x API is that you can access the cipher from PHP with MCRYPT_ciphername. With the mcrypt-2.4.x API these constants also work, but it is possible to specify the name of the cipher as a string with a call to mcrypt_module_open. MCRYPT_3DES MCRYPT_ARCFOUR_IV (libmcrypt 2.4.x only) MCRYPT_ARCFOUR (libmcrypt 2.4.x only) MCRYPT_BLOWFISH MCRYPT_CAST_128 MCRYPT_CAST_256 MCRYPT_CRYPT MCRYPT_DES MCRYPT_DES_COMPAT (libmcrypt 2.2.x only) MCRYPT_ENIGMA (libmcrypt 2.4.x only, alias for MCRYPT_CRYPT) MCRYPT_GOST MCRYPT_IDEA (non-free) MCRYPT_LOKI97 (libmcrypt 2.4.x only) MCRYPT_MARS (libmcrypt 2.4.x only, non-free) MCRYPT_PANAMA (libmcrypt 2.4.x only) MCRYPT_RIJNDAEL_128 (libmcrypt 2.4.x only) MCRYPT_RIJNDAEL_192 (libmcrypt 2.4.x only) MCRYPT_RIJNDAEL_256 (libmcrypt 2.4.x only) MCRYPT_RC2 MCRYPT_RC4 (libmcrypt 2.2.x only) MCRYPT_RC6 (libmcrypt 2.4.x only) MCRYPT_RC6_128 (libmcrypt 2.2.x only) MCRYPT_RC6_192 (libmcrypt 2.2.x only) MCRYPT_RC6_256 (libmcrypt 2.2.x only) MCRYPT_SAFER64 MCRYPT_SAFER128 MCRYPT_SAFERPLUS (libmcrypt 2.4.x only) MCRYPT_SERPENT(libmcrypt 2.4.x only) MCRYPT_SERPENT_128 (libmcrypt 2.2.x only) MCRYPT_SERPENT_192 (libmcrypt 2.2.x only) MCRYPT_SERPENT_256 (libmcrypt 2.2.x only) MCRYPT_SKIPJACK (libmcrypt 2.4.x only) MCRYPT_TEAN (libmcrypt 2.2.x only) MCRYPT_THREEWAY MCRYPT_TRIPLEDES (libmcrypt 2.4.x only) MCRYPT_TWOFISH (for older mcrypt 2.x versions, or mcrypt 2.4.x ) MCRYPT_TWOFISH128 (TWOFISHxxx are available in newer 2.x versions, but not in the 2.4.x versions) MCRYPT_TWOFISH192 MCRYPT_TWOFISH256 MCRYPT_WAKE (libmcrypt 2.4.x only) MCRYPT_XTEA (libmcrypt 2.4.x only) 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).

mcrypt_get_cipher_name Get the name of the specified cipher stringmcrypt_get_cipher_name intcipher stringmcrypt_get_cipher_name stringcipher 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 (libmcrypt 2.2.x) or takes the cipher name as an argument (libmcrypt 2.4.x) and returns the name of the cipher or &false;, if the cipher does not exist. ]]> The above example will produce: mcrypt_get_block_size Get the block size of the specified cipher intmcrypt_get_block_size intcipher intmcrypt_get_block_size stringcipher stringmodule The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x. mcrypt_get_block_size is used to get the size of a block of the specified cipher. mcrypt_get_block_size takes one or two arguments, the cipher and module, and returns the size in bytes. See also: mcrypt_get_key_size. mcrypt_get_key_size Get the key size of the specified cipher intmcrypt_get_key_size intcipher intmcrypt_get_key_size stringcipher stringmodule The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x. mcrypt_get_key_size is used to get the size of a key of the specified cipher. mcrypt_get_key_size takes one or two arguments, the cipher and module, and returns the size in bytes. See also: mcrypt_get_block_size. mcrypt_create_iv Create an initialization vector (IV) from a random source stringmcrypt_create_iv intsize intsource 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. 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_cbc Encrypt/decrypt data in CBC mode stringmcrypt_cbc intcipher stringkey stringdata intmode stringiv stringmcrypt_cbc stringcipher stringkey stringdata intmode stringiv The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x. 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. Key is the key supplied to the algorithm. It must be kept secret. Data is the data which shall be encrypted/decrypted. Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. IV is the optional initialization vector. See also: mcrypt_cfb, mcrypt_ecb, and mcrypt_ofb. mcrypt_cfb Encrypt/decrypt data in CFB mode stringmcrypt_cfb intcipher stringkey stringdata intmode stringiv stringmcrypt_cfb stringcipher stringkey stringdata intmode stringiv The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x. 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. Key is the key supplied to the algorithm. It must be kept secret. Data is the data which shall be encrypted/decrypted. Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. IV is the initialization vector. See also: mcrypt_cbc, mcrypt_ecb, and mcrypt_ofb. mcrypt_ecb Encrypt/decrypt data in ECB mode stringmcrypt_ecb intcipher stringkey stringdata intmode stringmcrypt_ecb stringcipher stringkey stringdata intmode stringiv The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x. 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. Key is the key supplied to the algorithm. It must be kept secret. Data is the data which shall be encrypted/decrypted. Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. See also: mcrypt_cbc, mcrypt_cfb, and mcrypt_ofb. mcrypt_ofb Encrypt/decrypt data in OFB mode stringmcrypt_ofb intcipher stringkey stringdata intmode stringiv stringmcrypt_ofb stringcipher stringkey stringdata intmode stringiv The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x. 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. Key is the key supplied to the algorithm. It must be kept secret. Data is the data which shall be encrypted/decrypted. Mode is MCRYPT_ENCRYPT or MCRYPT_DECRYPT. IV is the initialization vector. See also: mcrypt_cbc, mcrypt_cfb, and mcrypt_ecb. mcrypt_list_algorithms Get an array of all supported ciphers arraymcrypt_list_algorithms string lib_dir mcrypt_list_algorithms is used to get an array of all supported algorithms in the lib_dir. mcrypt_list_algorithms takes as optional parameter a directory which specifies the directory where all algorithms are located. If not specifies, the value of the mcrypt.algorithms_dir &php.ini; directive is used. ]]> The above example will produce a list with all supported algorithms in the "/usr/local/lib/libmcrypt" directory. mcrypt_list_modes Get an array of all supported modes arraymcrypt_list_modes string lib_dir mcrypt_list_modes is used to get an array of all supported modes in the lib_dir. mcrypt_list_modes takes as optional parameter a directory which specifies the directory where all modes are located. If not specifies, the value of the mcrypt.modes_dir &php.ini; directive is used. "; } ?> ]]> The above example will produce a list with all supported algorithms in the default mode directory. If it is not set with the ini directive mcrypt.modes_dir, the default directory of mcrypt is used (which is /usr/local/lib/libmcrypt). mcrypt_get_iv_size Returns the size of the IV belonging to a specific cipher/mode combination intmcrypt_get_iv_size stringcipher stringmode intmcrypt_get_iv_size resourcetd The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x. mcrypt_get_iv_size returns the size of the Initialisation Vector (IV) in bytes. On error the function returns &false;. If the IV is ignored in the specified cipher/mode combination zero is returned. Cipher is one of the MCRYPT_ciphername constants of the name of the algorithm as string. Mode is one of the MCRYPT_MODE_modename constants of one of "ecb", "cbc", "cfb", "ofb", "nofb" or "stream". Td is the algorithm specified. mcrypt_encrypt Encrypts plaintext with given parameters stringmcrypt_encrypt stringcipher stringkey stringdata stringmode string iv mcrypt_encrypt encrypts the data and returns the encrypted data. Cipher is one of the MCRYPT_ciphername constants of the name of the algorithm as string. Key is the key with which the data will be encrypted. If it's smaller that the required keysize, it is padded with '\0'. It is better not to use ASCII strings for keys. It is recommended to use the mhash functions to create a key from a string. Data is the data that will be encrypted with the given cipher and mode. If the size of the data is not n * blocksize, the data will be padded with '\0'. The returned crypttext can be larger that the size of the data that is given by data. Mode is one of the MCRYPT_MODE_modename constants of one of "ecb", "cbc", "cfb", "ofb", "nofb" or "stream". The IV parameter is used for the initialisation in CBC, CFB, OFB modes, and in some algorithms in STREAM mode. If you do not supply an IV, while it is needed for an algorithm, the function issues a warning and uses an IV with all bytes set to '\0'. ]]> The above example will print out: mcrypt_decrypt Decrypts crypttext with given parameters stringmcrypt_decrypt stringcipher stringkey stringdata stringmode string iv mcrypt_decrypt decrypts the data and returns the unencrypted data. Cipher is one of the MCRYPT_ciphername constants of the name of the algorithm as string. Key is the key with which the data is encrypted. If it's smaller that the required keysize, it is padded with '\0'. Data is the data that will be decrypted with the given cipher and mode. If the size of the data is not n * blocksize, the data will be padded with '\0'. Mode is one of the MCRYPT_MODE_modename constants of one of "ecb", "cbc", "cfb", "ofb", "nofb" or "stream". The IV parameter is used for the initialisation in CBC, CFB, OFB modes, and in some algorithms in STREAM mode. If you do not supply an IV, while it is needed for an algorithm, the function issues a warning and uses an IV with all bytes set to '\0'. mcrypt_module_open This function opens the module of the algorithm and the mode to be used resourcemcrypt_module_open stringalgorithm stringalgorithm_directory stringmode stringmode_directory This function opens the module of the algorithm and the mode to be used. The name of the algorithm is specified in algorithm, eg "twofish" or is one of the MCRYPT_ciphername constants. The library is closed by calling mcrypt_module_close, but there is no need to call that function if mcrypt_generic_end is called. Normally it returns an encryption descriptor, or &false; on error. The algorithm_directory and mode_directory are used to locate the encryption modules. When you supply a directory name, it is used. When you set one of these to the empty string (""), the value set by the mcrypt.algorithms_dir or mcrypt.modes_dir ini-directive is used. When these are not set, the default directory are used that are compiled in into libmcrypt (usally /usr/local/lib/libmcrypt). ]]> The above example will try to open the DES cipher from the default directory and the EBC mode from the directory /usr/lib/mcrypt-modes. mcrypt_module_close Free the descriptor td boolmcrypt_module_close resourcetd &warn.undocumented.func; mcrypt_generic_deinit This function terminates encrypt specified by the descriptor td boolmcrypt_generic_deinit resourcetd &warn.undocumented.func; mcrypt_generic_init This function initializes all buffers needed for encryption intmcrypt_generic_init resourcetd stringkey stringiv The maximum length of the key should be the one obtained by calling mcrypt_enc_get_key_size and every value smaller than this is legal. The IV should normally have the size of the algorithms block size, but you must obtain the size by calling mcrypt_enc_get_iv_size. IV is ignored in ECB. IV MUST exist in CFB, CBC, STREAM, nOFB and OFB modes. It needs to be random and unique (but not secret). The same IV must be used for encryption/decryption. If you do not want to use it you should set it to zeros, but this is not recommended. The function returns a negative value on error. You need to call this function before every mcrypt_generic or mdecrypt_generic. mcrypt_generic This function encrypts data stringmcrypt_generic resourcetd stringdata This function encrypts data. The data is padded with "\0" to make sure the length of the data is n * blocksize. This function returns the encrypted data. Note that the length of the returned string can in fact be longer then the input, due to the padding of the data. mdecrypt_generic This function decrypts data stringmdecrypt_generic resourcetd stringdata This function decrypts data. Note that the length of the returned string can in fact be longer then the unencrypted string, due to the padding of the data. ]]> The above example shows how to check if the data before the encryption is the same as the data after the decryption. mcrypt_generic_end This function terminates encryption boolmcrypt_generic_end resourcetd This function terminates encryption specified by the encryption descriptor (td). Actually it clears all buffers, and closes all the modules used. Returns &false; on error, or &true; on succes. mcrypt_enc_self_test This function runs a self test on the opened module intmcrypt_enc_self_test resourcetd This function runs the self test on the algorithm specified by the descriptor td. If the self test succeeds it returns zero. In case of an error, it returns 1. mcrypt_enc_is_block_algorithm_mode Checks whether the encryption of the opened mode works on blocks intmcrypt_enc_is_block_algorithm_mode resourcetd This function returns 1 if the mode is for use with block algorithms, otherwise it returns 0. (eg. 0 for stream, and 1 for cbc, cfb, ofb). mcrypt_enc_is_block_algorithm Checks whether the algorithm of the opened mode is a block algorithm intmcrypt_enc_is_block_algorithm resourcetd This function returns 1 if the algorithm is a block algorithm, or 0 if it is a stream algorithm. mcrypt_enc_is_block_mode Checks whether the opened mode outputs blocks intmcrypt_enc_is_block_mode resourcetd This function returns 1 if the mode outputs blocks of bytes or 0 if it outputs bytes. (eg. 1 for cbc and ecb, and 0 for cfb and stream). mcrypt_enc_get_block_size Returns the blocksize of the opened algorithm intmcrypt_enc_get_block_size resourcetd This function returns the block size of the algorithm specified by the encryption descriptor td in bytes. mcrypt_enc_get_key_size Returns the maximum supported keysize of the opened mode intmcrypt_enc_get_key_size resourcetd This function returns the maximum supported key size of the algorithm specified by the encryption descriptor td in bytes. mcrypt_enc_get_supported_key_sizes Returns an array with the supported keysizes of the opened algorithm arraymcrypt_enc_get_supported_key_sizes resourcetd Returns an array with the key sizes supported by the algorithm specified by the encryption descriptor. If it returns an empty array then all key sizes between 1 and mcrypt_enc_get_key_size are supported by the algorithm. mcrypt_enc_get_iv_size Returns the size of the IV of the opened algorithm intmcrypt_enc_get_iv_size resourcetd This function returns the size of the iv of the algorithm specified by the encryption descriptor in bytes. If it returns '0' then the IV is ignored in the algorithm. An IV is used in cbc, cfb and ofb modes, and in some algorithms in stream mode. mcrypt_enc_get_algorithms_name Returns the name of the opened algorithm stringmcrypt_enc_get_algorithms_name resourcetd This function returns the name of the algorithm. mcrypt_enc_get_modes_name Returns the name of the opened mode stringmcrypt_enc_get_modes_name resourcetd This function returns the name of the mode. mcrypt_module_self_test This function runs a self test on the specified module boolmcrypt_module_self_test stringalgorithm stringlib_dir This function runs the self test on the algorithm specified. The optional lib_dir parameter can contain the location of where the algorithm module is on the system. The function returns &true; if the self test succeeds, or &false; when if fails. mcrypt_module_is_block_algorithm_mode This function returns if the the specified module is a block algorithm or not boolmcrypt_module_is_block_algorithm_mode stringmode stringlib_dir This function returns &true; if the mode is for use with block algorithms, otherwise it returns 0. (eg. 0 for stream, and 1 for cbc, cfb, ofb). The optional lib_dir parameter can contain the location where the mode module is on the system. mcrypt_module_is_block_algorithm This function checks whether the specified algorithm is a block algorithm boolmcrypt_module_is_block_algorithm stringalgorithm stringlib_dir This function returns &true; if the specified algorithm is a block algorithm, or &false; is it is a stream algorithm. The optional lib_dir parameter can contain the location where the algorithm module is on the system. mcrypt_module_is_block_mode This function returns if the the specified mode outputs blocks or not boolmcrypt_module_is_block_mode stringmode stringlib_dir This function returns &true; if the mode outputs blocks of bytes or &false; if it outputs just bytes. (eg. 1 for cbc and ecb, and 0 for cfb and stream). The optional lib_dir parameter can contain the location where the mode module is on the system. mcrypt_module_get_algo_block_size Returns the blocksize of the specified algorithm intmcrypt_module_get_algo_block_size stringalgorithm stringlib_dir This function returns the block size of the algorithm specified in bytes. The optional lib_dir parameter can contain the location where the mode module is on the system. mcrypt_module_get_algo_key_size Returns the maximum supported keysize of the opened mode intmcrypt_module_get_algo_key_size stringalgorithm stringlib_dir This function returns the maximum supported key size of the algorithm specified in bytes. The optional lib_dir parameter can contain the location where the mode module is on the system. mcrypt_module_get_supported_key_sizes Returns an array with the supported keysizes of the opened algorithm arraymcrypt_module_get_supported_key_sizes stringalgorithm stringlib_dir Returns an array with the key sizes supported by the specified algorithm. If it returns an empty array then all key sizes between 1 and mcrypt_module_get_algo_key_size are supported by the algorithm. The optional lib_dir parameter can contain the location where the mode module is on the system.