svn: /phpdoc/en/trunk/reference/openssl/functions/ openssl-random-pseudo-bytes.xml

From: Date: Mon, 03 May 2010 18:53:10 +0000
Subject: svn: /phpdoc/en/trunk/reference/openssl/functions/ openssl-random-pseudo-bytes.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-6564@lists.php.net to get a copy of this message
philip Mon, 03 May 2010 18:53:10 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=298921 Log: Rewrote and expanded documentation. Changed paths: U phpdoc/en/trunk/reference/openssl/functions/openssl-random-pseudo-bytes.xml Modified: phpdoc/en/trunk/reference/openssl/functions/openssl-random-pseudo-bytes.xml =================================================================== --- phpdoc/en/trunk/reference/openssl/functions/openssl-random-pseudo-bytes.xml 2010-05-03 18:50:47 UTC (rev 298920) +++ phpdoc/en/trunk/reference/openssl/functions/openssl-random-pseudo-bytes.xml 2010-05-03 18:53:10 UTC (rev 298921) @@ -3,7 +3,7 @@ <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.openssl-random-pseudo-bytes"> <refnamediv> <refname>openssl_random_pseudo_bytes</refname> - <refpurpose>Generate a pseudo-random string</refpurpose> + <refpurpose>Generate a pseudo-random string of bytes</refpurpose> </refnamediv> <refsect1 role="description"> @@ -11,13 +11,17 @@ <methodsynopsis> <type>string</type><methodname>openssl_random_pseudo_bytes</methodname> <methodparam><type>string</type><parameter>length</parameter></methodparam> - <methodparam><type>string</type><parameter>strong</parameter></methodparam> + <methodparam choice="opt"><type>bool</type><parameter role="reference">crypto_strong</parameter></methodparam> </methodsynopsis> <para> - <function>openssl_random_pseudo_bytes</function> returns a &string; with - <parameter>length</parameter> caracters. It also indicates if it has used - a strong algorithm to produce those pseudo-random bytes in the second argument. + Generates a <type>string</type> of pseudo-random bytes, with the number of bytes + determined by the <parameter>length</parameter> parameter. </para> + <para> + It also indicates if a cryptographically strong algorithm was used to produce the + pseudo-random bytes, and does this via the optional <parameter>crypto_strong</parameter> + parameter. It's rare for this to be &false;, but some systems may be broken or old. + </para> </refsect1> <refsect1 role="parameters"> @@ -28,17 +32,18 @@ <term><parameter>length</parameter></term> <listitem> <para> - The length of the desired string. Must be a positive integer. PHP will + The length of the desired string of bytes. Must be a positive integer. PHP will try to cast this parameter to a non-null integer to use it. </para> </listitem> </varlistentry> <varlistentry> - <term><parameter>strong</parameter></term> + <term><parameter>crypto_strong</parameter></term> <listitem> <para> - If a strong algorithm was used, or not, as a boolean. - This parameter will be &null; if an error occurrs. + If passed into the function, this will hold a <type>boolean</type> value that determines + if the algorithm used was "cryptographically strong", e.g., safe for usage with GPG, + passwords, etc. &true; if it did, otherwise &false; </para> </listitem> </varlistentry> @@ -49,7 +54,7 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - Returns the generated &string; in case of success, &return.falseforfailure;. + Returns the generated &string; of bytes on success, &return.falseforfailure;. </para> </refsect1> @@ -61,35 +66,60 @@ <programlisting role="php"> <![CDATA[ <?php -for ($i = -1; $i < 5; $i++) { - var_dump(bin2hex(openssl_random_pseudo_bytes($i, $strong))); - var_dump($strong); +for ($i = -1; $i <= 4; $i++) { + $bytes = openssl_random_pseudo_bytes($i, $cstrong); + $hex = bin2hex($bytes); + + echo "Lengths: Bytes: $i and Hex: " . strlen($hex) . PHP_EOL; + var_dump($hex); + var_dump($cstrong); + echo PHP_EOL; } - ?> ]]> </programlisting> &example.outputs.similar; <screen> <![CDATA[ +Lengths: Bytes: -1 and Hex: 0 string(0) "" NULL + +Lengths: Bytes: 0 and Hex: 0 string(0) "" NULL -string(2) "f6" + +Lengths: Bytes: 1 and Hex: 2 +string(2) "42" bool(true) -string(4) "8999" + +Lengths: Bytes: 2 and Hex: 4 +string(4) "dc6e" bool(true) -string(6) "c202c9" + +Lengths: Bytes: 3 and Hex: 6 +string(6) "288591" bool(true) -string(8) "45261b8f" + +Lengths: Bytes: 4 and Hex: 8 +string(8) "ab86d144" bool(true) + ]]> </screen> </example> </para> </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><function>bin2hex</function></member> + <member><function>crypt</function></member> + <member><function>mt_rand</function></member> + <member><function>uniqid</function></member> + </simplelist> + </refsect1> </refentry> <!-- Keep this comment at the end of the file

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