cvs: phpdoc /en/reference/mhash/functions mhash-count.xml mhash-get-block-size.xml mhash-get-hash-name.xml mhash-keygen-s2k.xml mhash.xml

didou Sun Jan 21 15:14:02 2007 UTC Modified files: /phpdoc/en/reference/mhash/functions mhash-count.xml mhash-get-block-size.xml mhash-get-hash-name.xml mhash-keygen-s2k.xml mhash.xml Log: ref.mhash: switch to new style

http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/mhash/functions/mhash-count.xml?r1=1.4&r2=1.5&diff_format=u Index: phpdoc/en/reference/mhash/functions/mhash-count.xml diff -u phpdoc/en/reference/mhash/functions/mhash-count.xml:1.4 phpdoc/en/reference/mhash/functions/mhash-count.xml:1.5 --- phpdoc/en/reference/mhash/functions/mhash-count.xml:1.4 Sun Jan 21 14:14:08 2007 +++ phpdoc/en/reference/mhash/functions/mhash-count.xml Sun Jan 21 15:14:02 2007 @@ -1,20 +1,32 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <refentry id="function.mhash-count"> <refnamediv> <refname>mhash_count</refname> <refpurpose>Get the highest available hash id</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>mhash_count</methodname> <void/> </methodsynopsis> <para> - <function>mhash_count</function> returns the highest available hash - id. Hashes are numbered from 0 to this hash id. + Gets the highest available hash id. </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the highest available hash id. Hashes are numbered from 0 to this + hash id. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Traversing all hashes</title> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/mhash/functions/mhash-get-block-size.xml?r1=1.3&r2=1.4&diff_format=u Index: phpdoc/en/reference/mhash/functions/mhash-get-block-size.xml diff -u phpdoc/en/reference/mhash/functions/mhash-get-block-size.xml:1.3 phpdoc/en/reference/mhash/functions/mhash-get-block-size.xml:1.4 --- phpdoc/en/reference/mhash/functions/mhash-get-block-size.xml:1.3 Sun Jan 21 14:14:09 2007 +++ phpdoc/en/reference/mhash/functions/mhash-get-block-size.xml Sun Jan 21 15:14:02 2007 @@ -1,24 +1,61 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <refentry id="function.mhash-get-block-size"> <refnamediv> <refname>mhash_get_block_size</refname> <refpurpose>Get the block size of the specified hash</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>mhash_get_block_size</methodname> <methodparam><type>int</type><parameter>hash</parameter></methodparam> </methodsynopsis> <para> - <function>mhash_get_block_size</function> is used to get the size - of a block of the specified <parameter>hash</parameter>. + Gets the size of a block of the specified <parameter>hash</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>hash</parameter></term> + <listitem> + <para> + The hash id. One of the <literal>MHASH_XXX</literal> constants. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - <function>mhash_get_block_size</function> takes one argument, the - <parameter>hash</parameter> and returns the size in bytes or - &false;, if the <parameter>hash</parameter> does not exist. + Returns the size in bytes or &false;, if the <parameter>hash</parameter> + does not exist. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>mhash_get_block_size</function> Example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +echo mhash_get_block_size(MHASH_MD5); // 16 + +?> +]]> + </programlisting> + </example> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/mhash/functions/mhash-get-hash-name.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/mhash/functions/mhash-get-hash-name.xml diff -u phpdoc/en/reference/mhash/functions/mhash-get-hash-name.xml:1.6 phpdoc/en/reference/mhash/functions/mhash-get-hash-name.xml:1.7 --- phpdoc/en/reference/mhash/functions/mhash-get-hash-name.xml:1.6 Sun Jan 21 14:14:09 2007 +++ phpdoc/en/reference/mhash/functions/mhash-get-hash-name.xml Sun Jan 21 15:14:02 2007 @@ -1,43 +1,59 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> +<!-- $Revision: 1.7 $ --> <refentry id="function.mhash-get-hash-name"> <refnamediv> <refname>mhash_get_hash_name</refname> <refpurpose>Get the name of the specified hash</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>mhash_get_hash_name</methodname> <methodparam><type>int</type><parameter>hash</parameter></methodparam> </methodsynopsis> <para> - <function>mhash_get_hash_name</function> is used to get the name - of the specified hash. + Gets the name of the specified <parameter>hash</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - <function>mhash_get_hash_name</function> takes the hash id as an - argument and returns the name of the hash or &false;, if the hash - does not exist. + <variablelist> + <varlistentry> + <term><parameter>hash</parameter></term> + <listitem> + <para> + The hash id. One of the <literal>MHASH_XXX</literal> constants. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the name of the hash or &false;, if the hash does not exist. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>mhash_get_hash_name</function> example</title> <programlisting role="php"> <![CDATA[ <?php -$hash = MHASH_MD5; -echo mhash_get_hash_name($hash); +echo mhash_get_hash_name(MHASH_MD5); // MD5 + ?> ]]> </programlisting> - &example.outputs; - <screen> -<![CDATA[ - MD5 -]]> - </screen> </example> </para> </refsect1> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/mhash/functions/mhash-keygen-s2k.xml?r1=1.4&r2=1.5&diff_format=u Index: phpdoc/en/reference/mhash/functions/mhash-keygen-s2k.xml diff -u phpdoc/en/reference/mhash/functions/mhash-keygen-s2k.xml:1.4 phpdoc/en/reference/mhash/functions/mhash-keygen-s2k.xml:1.5 --- phpdoc/en/reference/mhash/functions/mhash-keygen-s2k.xml:1.4 Sun Jan 21 14:14:09 2007 +++ phpdoc/en/reference/mhash/functions/mhash-keygen-s2k.xml Sun Jan 21 15:14:02 2007 @@ -1,12 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <refentry id="function.mhash-keygen-s2k"> <refnamediv> <refname>mhash_keygen_s2k</refname> <refpurpose>Generates a key</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>mhash_keygen_s2k</methodname> <methodparam><type>int</type><parameter>hash</parameter></methodparam> @@ -15,16 +16,12 @@ <methodparam><type>int</type><parameter>bytes</parameter></methodparam> </methodsynopsis> <para> - <function>mhash_keygen_s2k</function> generates a key that is - <parameter>bytes</parameter> long, from a user given password. + Generates a key according to the <parameter>hash</parameter> given a user + provided <parameter>password</parameter>. + </para> + <para> This is the Salted S2K algorithm as specified in the OpenPGP - document (RFC 2440). That algorithm will use the specified - <parameter>hash</parameter> algorithm to create the key. - The <parameter>salt</parameter> must be different and random - enough for every key you generate in order to create different keys. - That salt must be known when you check the keys, thus it is - a good idea to append the key to it. Salt has a fixed length - of 8 bytes and will be padded with zeros if you supply less bytes. + document (<ulink url="&url.rfc;2440">RFC 2440</ulink>). </para> <para> Keep in mind that user supplied passwords are not really suitable @@ -35,6 +32,58 @@ supplied key. </para> </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>hash</parameter></term> + <listitem> + <para> + The hash id used to create the key. + One of the <literal>MHASH_XXX</literal> constants. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>password</parameter></term> + <listitem> + <para> + User supplied password. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>salt</parameter></term> + <listitem> + <para> + Must be different and random enough for every key you generate in + order to create different keys. That salt must be known when you check + the keys, thus it is a good idea to append the key to it. Salt has a + fixed length of 8 bytes and will be padded with zeros if you supply + less bytes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>bytes</parameter></term> + <listitem> + <para> + The key length, in bytes. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the generated key as a string, or &false; on error. + </para> + </refsect1> </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/mhash/functions/mhash.xml?r1=1.3&r2=1.4&diff_format=u Index: phpdoc/en/reference/mhash/functions/mhash.xml diff -u phpdoc/en/reference/mhash/functions/mhash.xml:1.3 phpdoc/en/reference/mhash/functions/mhash.xml:1.4 --- phpdoc/en/reference/mhash/functions/mhash.xml:1.3 Sun Jan 21 14:14:09 2007 +++ phpdoc/en/reference/mhash/functions/mhash.xml Sun Jan 21 15:14:02 2007 @@ -1,12 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <refentry id="function.mhash"> <refnamediv> <refname>mhash</refname> <refpurpose>Compute hash</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>mhash</methodname> <methodparam><type>int</type><parameter>hash</parameter></methodparam> @@ -15,12 +16,50 @@ </methodsynopsis> <para> <function>mhash</function> applies a hash function specified by - <parameter>hash</parameter> to the <parameter>data</parameter> and - returns the resulting hash (also called digest). If the <parameter> key</parameter> - is specified it will return the resulting HMAC. HMAC is keyed hashing - for message authentication, or simply a message digest that depends on - the specified key. Not all algorithms supported in mhash can be used in - HMAC mode. In case of an error returns &false;. + <parameter>hash</parameter> to the <parameter>data</parameter>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>hash</parameter></term> + <listitem> + <para> + The hash id. One of the <literal>MHASH_XXX</literal> constants. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>data</parameter></term> + <listitem> + <para> + The user input, as a string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>key</parameter></term> + <listitem> + <para> + If specified, the function will return the resulting HMAC instead. + HMAC is keyed hashing for message authentication, or simply a message + digest that depends on the specified key. Not all algorithms + supported in mhash can be used in HMAC mode. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the resulting hash (also called digest) or HMAC as a string, or + &false; on errors. </para> </refsect1> </refentry>