svn: /phpdoc/en/trunk/ language-snippets.ent reference/csprng/functions/random-bytes.xml reference/csprng/functions/random-int.xml

From: Date: Mon, 21 Sep 2015 12:17:12 +0000
Subject: svn: /phpdoc/en/trunk/ language-snippets.ent reference/csprng/functions/random-bytes.xml reference/csprng/functions/random-int.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-13750@lists.php.net to get a copy of this message
aharvey Mon, 21 Sep 2015 12:17:12 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=337871 Log: Move the description of CSPRNG sources to a snippet. Changed paths: U phpdoc/en/trunk/language-snippets.ent U phpdoc/en/trunk/reference/csprng/functions/random-bytes.xml U phpdoc/en/trunk/reference/csprng/functions/random-int.xml Modified: phpdoc/en/trunk/language-snippets.ent =================================================================== --- phpdoc/en/trunk/language-snippets.ent 2015-09-21 12:17:07 UTC (rev 337870) +++ phpdoc/en/trunk/language-snippets.ent 2015-09-21 12:17:12 UTC (rev 337871) @@ -2114,6 +2114,46 @@ </varlistentry> '> +<!-- csprng snippets --> +<!ENTITY csprng.sources ' +<para xmlns="http://docbook.org/ns/docbook"> + The sources of randomness used for this function are as follows: +</para> +<itemizedlist xmlns="http://docbook.org/ns/docbook"> + <listitem> + <simpara> + <!-- TODO: link this to an MSDN link or similar --> + On Windows, <function>CryptGenRandom</function> will always be used. + </simpara> + </listitem> + <listitem> + <simpara> + On other platforms, <function>arc4random_buf</function> will be used if it + is available. This is generally only true on BSD derivatives or systems + with libbsd. + </simpara> + </listitem> + <listitem> + <simpara> + Failing the above, <filename>/dev/arandom</filename> will be used if + available. + </simpara> + </listitem> + <listitem> + <simpara> + If <filename>/dev/arandom</filename> is unavailable, then + <filename>/dev/urandom</filename> will be used as the final fallback. + </simpara> + </listitem> + <listitem> + <simpara> + If none of the aforementioned sources are available, then an + <classname>Error</classname> will be thrown. + </simpara> + </listitem> +</itemizedlist> +'> + <!-- Migration Guide snippets --> <!ENTITY migration56.openssl.peer-verification ' <para xmlns="http://docbook.org/ns/docbook"> Modified: phpdoc/en/trunk/reference/csprng/functions/random-bytes.xml =================================================================== --- phpdoc/en/trunk/reference/csprng/functions/random-bytes.xml 2015-09-21 12:17:07 UTC (rev 337870) +++ phpdoc/en/trunk/reference/csprng/functions/random-bytes.xml 2015-09-21 12:17:12 UTC (rev 337871) @@ -14,34 +14,11 @@ <methodparam><type>int</type><parameter>length</parameter></methodparam> </methodsynopsis> <para> - Generates an arbitrary length string of cryptographic random bytes that are suitable for use in cryptography when - generating salts, keys and initialization vectors. + Generates an arbitrary length string of cryptographic random bytes that are + suitable for cryptographic use, such as when generating salts, keys or + initialization vectors. </para> - <para> - The sources of random are as follows: - </para> - <itemizedlist> - <listitem> - <simpara> - On Windows <function>CryptGenRandom</function> is used exclusively - </simpara> - </listitem> - <listitem> - <simpara> - <function>arc4random_buf</function> is used if it is available (generally BSD specific) - </simpara> - </listitem> - <listitem> - <simpara> - <filename>/dev/arandom</filename> is used where available - </simpara> - </listitem> - <listitem> - <simpara> - <filename>/dev/urandom</filename> is used where none of the above is available - </simpara> - </listitem> - </itemizedlist> + &csprng.sources; </refsect1><!-- }}} --> <refsect1 role="parameters"><!-- {{{ --> Modified: phpdoc/en/trunk/reference/csprng/functions/random-int.xml =================================================================== --- phpdoc/en/trunk/reference/csprng/functions/random-int.xml 2015-09-21 12:17:07 UTC (rev 337870) +++ phpdoc/en/trunk/reference/csprng/functions/random-int.xml 2015-09-21 12:17:12 UTC (rev 337871) @@ -15,34 +15,11 @@ <methodparam><type>int</type><parameter>max</parameter></methodparam> </methodsynopsis> <para> - Generates cryptographic random integers that are suitable for use where unbiased results are critical - (e.g. shuffling a Poker deck). + Generates cryptographic random integers that are suitable for use where + unbiased results are critical, such as when shuffling a deck of cards for a + poker game. </para> - <para> - The sources of random are as follows: - </para> - <itemizedlist> - <listitem> - <simpara> - On Windows <function>CryptGenRandom</function> is used exclusively - </simpara> - </listitem> - <listitem> - <simpara> - <function>arc4random_buf</function> is used if it is available (generally BSD specific) - </simpara> - </listitem> - <listitem> - <simpara> - <filename>/dev/arandom</filename> is used where available - </simpara> - </listitem> - <listitem> - <simpara> - <filename>/dev/urandom</filename> is used where none of the above is available - </simpara> - </listitem> - </itemizedlist> + &csprng.sources; </refsect1><!-- }}} --> <refsect1 role="parameters"><!-- {{{ -->

« previous php.doc.cvs (#13750) next »