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". 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. 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. <?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); ?> 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. <?php $key = "this is a very secret key"; $input = "Let us meet at 9 o'clock at the secret place."; $td = mcrypt_open_module (MCRYPT_TripleDES, "", MCRYPT_MODE_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); ?> This example will give you the encrypted data as a string in $encrypted_data. 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. Then there are also constants in the form MCRYPT_MODE_mode for use with several functions. 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, 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. nOFB (output feedback, in nbit) is comparable to OFB, but more secure because it operates on the block size of the algorithm. STREAM is an extra mode to include some stream algorithms like WAKE or RC4. 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 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_open_module. 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_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 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 string mcrypt_get_cipher_name int cipher string mcrypt_get_cipher_name string 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 (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. <?php $cipher = MCRYPT_TripleDES; print mcrypt_get_cipher_name ($cipher); ?> The above example will produce: TripleDES mcrypt_get_block_size Get the block size of the specified cipher 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 takes one argument, the cipher and returns the size in bytes. See also: mcrypt_get_key_size. mcrypt_get_key_size Get the key size of the specified cipher 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 takes one argument, the cipher and returns the size in bytes. See also: mcrypt_get_block_size. mcrypt_create_iv Create an initialization vector (IV) from a random source string mcrypt_create_iv int size int source 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. <?php $cipher = MCRYPT_TripleDES; $block_size = mcrypt_get_block_size ($cipher); $iv = mcrypt_create_iv ($block_size, MCRYPT_DEV_RANDOM); ?> mcrypt_cbc Encrypt/decrypt data in CBC mode string mcrypt_cbc int cipher string key string data int mode string iv string mcrypt_cbc string cipher string key string data int mode string iv 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 string mcrypt_cfb int cipher string key string data int mode string iv string mcrypt_cfb string cipher string key string data int mode string iv 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 string mcrypt_ecb int cipher string key string data int mode string mcrypt_ecb string cipher string key string data int mode string iv 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 string mcrypt_ofb int cipher string key string data int mode string iv string mcrypt_ofb string cipher string key string data int mode string iv 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 array mcrypt_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. <?php $algorithms = mcrypt_list_algorithms ("/usr/local/lib/libmcrypt"); foreach ($algorithms as $cipher) { echo $cipher."/n"; } ?> 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 array mcrypt_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. <?php $modes = mcrypt_list_modes (); foreach ($modes as $mode) { echo $mode."/n"; } ?> 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 int mcrypt_get_iv_size string cipher string mode Mcrypt_get_iv_size returns the size of the Initialisation Vector (IV). 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". mcrypt_encrypt Encrypts plaintext with given parameters string mcrypt_encrypt string cipher string key string data string mode 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'. 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'. <?php $iv = mcrypt_create_iv (mcrypt_get_iv_size (MCRYPT_RIJNDAEL_256, MCRYPT_MODE_ECB), MCRYPT_RAND); $key = "This is a very secret key"; $text = "Meet me at 11 o'clock behind the monument."; echo strlen ($text)."\n"; $crypttext = mcrypt_encrypt (MCRYPT_RIJNDAEL_256, $key, $text, MCRYPT_MODE_ECB, $iv); echo strlen ($crypttext)."\n"; ?> The above example will print out: 42 64 mcrypt_decrypt Decrypts crypttext with given parameters string mcrypt_decrypt string cipher string key string data string mode 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 resource mcrypt_module_open string algorithm string algorithm_directory string mode string mode_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). <?php $td = mcrypt_module_open (MCRYPT_DES, "", MCRYPT_MODE_ECB, "/usr/lib/mcrypt-modes"); ?> 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_generic_init This function initializes all buffers needed for encryption int mcrypt_generic_init resource td string key string iv 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 (-1) on error. You need to call this function before every mcrypt_generic or mdecrypt_generic. mcrypt_generic This function encrypts data string mcrypt_generic resource td string data 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 string mdecrypt_generic resource td string data 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. <?php $iv_size = mcrypt_enc_get_iv_size ($td)); $iv = @mcrypt_create_iv ($iv_size, MCRYPT_RAND); if (@mcrypt_generic_init ($td, $key, $iv) != -1) { $c_t = mcrypt_generic ($td, $plain_text); @mcrypt_generic_init ($td, $key, $iv); $p_t = mdecrypt_generic ($td, $c_t); } if (strncmp ($p_t, $plain_text, strlen($plain_text)) == 0) echo "ok"; else echo "error"; ?> 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 bool mcrypt_generic_end resource td 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 int mcrypt_enc_self_test resource td 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 int mcrypt_enc_is_block_algorithm_mode resource td 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 int mcrypt_enc_is_block_algorithm resource td 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 int mcrypt_enc_is_block_mode resource td 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 int mcrypt_enc_get_block_size resource td 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 int mcrypt_enc_get_key_size resource td 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 array mcrypt_enc_get_supported_key_sizes resource td 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 int mcrypt_enc_get_iv_size resource td 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 string mcrypt_enc_get_algorithms_name resource td This function returns the name of the algorithm. mcrypt_enc_get_modes_name Returns the name of the opened mode string mcrypt_enc_get_modes_name resource td This function returns the name of the mode. mcrypt_module_self_test This function runs a self test on the specified module bool mcrypt_module_self_test string algorithm string lib_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 bool mcrypt_module_is_block_algorithm_mode string mode string lib_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 bool mcrypt_module_is_block_algorithm string algorithm string lib_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 bool mcrypt_module_is_block_mode string mode string lib_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 int mcrypt_module_get_algo_block_size string algorithm string lib_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 int mcrypt_module_get_algo_key_size string algorithm string lib_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_algo_supported_key_sizes Returns an array with the supported keysizes of the opened algorithm array mcrypt_module_enc_get_algo_supported_key_sizes string algorithm string lib_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.