...

...

@@ -1,6 +1,6 @@

1

1

<?xml version="1.0" encoding="utf-8"?>

2

2

<!-- $Revision$ -->

3

-

<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.openssl-random-pseudo-bytes">

3

+

<refentry xml:id="function.openssl-random-pseudo-bytes" xmlns="http://docbook.org/ns/docbook">

4

4

<refnamediv>

5

5

<refname>openssl_random_pseudo_bytes</refname>

6

6

<refpurpose>Generate a pseudo-random string of bytes</refpurpose>

...

...

@@ -11,7 +11,7 @@

11

11

<methodsynopsis>

12

12

<type>string</type><methodname>openssl_random_pseudo_bytes</methodname>

13

13

<methodparam><type>int</type><parameter>length</parameter></methodparam>

14

-

<methodparam choice="opt"><type>bool</type><parameter role="reference">crypto_strong</parameter></methodparam>

14

+

<methodparam choice="opt"><type>bool</type><parameter role="reference">strong_result</parameter><initializer>&null;</initializer></methodparam>

15

15

</methodsynopsis>

16

16

<para>

17

17

Generates a <type>string</type> of pseudo-random bytes, with the number of bytes

...

...

@@ -19,7 +19,7 @@

19

19

</para>

20

20

<para>

21

21

It also indicates if a cryptographically strong algorithm was used to produce the

22

-

pseudo-random bytes, and does this via the optional <parameter>crypto_strong</parameter>

22

+

pseudo-random bytes, and does this via the optional <parameter>strong_result</parameter>

23

23

parameter. It's rare for this to be &false;, but some systems may be broken or old.

24

24

</para>

25

25

</refsect1>

...

...

@@ -32,16 +32,16 @@

32

32

<term><parameter>length</parameter></term>

33

33

<listitem>

34

34

<para>

35

-

The length of the desired string of bytes. Must be a positive integer. PHP will

35

+

The length of the desired string of bytes. Must be a positive integer less than or equal to <literal>2147483647</literal>. PHP will

36

36

try to cast this parameter to a non-null integer to use it.

37

37

</para>

38

38

</listitem>

39

39

</varlistentry>

40

40

<varlistentry>

41

-

<term><parameter>crypto_strong</parameter></term>

41

+

<term><parameter>strong_result</parameter></term>

42

42

<listitem>

43

43

<para>

44

-

If passed into the function, this will hold a <type>boolean</type> value that determines

44

+

If passed into the function, this will hold a <type>bool</type> value that determines

45

45

if the algorithm used was "cryptographically strong", e.g., safe for usage with GPG,

46

46

passwords, etc. &true; if it did, otherwise &false;

47

47

</para>

...

...

@@ -54,10 +54,45 @@

54

54

<refsect1 role="returnvalues">

55

55

&reftitle.returnvalues;

56

56

<para>

57

-

Returns the generated &string; of bytes on success, &return.falseforfailure;.

57

+

Returns the generated &string; of bytes.

58

58

</para>

59

59

</refsect1>

60

60

61

+

<refsect1 role="errors">

62

+

&reftitle.errors;

63

+

<para>

64

+

<function>openssl_random_pseudo_bytes</function> throws an <classname>Exception</classname>

65

+

on failure.

66

+

</para>

67

+

</refsect1>

68

+

69

+

<refsect1 role="changelog">

70

+

&reftitle.changelog;

71

+

<informaltable>

72

+

<tgroup cols="2">

73

+

<thead>

74

+

<row>

75

+

<entry>&Version;</entry>

76

+

<entry>&Description;</entry>

77

+

</row>

78

+

</thead>

79

+

<tbody>

80

+

<row>

81

+

<entry>8.0.0</entry>

82

+

<entry>

83

+

<parameter>strong_result</parameter> is nullable now.

84

+

</entry>

85

+

</row>

86

+

<row>

87

+

<entry>7.4.0</entry>

88

+

<entry>

89

+

The function no longer returns &false; on failure, but throws an <classname>Exception</classname> instead.

90

+

</entry>

91

+

</row>

92

+

</tbody>

93

+

</tgroup>

94

+

</informaltable>

95

+

</refsect1>

61

96

<refsect1 role="examples">

62

97

&reftitle.examples;

63

98

<para>

...

...

@@ -66,7 +101,7 @@

66

101

<programlisting role="php">

67

102

<![CDATA[

68

103

<?php

69

-

for ($i = -1; $i <= 4; $i++) {

104

+

for ($i = 1; $i <= 4; $i++) {

70

105

$bytes = openssl_random_pseudo_bytes($i, $cstrong);

71

106

$hex = bin2hex($bytes);

72

107

...

...

@@ -81,14 +116,6 @@ for ($i = -1; $i <= 4; $i++) {

81

116

&example.outputs.similar;

82

117

<screen>

83

118

<![CDATA[

84

-

Lengths: Bytes: -1 and Hex: 0

85

-

string(0) ""

86

-

NULL

87

-

88

-

Lengths: Bytes: 0 and Hex: 0

89

-

string(0) ""

90

-

NULL

91

-

92

119

Lengths: Bytes: 1 and Hex: 2

93

120

string(2) "42"

94

121

bool(true)

...

...

@@ -117,12 +144,10 @@ bool(true)

117

144

<member><function>random_bytes</function></member>

118

145

<member><function>bin2hex</function></member>

119

146

<member><function>crypt</function></member>

120

-

<member><function>mt_rand</function></member>

121

-

<member><function>uniqid</function></member>

147

+

<member><function>random_int</function></member>

122

148

</simplelist>

123

149

</refsect1>

124

150

</refentry>

125

-

126

151

<!-- Keep this comment at the end of the file

127

152

Local variables:

128

153

mode: sgml

129

154