svn: /phpdoc/en/trunk/ language-snippets.ent reference/csprng/functions/random-bytes.xml reference/csprng/functions/random-int.xml
| From: | Adam Harvey | 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"><!-- {{{ -->