From fd290bcfc3cfeeb0923ab8921ac7a1437b3e2ed5 Mon Sep 17 00:00:00 2001 From: Sara Golemon Date: Mon, 5 Dec 2005 20:39:07 +0000 Subject: [PATCH] Document hash extension git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@202111 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/hash/constants.xml | 42 ++++++ reference/hash/functions/hash-algos.xml | 108 +++++++++++++++ reference/hash/functions/hash-file.xml | 118 +++++++++++++++++ reference/hash/functions/hash-final.xml | 108 +++++++++++++++ reference/hash/functions/hash-hmac-file.xml | 125 ++++++++++++++++++ reference/hash/functions/hash-hmac.xml | 123 +++++++++++++++++ reference/hash/functions/hash-init.xml | 122 +++++++++++++++++ reference/hash/functions/hash-update-file.xml | 92 +++++++++++++ .../hash/functions/hash-update-stream.xml | 120 +++++++++++++++++ reference/hash/functions/hash-update.xml | 81 ++++++++++++ reference/hash/functions/hash.xml | 114 ++++++++++++++++ reference/hash/reference.xml | 51 +++++++ 12 files changed, 1204 insertions(+) create mode 100644 reference/hash/constants.xml create mode 100644 reference/hash/functions/hash-algos.xml create mode 100644 reference/hash/functions/hash-file.xml create mode 100644 reference/hash/functions/hash-final.xml create mode 100644 reference/hash/functions/hash-hmac-file.xml create mode 100644 reference/hash/functions/hash-hmac.xml create mode 100644 reference/hash/functions/hash-init.xml create mode 100644 reference/hash/functions/hash-update-file.xml create mode 100644 reference/hash/functions/hash-update-stream.xml create mode 100644 reference/hash/functions/hash-update.xml create mode 100644 reference/hash/functions/hash.xml create mode 100644 reference/hash/reference.xml diff --git a/reference/hash/constants.xml b/reference/hash/constants.xml new file mode 100644 index 0000000000..8731398958 --- /dev/null +++ b/reference/hash/constants.xml @@ -0,0 +1,42 @@ + + +
+ &reftitle.constants; + &extension.constants; + + + + HASH_HMAC + (integer) + + + + Optional flag for hash_init. + Indicates that the HMAC digest-keying algorithm should be + applied to the current hashing context. + + + + +
+ + diff --git a/reference/hash/functions/hash-algos.xml b/reference/hash/functions/hash-algos.xml new file mode 100644 index 0000000000..ca466ec215 --- /dev/null +++ b/reference/hash/functions/hash-algos.xml @@ -0,0 +1,108 @@ + + + + + hash_algos + Return a list of registered hashing algorithms + + + &reftitle.description; + + arrayhash_algos + + + + + + &reftitle.returnvalues; + + Returns a numerically indexed array containing the list of supported + hashing algorithms. + + + + + &reftitle.examples; + + + <function>hash_algos</function> + + As of PHP 5.1.2, hash_algos will return the + following list of algorithm names. + + + +]]> + + &example.outputs; + + md4 + [1] => md5 + [2] => sha1 + [3] => sha256 + [4] => sha384 + [5] => sha512 + [6] => ripemd128 + [7] => ripemd160 + [8] => whirlpool + [9] => tiger128,3 + [10] => tiger160,3 + [11] => tiger192,3 + [12] => tiger128,4 + [13] => tiger160,4 + [14] => tiger192,4 + [15] => snefru + [16] => gost + [17] => adler32 + [18] => crc32 + [19] => crc32b + [20] => haval128,3 + [21] => haval160,3 + [22] => haval192,3 + [23] => haval224,3 + [24] => haval256,3 + [25] => haval128,4 + [26] => haval160,4 + [27] => haval192,4 + [28] => haval224,4 + [29] => haval256,4 + [30] => haval128,5 + [31] => haval160,5 + [32] => haval192,5 + [33] => haval224,5 + [34] => haval256,5 +) +]]> + + + + + + + + diff --git a/reference/hash/functions/hash-file.xml b/reference/hash/functions/hash-file.xml new file mode 100644 index 0000000000..f6b587cc2f --- /dev/null +++ b/reference/hash/functions/hash-file.xml @@ -0,0 +1,118 @@ + + + + + + hash_file + Generate a hash value using the contents of a given file + + + &reftitle.description; + + stringhash_file + stringalgo + stringfilename + boolraw_output + + + + + &reftitle.parameters; + + + + algo + + + Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) + + + + + filename + + + URL describing location of file to be hashed; Supports fopen wrappers. + + + + + raw_output + + + When set to &true;, outputs raw binary data. + Default value (&false;) outpus lowercase hexits. + + + + + + + + + &reftitle.returnvalues; + + Returns a string containing the calculated message digest as lowercase hexits + unless raw_output is set to true in which case the raw + binary representation of the message digest is returned. + + + + + &reftitle.examples; + + + Using <function>hash_file</function> + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + hash + hash_hmac_file + Or hash_update_file + + + + + + + diff --git a/reference/hash/functions/hash-final.xml b/reference/hash/functions/hash-final.xml new file mode 100644 index 0000000000..7ea673df39 --- /dev/null +++ b/reference/hash/functions/hash-final.xml @@ -0,0 +1,108 @@ + + + + + hash_final + Finalize an incremental hash and return desulting digest + + + &reftitle.description; + + stringhash_final + resourcecontext + boolraw_output + + + + + &reftitle.parameters; + + + + context + + + Hashing context returned by hash_init. + + + + + raw_output + + + When set to &true;, outputs raw binary data. + Default value (&false;) outpus lowercase hexits. + + + + + + + + + &reftitle.returnvalues; + + Returns a string containing the calculated message digest as lowercase hexits + unless raw_output is set to true in which case the raw + binary representation of the message digest is returned. + + + + + &reftitle.examples; + + + <function>hash_final</function> + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + hash_init + hash_update + hash_update_stream + hash_update_file + + + + + + + diff --git a/reference/hash/functions/hash-hmac-file.xml b/reference/hash/functions/hash-hmac-file.xml new file mode 100644 index 0000000000..7321f91f52 --- /dev/null +++ b/reference/hash/functions/hash-hmac-file.xml @@ -0,0 +1,125 @@ + + + + + hash_hmac_file + Generate a keyed hash value using the HMAC method and the contents of a given file + + + &reftitle.description; + + stringhash_hmac_file + stringalgo + stringfilename + stringkey + boolraw_output + + + + + &reftitle.parameters; + + + + algo + + + Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) + + + + + filename + + + URL describing location of file to be hashed; Supports fopen wrappers. + + + + + key + + + Shared secret key used for generating the HMAC variant of the message digest. + + + + + raw_output + + + When set to &true;, outputs raw binary data. + Default value (&false;) outpus lowercase hexits. + + + + + + + + + &reftitle.returnvalues; + + Returns a string containing the calculated message digest as lowercase hexits + unless raw_output is set to true in which case the raw + binary representation of the message digest is returned. + + + + + &reftitle.examples; + + + <function>hash_hmac_file</function> example + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + hash_hmac + Or hash_file + + + + + + + diff --git a/reference/hash/functions/hash-hmac.xml b/reference/hash/functions/hash-hmac.xml new file mode 100644 index 0000000000..95adeeab2c --- /dev/null +++ b/reference/hash/functions/hash-hmac.xml @@ -0,0 +1,123 @@ + + + + + hash_hmac + Generate a keyed hash value using the HMAC method + + + &reftitle.description; + + stringhash_hmac + stringalgo + stringdata + stringkey + boolraw_output + + + + + &reftitle.parameters; + + + + algo + + + Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) + + + + + data + + + Message to be hashed. + + + + + key + + + Shared secret key used for generating the HMAC variant of the message digest. + + + + + raw_output + + + When set to &true;, outputs raw binary data. + Default value (&false;) outpus lowercase hexits. + + + + + + + + + &reftitle.returnvalues; + + Returns a string containing the calculated message digest as lowercase hexits + unless raw_output is set to true in which case the raw + binary representation of the message digest is returned. + + + + + &reftitle.examples; + + + <function>hash_hmac</function> example + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + hash + hash_init + Or hash_hmac_file + + + + + + + diff --git a/reference/hash/functions/hash-init.xml b/reference/hash/functions/hash-init.xml new file mode 100644 index 0000000000..3ad4a3d5b5 --- /dev/null +++ b/reference/hash/functions/hash-init.xml @@ -0,0 +1,122 @@ + + + + + + hash_init + Initialize an incremental hashing context + + + &reftitle.description; + + resourcehash_init + stringalgo + intoptions + stringkey + + + + + &reftitle.parameters; + + + + algo + + + Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) + + + + + options + + + Optional settings for hash generation, currently supports only one option: + HASH_HMAC. When specified, the key + must be specified. + + + + + key + + + When HASH_HMAC is specified for options, + a shared secret key to be used with the HMAC hashing method must be supplied in this + parameter. + + + + + + + + + &reftitle.returnvalues; + + Returns a Hashing Context resource for use with hash_update, + hash_update_stream, hash_update_file, + and hash_final. + + + + + &reftitle.examples; + + + Incremental hashing example + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + hash + hash_file + hash_hmac + Or hash_hmac_file + + + + + + + diff --git a/reference/hash/functions/hash-update-file.xml b/reference/hash/functions/hash-update-file.xml new file mode 100644 index 0000000000..3df10cd096 --- /dev/null +++ b/reference/hash/functions/hash-update-file.xml @@ -0,0 +1,92 @@ + + + + + hash_update_file + Pump data into an active hashing context from a file + + + &reftitle.description; + + boolhash_update_file + resourcecontext + stringfilename + resourcecontext + + + + + &reftitle.parameters; + + + + context + + + Hashing context returned by hash_init. + + + + + filename + + + URL describing location of file to be hashed; Supports fopen wrappers. + + + + + context + + + Stream context as returned by stream_context_create. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.seealso; + + + hash_init + hash_update + hash_update_stream + hash_final + hash + Or hash_file + + + + + + + diff --git a/reference/hash/functions/hash-update-stream.xml b/reference/hash/functions/hash-update-stream.xml new file mode 100644 index 0000000000..21d1e3398a --- /dev/null +++ b/reference/hash/functions/hash-update-stream.xml @@ -0,0 +1,120 @@ + + + + + hash_update_stream + Pump data into an active hashing context from an open stream + + + &reftitle.description; + + inthash_update_stream + resourcecontext + resourcehandle + integerlength + + + + + &reftitle.parameters; + + + + context + + + Hashing context returned by hash_init. + + + + + handle + + + Open file handle as returned by any stream creation function. + + + + + length + + + Maximum number of characters to copy from handle + into the hashing context. + + + + + + + + + &reftitle.returnvalues; + + Actual number of bytes added to the hashing context from handle. + + + + + &reftitle.examples; + + + <function>hash_update_stream</function> example + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + hash_init + hash_update + hash_final + hash + hash_file + + + + + + + diff --git a/reference/hash/functions/hash-update.xml b/reference/hash/functions/hash-update.xml new file mode 100644 index 0000000000..9e45afcc1f --- /dev/null +++ b/reference/hash/functions/hash-update.xml @@ -0,0 +1,81 @@ + + + + + hash_update + Pump data into an active hashing context + + + &reftitle.description; + + boolhash_update + resourcecontext + stringdata + + + + + &reftitle.parameters; + + + + context + + + Hashing context returned by hash_init. + + + + + data + + + Message to be included in the hash digest. + + + + + + + + + &reftitle.returnvalues; + + Returns &true; + + + + + &reftitle.seealso; + + + hash_init + hash_update_file + hash_update_stream + Or hash_final + + + + + + + diff --git a/reference/hash/functions/hash.xml b/reference/hash/functions/hash.xml new file mode 100644 index 0000000000..2522108499 --- /dev/null +++ b/reference/hash/functions/hash.xml @@ -0,0 +1,114 @@ + + + + + hash + Generate a keyed hash value using the HMAC method + + + &reftitle.description; + + stringhash + stringalgo + stringdata + boolraw_output + + + + + &reftitle.parameters; + + + + algo + + + Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) + + + + + data + + + Message to be hashed. + + + + + raw_output + + + When set to &true;, outputs raw binary data. + Default value (&false;) outpus lowercase hexits. + + + + + + + + + &reftitle.returnvalues; + + Returns a string containing the calculated message digest as lowercase hexits + unless raw_output is set to true in which case the raw + binary representation of the message digest is returned. + + + + + &reftitle.examples; + + + A <function>hash</function> example + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + hash_file + hash_hmac + Or hash_init + + + + + + + diff --git a/reference/hash/reference.xml b/reference/hash/reference.xml new file mode 100644 index 0000000000..226e810acd --- /dev/null +++ b/reference/hash/reference.xml @@ -0,0 +1,51 @@ + + + + hash Functions + hash + + +
+ &reftitle.intro; + + Message Digest (hash) engine. Allows direct or incremental processing + of arbitrary length messages using a variety of hashing algorithms. + +
+
+ &reftitle.required; + + The Hash extension requires no external libraries and is enabled by + default as of PHP 5.1.2. It may be explicitly disabled by using the + --disable-hash switch to configure. Earlier versions of PHP may + incorporate the Hash extension by installing the + PECL module. + +
+ + + &reference.hash.constants; + + &reference.hash.functions; + + +