From 97d13aa37760d63a391c8a35bf0228a6fb8e2bec Mon Sep 17 00:00:00 2001 From: Mehdi Achour Date: Sun, 30 Dec 2007 13:15:56 +0000 Subject: [PATCH] WS, prepare for new doc style git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@249417 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mcrypt/functions/mcrypt-cbc.xml | 76 +++++----- reference/mcrypt/functions/mcrypt-cfb.xml | 76 +++++----- .../mcrypt/functions/mcrypt-create-iv.xml | 128 +++++++++-------- reference/mcrypt/functions/mcrypt-decrypt.xml | 96 ++++++------- reference/mcrypt/functions/mcrypt-ecb.xml | 74 +++++----- .../mcrypt-enc-get-algorithms-name.xml | 56 ++++---- .../functions/mcrypt-enc-get-block-size.xml | 36 ++--- .../functions/mcrypt-enc-get-iv-size.xml | 40 +++--- .../functions/mcrypt-enc-get-key-size.xml | 38 ++--- .../functions/mcrypt-enc-get-modes-name.xml | 60 ++++---- .../mcrypt-enc-get-supported-key-sizes.xml | 66 ++++----- .../mcrypt-enc-is-block-algorithm-mode.xml | 36 ++--- .../mcrypt-enc-is-block-algorithm.xml | 36 ++--- .../functions/mcrypt-enc-is-block-mode.xml | 38 ++--- .../mcrypt/functions/mcrypt-enc-self-test.xml | 38 ++--- reference/mcrypt/functions/mcrypt-encrypt.xml | 132 +++++++++--------- .../functions/mcrypt-generic-deinit.xml | 54 ++++--- .../mcrypt/functions/mcrypt-generic-end.xml | 56 ++++---- .../mcrypt/functions/mcrypt-generic-init.xml | 86 ++++++------ reference/mcrypt/functions/mcrypt-generic.xml | 104 +++++++------- .../functions/mcrypt-get-block-size.xml | 94 ++++++------- .../functions/mcrypt-get-cipher-name.xml | 76 +++++----- .../mcrypt/functions/mcrypt-get-iv-size.xml | 102 +++++++------- .../mcrypt/functions/mcrypt-get-key-size.xml | 88 ++++++------ .../functions/mcrypt-list-algorithms.xml | 68 ++++----- .../mcrypt/functions/mcrypt-list-modes.xml | 74 +++++----- .../mcrypt/functions/mcrypt-module-close.xml | 42 +++--- .../mcrypt-module-get-algo-block-size.xml | 40 +++--- .../mcrypt-module-get-algo-key-size.xml | 42 +++--- .../mcrypt-module-get-supported-key-sizes.xml | 52 +++---- .../mcrypt-module-is-block-algorithm-mode.xml | 44 +++--- .../mcrypt-module-is-block-algorithm.xml | 42 +++--- .../functions/mcrypt-module-is-block-mode.xml | 44 +++--- .../mcrypt/functions/mcrypt-module-open.xml | 126 ++++++++--------- .../functions/mcrypt-module-self-test.xml | 68 ++++----- reference/mcrypt/functions/mcrypt-ofb.xml | 76 +++++----- .../mcrypt/functions/mdecrypt-generic.xml | 96 ++++++------- 37 files changed, 1246 insertions(+), 1254 deletions(-) diff --git a/reference/mcrypt/functions/mcrypt-cbc.xml b/reference/mcrypt/functions/mcrypt-cbc.xml index 5a30a34299..7eee010552 100644 --- a/reference/mcrypt/functions/mcrypt-cbc.xml +++ b/reference/mcrypt/functions/mcrypt-cbc.xml @@ -1,43 +1,43 @@ - + - - - mcrypt_cbc - Encrypt/decrypt data in CBC mode - - - Description - - 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 or higher. The - mode should be either - MCRYPT_ENCRYPT or - MCRYPT_DECRYPT. - - - This function should not be used anymore, see - mcrypt_generic and - mdecrypt_generic for replacements. - - - + + + mcrypt_cbc + Encrypt/decrypt data in CBC mode + + + Description + + 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 or higher. The + mode should be either + MCRYPT_ENCRYPT or + MCRYPT_DECRYPT. + + + This function should not be used anymore, see + mcrypt_generic and + mdecrypt_generic for replacements. + + + + - - - mcrypt_cfb - Encrypt/decrypt data in CFB mode - - - Description - - 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 or higher. The - mode should be either - MCRYPT_ENCRYPT or - MCRYPT_DECRYPT. - - - This function should not be used anymore, see - mcrypt_generic and - mdecrypt_generic for replacements. - - - + + + mcrypt_cfb + Encrypt/decrypt data in CFB mode + + + Description + + 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 or higher. The + mode should be either + MCRYPT_ENCRYPT or + MCRYPT_DECRYPT. + + + This function should not be used anymore, see + mcrypt_generic and + mdecrypt_generic for replacements. + + + + - - - mcrypt_create_iv - - Create an initialization vector (IV) from a random source - - - - Description - - stringmcrypt_create_iv - intsize - intsource - - - mcrypt_create_iv is used to create an IV. - - - Parameter - size determines the size of the IV, - parameter source (defaults to random value) - 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). MCRYPT_RAND - is the only one supported on Windows because Windows (of course) - doesn't have /dev/random or - /dev/urandom. - - - - When using MCRYPT_RAND, remember to call - srand before - mcrypt_create_iv to initialize the random - number generator; it is not seeded automatically like - rand is. - - - - - <function>mcrypt_create_iv</function> example - + + + mcrypt_create_iv + Create an initialization vector (IV) from a random source + + + Description + + stringmcrypt_create_iv + intsize + intsource + + + mcrypt_create_iv is used to create an IV. + + + Parameter + size determines the size of the IV, + parameter source (defaults to random value) + 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). MCRYPT_RAND + is the only one supported on Windows because Windows (of course) + doesn't have /dev/random or + /dev/urandom. + + + + When using MCRYPT_RAND, remember to call + srand before + mcrypt_create_iv to initialize the random + number generator; it is not seeded automatically like + rand is. + + + + + <function>mcrypt_create_iv</function> example + ]]> - - - - - The IV is only meant to give an alternative seed to the encryption - routines. This IV does not need to be secret at all, though it can be - desirable. You even can send it along with your ciphertext without - losing security. - - - More information can be found at &url.mcrypt.iv;, &url.mcrypt.bcm; and in chapter 9.3 of - Applied Cryptography by Schneier (ISBN 0-471-11709-9) for a discussion of - this topic. - - - + + + + + The IV is only meant to give an alternative seed to the encryption + routines. This IV does not need to be secret at all, though it can be + desirable. You even can send it along with your ciphertext without + losing security. + + + More information can be found at &url.mcrypt.iv;, &url.mcrypt.bcm; and in chapter 9.3 of + Applied Cryptography by Schneier (ISBN 0-471-11709-9) for a discussion of + this topic. + + + + - - - mcrypt_decrypt - Decrypts crypttext with given parameters - - - Description - - stringmcrypt_decrypt - stringcipher - stringkey - stringdata - stringmode - stringiv - - - 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_decrypt + Decrypts crypttext with given parameters + + + Description + + stringmcrypt_decrypt + stringcipher + stringkey + stringdata + stringmode + stringiv + + + 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_ecb - Deprecated: Encrypt/decrypt data in ECB mode - - - Description - - 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 or higher. The - mode should be either - MCRYPT_ENCRYPT or - MCRYPT_DECRYPT. - - - This function is deprecated and should not be used anymore, see - mcrypt_generic and - mdecrypt_generic for replacements. - - - + + + mcrypt_ecb + Deprecated: Encrypt/decrypt data in ECB mode + + + Description + + 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 or higher. The + mode should be either + MCRYPT_ENCRYPT or + MCRYPT_DECRYPT. + + + This function is deprecated and should not be used anymore, see + mcrypt_generic and + mdecrypt_generic for replacements. + + + + - - - mcrypt_enc_get_algorithms_name - Returns the name of the opened algorithm - - - Description - - stringmcrypt_enc_get_algorithms_name - resourcetd - - - This function returns the name of the algorithm. - - - - <function>mcrypt_enc_get_algorithms_name</function> example - + + + mcrypt_enc_get_algorithms_name + Returns the name of the opened algorithm + + + Description + + stringmcrypt_enc_get_algorithms_name + resourcetd + + + This function returns the name of the algorithm. + + + + <function>mcrypt_enc_get_algorithms_name</function> example + ]]> - - &example.outputs; - + + &example.outputs; + - - - - - + + + + + + - - - mcrypt_enc_get_block_size - Returns the blocksize of the opened algorithm - - - Description - - 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_block_size + Returns the blocksize of the opened algorithm + + + Description + + 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_iv_size - Returns the size of the IV of the opened algorithm - - - Description - - 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_iv_size + Returns the size of the IV of the opened algorithm + + + Description + + 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_key_size - Returns the maximum supported keysize of the opened mode - - - Description - - 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_key_size + Returns the maximum supported keysize of the opened mode + + + Description + + 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_modes_name - Returns the name of the opened mode - - - Description - - stringmcrypt_enc_get_modes_name - resourcetd - - - This function returns the name of the mode. - - - - <function>mcrypt_enc_get_modes_name</function> example - + + + mcrypt_enc_get_modes_name + Returns the name of the opened mode + + + Description + + stringmcrypt_enc_get_modes_name + resourcetd + + + This function returns the name of the mode. + + + + <function>mcrypt_enc_get_modes_name</function> example + ]]> - - - Prints: - - + + + Prints: + + - - - - - + + + + + + - - - mcrypt_enc_get_supported_key_sizes - Returns an array with the supported keysizes of the opened algorithm - - - Description - - 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. - - - - <function>mcrypt_enc_get_supported_key_sizes</function> example - + + + mcrypt_enc_get_supported_key_sizes + Returns an array with the supported keysizes of the opened algorithm + + + Description + + 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. + + + + <function>mcrypt_enc_get_supported_key_sizes</function> example + ]]> - - - This will print: - - + + + This will print: + + @@ -44,11 +44,11 @@ array(3) { int(32) } ]]> - - - - - + + + + + + - - - mcrypt_enc_is_block_algorithm_mode - Checks whether the encryption of the opened mode works on blocks - - - Description - - boolmcrypt_enc_is_block_algorithm_mode - resourcetd - - - This function returns &true; if the mode is for use with block algorithms, - otherwise it returns &false;. (e.g. &false; for stream, and &true; for cbc, cfb, ofb). - - - + + + mcrypt_enc_is_block_algorithm_mode + Checks whether the encryption of the opened mode works on blocks + + + Description + + boolmcrypt_enc_is_block_algorithm_mode + resourcetd + + + This function returns &true; if the mode is for use with block algorithms, + otherwise it returns &false;. (e.g. &false; for stream, and &true; for cbc, cfb, ofb). + + + + - - - mcrypt_enc_is_block_algorithm - Checks whether the algorithm of the opened mode is a block algorithm - - - Description - - boolmcrypt_enc_is_block_algorithm - resourcetd - - - This function returns &true; if the algorithm is a block algorithm, - or &false; if it is a stream algorithm. - - - + + + mcrypt_enc_is_block_algorithm + Checks whether the algorithm of the opened mode is a block algorithm + + + Description + + boolmcrypt_enc_is_block_algorithm + resourcetd + + + This function returns &true; if the algorithm is a block algorithm, + or &false; if it is a stream algorithm. + + + + - - - mcrypt_enc_is_block_mode - Checks whether the opened mode outputs blocks - - - Description - - boolmcrypt_enc_is_block_mode - resourcetd - - - This function returns &true; if the mode outputs blocks of bytes or - &false; if it outputs bytes. (e.g. &true; for cbc and ecb, and &false; for cfb and - stream). - - - + + + mcrypt_enc_is_block_mode + Checks whether the opened mode outputs blocks + + + Description + + boolmcrypt_enc_is_block_mode + resourcetd + + + This function returns &true; if the mode outputs blocks of bytes or + &false; if it outputs bytes. (e.g. &true; for cbc and ecb, and &false; for cfb and + stream). + + + + - - - mcrypt_enc_self_test - This function runs a self test on the opened module - - - Description - - 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 &false;. In case - of an error, it returns &true;. - - - + + + mcrypt_enc_self_test + This function runs a self test on the opened module + + + Description + + 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 &false;. In case + of an error, it returns &true;. + + + + - - - mcrypt_encrypt - Encrypts plaintext with given parameters - - - Description - - stringmcrypt_encrypt - stringcipher - stringkey - stringdata - stringmode - stringiv - - - 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'. - - - - <function>mcrypt_encrypt</function> Example - + + + mcrypt_encrypt + Encrypts plaintext with given parameters + + + Description + + stringmcrypt_encrypt + stringcipher + stringkey + stringdata + stringmode + stringiv + + + 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'. + + + + <function>mcrypt_encrypt</function> Example + ]]> - - &example.outputs; - + + &example.outputs; + - - - - - See also mcrypt_module_open for a more advanced API - and an example. - - - + + + + + See also mcrypt_module_open for a more advanced API + and an example. + + + + - - - mcrypt_generic_deinit - - This function deinitializes an encryption module - - - - Description - - boolmcrypt_generic_deinit - resourcetd - - - This function terminates encryption specified by the encryption - descriptor (td). It clears all buffers, but does - not close the module. You need to call - mcrypt_module_close yourself. (But PHP does this for - you at the end of the script.) Returns &false; on error, or &true; on - success. - - - See for an example mcrypt_module_open and the - entry on mcrypt_generic_init. - - - + + + mcrypt_generic_deinit + This function deinitializes an encryption module + + + Description + + boolmcrypt_generic_deinit + resourcetd + + + This function terminates encryption specified by the encryption + descriptor (td). It clears all buffers, but does + not close the module. You need to call + mcrypt_module_close yourself. (But PHP does this for + you at the end of the script.) Returns &false; on error, or &true; on + success. + + + See for an example mcrypt_module_open and the + entry on mcrypt_generic_init. + + + + - - - mcrypt_generic_end - This function terminates encryption - - - Description - - boolmcrypt_generic_end - resourcetd - + + + mcrypt_generic_end + This function terminates encryption + + + Description + + boolmcrypt_generic_end + resourcetd + + + - - - This function is deprecated, use - mcrypt_generic_deinit instead. It can cause - crashes when used with mcrypt_module_close due to - multiple buffer frees. - - + This function is deprecated, use + mcrypt_generic_deinit instead. It can cause + crashes when used with mcrypt_module_close due to + multiple buffer frees. - - 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 - success. - - - + + + + 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 + success. + + + + - - - mcrypt_generic_init - This function initializes all buffers needed for encryption - - - Description - - 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, -3 when the key length - was incorrect, -4 when there was a memory allocation problem and any - other return value is an unknown error. If an error occurs a warning will - be displayed accordingly. &false; is returned if incorrect parameters - were passed. - - - You need to call this function before every call to - mcrypt_generic or - mdecrypt_generic. - - - See for an example mcrypt_module_open. - - - + + + mcrypt_generic_init + This function initializes all buffers needed for encryption + + + Description + + 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, -3 when the key length + was incorrect, -4 when there was a memory allocation problem and any + other return value is an unknown error. If an error occurs a warning will + be displayed accordingly. &false; is returned if incorrect parameters + were passed. + + + You need to call this function before every call to + mcrypt_generic or + mdecrypt_generic. + + + See for an example mcrypt_module_open. + + + + - - - mcrypt_generic - This function encrypts data - - - Description - - 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. - - - If you want to store the encrypted data in a database make sure to store - the entire string as returned by mcrypt_generic, or the string will not - entirely decrypt properly. If your original string is 10 characters long - and the block size is 8 (use - mcrypt_enc_get_block_size to determine the - blocksize), you would need at least 16 characters in your database field. - Note the string returned by mdecrypt_generic will be - 16 characters as well...use rtrim($str, "\0") to - remove the padding. - - - If you are for example storing the data in a MySQL database remember that - varchar fields automatically have trailing spaces removed during - insertion. As encrypted data can end in a space (ASCII 32), the data will - be damaged by this removal. Store data in a tinyblob/tinytext (or - larger) field instead. - - - The encryption handle should always be initialized with - mcrypt_generic_init with a key and an IV before - calling this function. Where the encryption is done, you should free the - encryption buffers by calling mcrypt_generic_deinit. - See mcrypt_module_open for an example. - - - See also mdecrypt_generic, - mcrypt_generic_init, and - mcrypt_generic_deinit. - - - + + + mcrypt_generic + This function encrypts data + + + Description + + 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. + + + If you want to store the encrypted data in a database make sure to store + the entire string as returned by mcrypt_generic, or the string will not + entirely decrypt properly. If your original string is 10 characters long + and the block size is 8 (use + mcrypt_enc_get_block_size to determine the + blocksize), you would need at least 16 characters in your database field. + Note the string returned by mdecrypt_generic will be + 16 characters as well...use rtrim($str, "\0") to + remove the padding. + + + If you are for example storing the data in a MySQL database remember that + varchar fields automatically have trailing spaces removed during + insertion. As encrypted data can end in a space (ASCII 32), the data will + be damaged by this removal. Store data in a tinyblob/tinytext (or + larger) field instead. + + + The encryption handle should always be initialized with + mcrypt_generic_init with a key and an IV before + calling this function. Where the encryption is done, you should free the + encryption buffers by calling mcrypt_generic_deinit. + See mcrypt_module_open for an example. + + + See also mdecrypt_generic, + mcrypt_generic_init, and + mcrypt_generic_deinit. + + + + - - - mcrypt_get_block_size - Get the block size of the specified cipher - - - Description - - 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 or 2.5.x. - - - mcrypt_get_block_size is used to get the - size of a block of the specified cipher (in - combination with an encryption mode). - - - It is more useful to use the mcrypt_enc_get_block_size - function as this uses the resource returned by - mcrypt_module_open. - - - This example shows how to use this function when linked against libmcrypt - 2.4.x and 2.5.x. - - <function>mcrypt_get_block_size</function> example - + + + mcrypt_get_block_size + Get the block size of the specified cipher + + + Description + + 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 or 2.5.x. + + + mcrypt_get_block_size is used to get the + size of a block of the specified cipher (in + combination with an encryption mode). + + + It is more useful to use the mcrypt_enc_get_block_size + function as this uses the resource returned by + mcrypt_module_open. + + + This example shows how to use this function when linked against libmcrypt + 2.4.x and 2.5.x. + + <function>mcrypt_get_block_size</function> example + - - - - - See also: mcrypt_get_key_size, - mcrypt_enc_get_block_size and - mcrypt_encrypt. - - - + + + + + See also: mcrypt_get_key_size, + mcrypt_enc_get_block_size and + mcrypt_encrypt. + + + + - - - mcrypt_get_cipher_name - Get the name of the specified cipher - - - Description - - 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 or higher) and returns the name of the cipher - or &false;, if the cipher does not exist. - - - - <function>mcrypt_get_cipher_name</function> Example - + + + mcrypt_get_cipher_name + Get the name of the specified cipher + + + Description + + 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 or higher) and returns the name of the cipher + or &false;, if the cipher does not exist. + + + + <function>mcrypt_get_cipher_name</function> Example + ]]> - - &example.outputs; - + + &example.outputs; + - - - - - + + + + + + - - - mcrypt_get_iv_size - - Returns the size of the IV belonging to a specific cipher/mode combination - - - - Description - - intmcrypt_get_iv_size - stringcipher - stringmode - - - 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 - or one of "ecb", "cbc", "cfb", "ofb", "nofb" or "stream". The IV is - ignored in ECB mode as this mode does not require it. You will need to - have the same IV (think: starting point) both at encryption and - decryption stages, otherwise your encryption will fail. - - - It is more useful to use the mcrypt_enc_get_iv_size - function as this uses the resource returned by - mcrypt_module_open. - - - - <function>mcrypt_get_iv_size</function> example - + + + mcrypt_get_iv_size + Returns the size of the IV belonging to a specific cipher/mode combination + + + Description + + intmcrypt_get_iv_size + stringcipher + stringmode + + + 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 + or one of "ecb", "cbc", "cfb", "ofb", "nofb" or "stream". The IV is + ignored in ECB mode as this mode does not require it. You will need to + have the same IV (think: starting point) both at encryption and + decryption stages, otherwise your encryption will fail. + + + It is more useful to use the mcrypt_enc_get_iv_size + function as this uses the resource returned by + mcrypt_module_open. + + + + <function>mcrypt_get_iv_size</function> example + ]]> - - - - - See also - mcrypt_get_block_size, - mcrypt_enc_get_iv_size and - mcrypt_create_iv. - - - + + + + + See also + mcrypt_get_block_size, + mcrypt_enc_get_iv_size and + mcrypt_create_iv. + + + + - - - mcrypt_get_key_size - Get the key size of the specified cipher - - - Description - - 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 or 2.5.x. - - - mcrypt_get_key_size is used to get the size - of a key of the specified cipher (in - combination with an encryption mode). - - - This example shows how to use this function when linked against libmcrypt - 2.4.x and 2.5.x. It is more useful to use the - mcrypt_enc_get_key_size function as this uses the - resource returned by mcrypt_module_open. + + + mcrypt_get_key_size + Get the key size of the specified cipher + + + Description + + 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 or 2.5.x. + + + mcrypt_get_key_size is used to get the size + of a key of the specified cipher (in + combination with an encryption mode). + + + This example shows how to use this function when linked against libmcrypt + 2.4.x and 2.5.x. It is more useful to use the + mcrypt_enc_get_key_size function as this uses the + resource returned by mcrypt_module_open. - - <function>mcrypt_get_block_size</function> example - + + <function>mcrypt_get_block_size</function> example + - - - - - See also: mcrypt_get_block_size, - mcrypt_end_get_key_size and - mcrypt_encrypt. - + + + + + See also: mcrypt_get_block_size, + mcrypt_end_get_key_size and + mcrypt_encrypt. + - - + + + - - - mcrypt_list_algorithms - Get an array of all supported ciphers - - - Description - - arraymcrypt_list_algorithms - stringlib_dir - - - mcrypt_list_algorithms is used to get an - array of all supported algorithms in the lib_dir parameter. - - - mcrypt_list_algorithms takes an optional - lib_dir parameter which specifies the directory - where all algorithms are located. If not specifies, the value of the - mcrypt.algorithms_dir &php.ini; directive is used. - - - - <function>mcrypt_list_algorithms</function> Example - + + + mcrypt_list_algorithms + Get an array of all supported ciphers + + + Description + + arraymcrypt_list_algorithms + stringlib_dir + + + mcrypt_list_algorithms is used to get an + array of all supported algorithms in the lib_dir parameter. + + + mcrypt_list_algorithms takes an optional + lib_dir parameter which specifies the directory + where all algorithms are located. If not specifies, the value of the + mcrypt.algorithms_dir &php.ini; directive is used. + + + + <function>mcrypt_list_algorithms</function> Example + ]]> - - - The above example will produce a list with all supported - algorithms in the "/usr/local/lib/libmcrypt" directory. - - + + + 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 - - - Description - - arraymcrypt_list_modes - stringlib_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. - - - - <function>mcrypt_list_modes</function> Example - + + + mcrypt_list_modes + Get an array of all supported modes + + + Description + + arraymcrypt_list_modes + stringlib_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. + + + + <function>mcrypt_list_modes</function> Example + ]]> - - - 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). - - + + + 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_module_close - - Close the mcrypt module - - - - Description - - boolmcrypt_module_close - resourcetd - - - This function closes the specified encryption handle. - - - See mcrypt_module_open for an example. - - - + + + mcrypt_module_close + Close the mcrypt module + + + Description + + boolmcrypt_module_close + resourcetd + + + This function closes the specified encryption handle. + + + See mcrypt_module_open for an example. + + + + - - - mcrypt_module_get_algo_block_size - Returns the blocksize of the specified algorithm - - - Description - - 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_block_size + Returns the blocksize of the specified algorithm + + + Description + + 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 - - - Description - - 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_algo_key_size + Returns the maximum supported keysize of the opened mode + + + Description + + 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 - - - Description - - 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. - - - See also mcrypt_enc_get_supported_key_sizes which is - used on open encryption modules. - - - + + + mcrypt_module_get_supported_key_sizes + Returns an array with the supported keysizes of the opened algorithm + + + Description + + 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. + + + See also mcrypt_enc_get_supported_key_sizes which is + used on open encryption modules. + + + + - - - mcrypt_module_is_block_algorithm_mode - Returns if the specified module is a block algorithm or not - - - Description - - 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 &false;. (e.g. &false; for stream, and - &true; 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_mode + Returns if the specified module is a block algorithm or not + + + Description + + 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 &false;. (e.g. &false; for stream, and + &true; 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 - - - Description - - 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_algorithm + This function checks whether the specified algorithm is a block algorithm + + + Description + + 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 - Returns if the specified mode outputs blocks or not - - - Description - - 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. (e.g. &true; for cbc and ecb, and - &false; for cfb and stream). The optional lib_dir - parameter can contain the location where the mode module is on the - system. - - - + + + mcrypt_module_is_block_mode + Returns if the specified mode outputs blocks or not + + + Description + + 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. (e.g. &true; for cbc and ecb, and + &false; for cfb and stream). The optional lib_dir + parameter can contain the location where the mode module is on the + system. + + + + - - - mcrypt_module_open - Opens the module of the algorithm and the mode to be used - - - Description - - 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, e.g. "twofish" or is - one of the MCRYPT_ciphername constants. The module is closed by calling - mcrypt_module_close. 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 directories that are used are the ones - that were compiled in into libmcrypt (usually /usr/local/lib/libmcrypt). - - - - <function>mcrypt_module_open</function> examples - + + + mcrypt_module_open + Opens the module of the algorithm and the mode to be used + + + Description + + 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, e.g. "twofish" or is + one of the MCRYPT_ciphername constants. The module is closed by calling + mcrypt_module_close. 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 directories that are used are the ones + that were compiled in into libmcrypt (usually /usr/local/lib/libmcrypt). + + + + <function>mcrypt_module_open</function> examples + ]]> - - - - - The first line in the example above will try to open the DES cipher from - the default directory and the EBC mode from the directory - /usr/lib/mcrypt-modes. The second example uses - strings as name for the cipher and mode, this only works when the - extension is linked against libmcrypt 2.4.x or 2.5.x. - - - - Using <function>mcrypt_module_open</function> in encryption - + + + + + The first line in the example above will try to open the DES cipher from + the default directory and the EBC mode from the directory + /usr/lib/mcrypt-modes. The second example uses + strings as name for the cipher and mode, this only works when the + extension is linked against libmcrypt 2.4.x or 2.5.x. + + + + Using <function>mcrypt_module_open</function> in encryption + ]]> - - - - - See also - mcrypt_module_close, - mcrypt_generic, - mdecrypt_generic, - mcrypt_generic_init, and - mcrypt_generic_deinit. - - - + + + + + See also + mcrypt_module_close, + mcrypt_generic, + mdecrypt_generic, + mcrypt_generic_init, and + mcrypt_generic_deinit. + + + + - - - mcrypt_module_self_test - This function runs a self test on the specified module - - - Description - - 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. - - - - <function>mcrypt_module_self_test</function> example - + + + mcrypt_module_self_test + This function runs a self test on the specified module + + + Description + + 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. + + + + <function>mcrypt_module_self_test</function> example + ]]> - - &example.outputs; - + + &example.outputs; + - - - - - + + + + + + - - - mcrypt_ofb - Encrypt/decrypt data in OFB mode - - - Description - - 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 or higher. The - mode should be either - MCRYPT_ENCRYPT or - MCRYPT_DECRYPT. - - - This function should not be used anymore, see - mcrypt_generic and - mdecrypt_generic for replacements. - - - + + + mcrypt_ofb + Encrypt/decrypt data in OFB mode + + + Description + + 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 or higher. The + mode should be either + MCRYPT_ENCRYPT or + MCRYPT_DECRYPT. + + + This function should not be used anymore, see + mcrypt_generic and + mdecrypt_generic for replacements. + + + + - - - mdecrypt_generic - Decrypt data - - - Description - - 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. - - - - <function>mdecrypt_generic</function> example - + + + mdecrypt_generic + Decrypt data + + + Description + + 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. + + + + <function>mdecrypt_generic</function> example + ]]> - - - - - The above example shows how to check if the data before the encryption is - the same as the data after the decryption. It is very important to - reinitialize the encryption buffer with - mcrypt_generic_init before you try to decrypt the - data. - - - The decryption handle should always be initialized with - mcrypt_generic_init with a key and an IV before - calling this function. Where the encryption is done, you should free the - encryption buffers by calling mcrypt_generic_deinit. - See mcrypt_module_open for an example. - - - See also mcrypt_generic, - mcrypt_generic_init, and - mcrypt_generic_deinit. - - - + + + + + The above example shows how to check if the data before the encryption is + the same as the data after the decryption. It is very important to + reinitialize the encryption buffer with + mcrypt_generic_init before you try to decrypt the + data. + + + The decryption handle should always be initialized with + mcrypt_generic_init with a key and an IV before + calling this function. Where the encryption is done, you should free the + encryption buffers by calling mcrypt_generic_deinit. + See mcrypt_module_open for an example. + + + See also mcrypt_generic, + mcrypt_generic_init, and + mcrypt_generic_deinit. + + +