1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-regenerate-id">
<refnamediv>
<refname>session_regenerate_id</refname>
<refpurpose>
Update the current session id with a newly generated one
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>session_regenerate_id</methodname>
<methodparam choice="opt"><type>bool</type><parameter>delete_old_session</parameter><initializer>&false;</initializer></methodparam>
</methodsynopsis>
<para>
<function>session_regenerate_id</function> will replace the current
session id with a new one, and keep the current session information.
</para>
<para>
When <link linkend="ini.session.use-trans-sid">session.use_trans_sid</link>
is enabled, output must be started after <function>session_regenerate_id</function>
call. Otherwise, old session ID is used.
</para>
<warning>
<para>
Currently, session_regenerate_id does not handle an unstable network well,
e.g. Mobile and WiFi network. Therefore, you may experience a lost
session by calling session_regenerate_id.
</para>
<para>
You should not destroy old session data immediately, but should use
destroy time-stamp and control access to old session ID. Otherwise,
concurrent access to page may result in inconsistent state, or you
may have lost session, or it may cause client (browser) side race
condition and may create many session ID needlessly. Immediate
session data deletion disables session hijack attack detection
and prevention also.
</para>
</warning>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>delete_old_session</parameter></term>
<listitem>
<para>
Whether to delete the old associated session file or not.
You should not delete old session if you need to avoid
races caused by deletion or detect/avoid session hijack
attacks.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>session_regenerate_id</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
// NOTE: This code is not fully working code, but an example!
session_start();
// Check destroyed time-stamp
if (isset($_SESSION['destroyed'])
&& $_SESSION['destroyed'] < time() - 300) {
// Should not happen usually. This could be attack or due to unstable network.
// Remove all authentication status of this users session.
remove_all_authentication_flag_from_active_sessions($_SESSION['userid']);
throw(new DestroyedSessionAccessException);
}
$old_sessionid = session_id();
// Set destroyed timestamp
$_SESSION['destroyed'] = time(); // session_regenerate_id() saves old session data
// Simply calling session_regenerate_id() may result in lost session, etc.
// See next example.
session_regenerate_id();
// New session does not need destroyed timestamp
unset($_SESSION['destroyed']);
$new_sessionid = session_id();
echo "Old Session: $old_sessionid<br />";
echo "New Session: $new_sessionid<br />";
print_r($_SESSION);
?>
]]>
</programlisting>
</example>
</para>
<para>
Current session module does not handle unstable network well. You should
manage session ID to avoid lost session by session_regenerate_id.
</para>
<para>
<example>
<title>Avoiding lost session by <function>session_regenerate_id</function></title>
<programlisting role="php">
<![CDATA[
<?php
// NOTE: This code is not fully working code, but an example!
// my_session_start() and my_session_regenerate_id() avoid lost sessions by
// unstable network. In addition, this code may prevent exploiting stolen
// session by attackers.
function my_session_start() {
session_start();
if (isset($_SESSION['destroyed'])) {
if ($_SESSION['destroyed'] < time()-300) {
// Should not happen usually. This could be attack or due to unstable network.
// Remove all authentication status of this users session.
remove_all_authentication_flag_from_active_sessions($_SESSION['userid']);
throw(new DestroyedSessionAccessException);
}
if (isset($_SESSION['new_session_id'])) {
// Not fully expired yet. Could be lost cookie by unstable network.
// Try again to set proper session ID cookie.
// NOTE: Do not try to set session ID again if you would like to remove
// authentication flag.
session_commit();
session_id($_SESSION['new_session_id']);
// New session ID should exist
session_start();
return;
}
}
}
function my_session_regenerate_id() {
// New session ID is required to set proper session ID
// when session ID is not set due to unstable network.
$new_session_id = session_create_id();
$_SESSION['new_session_id'] = $new_session_id;
// Set destroy timestamp
$_SESSION['destroyed'] = time();
// Write and close current session;
session_commit();
// Start session with new session ID
session_id($new_session_id);
ini_set('session.use_strict_mode', 0);
session_start();
ini_set('session.use_strict_mode', 1);
// New session does not need them
unset($_SESSION['destroyed']);
unset($_SESSION['new_session_id']);
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>session_id</function></member>
<member><function>session_create_id</function></member>
<member><function>session_start</function></member>
<member><function>session_destroy</function></member>
<member><function>session_reset</function></member>
<member><function>session_name</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
|
