mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 08:28:54 +00:00
240 lines
7.8 KiB
XML
240 lines
7.8 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<phpdoc:classref xml:id="class.sessionhandler" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<title>The SessionHandler class</title>
|
|
<titleabbrev>SessionHandler</titleabbrev>
|
|
|
|
<partintro>
|
|
|
|
<!-- {{{ SessionHandler intro -->
|
|
<section xml:id="sessionhandler.intro">
|
|
&reftitle.intro;
|
|
<para>
|
|
<classname>SessionHandler</classname> is a special class that can be used
|
|
to expose the current internal PHP session save handler by inheritance.
|
|
There are seven methods which wrap the seven internal session save handler
|
|
callbacks (<parameter>open</parameter>, <parameter>close</parameter>,
|
|
<parameter>read</parameter>, <parameter>write</parameter>,
|
|
<parameter>destroy</parameter>, <parameter>gc</parameter> and
|
|
<parameter>create_sid</parameter>). By default, this class will wrap
|
|
whatever internal save handler is set as defined by the
|
|
<link linkend="ini.session.save-handler">session.save_handler</link>
|
|
configuration directive which is usually <parameter>files</parameter> by
|
|
default. Other internal session save handlers are provided by PHP
|
|
extensions such as SQLite (as <parameter>sqlite</parameter>), Memcache (as
|
|
<parameter>memcache</parameter>), and Memcached (as
|
|
<parameter>memcached</parameter>).
|
|
</para>
|
|
<para>
|
|
When a plain instance of <classname>SessionHandler</classname> is set as the save handler using
|
|
<function>session_set_save_handler</function> it will wrap the current save handlers.
|
|
A class extending from <classname>SessionHandler</classname> allows you to override
|
|
the methods or intercept or filter them by calls the parent class methods which ultimately wrap
|
|
the internal PHP session handlers.
|
|
</para>
|
|
<para>
|
|
This allows you, for example, to intercept the <parameter>read</parameter> and <parameter>write</parameter>
|
|
methods to encrypt/decrypt the session data and then pass the result to and from the parent class.
|
|
Alternatively one might chose to entirely override a method like the garbage collection callback
|
|
<parameter>gc</parameter>.
|
|
</para>
|
|
<para>
|
|
Because the <classname>SessionHandler</classname> wraps the current internal save handler
|
|
methods, the above example of encryption can be applied to any internal save handler without
|
|
having to know the internals of the handlers.
|
|
</para>
|
|
<para>
|
|
To use this class, first set the save handler you wish to expose using
|
|
<link linkend="ini.session.save-handler">session.save_handler</link> and then pass an instance of
|
|
<classname>SessionHandler</classname> or one extending it to <function>session_set_save_handler</function>.
|
|
</para>
|
|
<para>
|
|
Please note the callback methods of this class are designed to be called internally by
|
|
PHP and are not meant to be called from user-space code. The return values are equally processed internally
|
|
by PHP. For more information on the session workflow, please refer <function>session_set_save_handler</function>.
|
|
</para>
|
|
</section>
|
|
<!-- }}} -->
|
|
|
|
<section xml:id="sessionhandler.synopsis">
|
|
&reftitle.classsynopsis;
|
|
|
|
<!-- {{{ Synopsis -->
|
|
<classsynopsis>
|
|
<ooclass>
|
|
<classname>SessionHandler</classname>
|
|
</ooclass>
|
|
|
|
<classsynopsisinfo>
|
|
<ooclass>
|
|
<classname>SessionHandler</classname>
|
|
</ooclass>
|
|
|
|
<oointerface>
|
|
<interfacename>SessionHandlerInterface</interfacename>
|
|
</oointerface>
|
|
|
|
<oointerface>
|
|
<interfacename>SessionIdInterface</interfacename>
|
|
</oointerface>
|
|
</classsynopsisinfo>
|
|
|
|
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
|
|
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.sessionhandler')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])">
|
|
<xi:fallback/>
|
|
</xi:include>
|
|
</classsynopsis>
|
|
<!-- }}} -->
|
|
|
|
</section>
|
|
|
|
<section xml:id="session.notes">
|
|
<warning>
|
|
<para>
|
|
This class is designed to expose the current internal PHP session save handler, if you want to
|
|
write your own custom save handlers, please implement the <classname>SessionHandlerInterface</classname>
|
|
interface instead of extending from <classname>SessionHandler</classname>.
|
|
</para>
|
|
</warning>
|
|
</section>
|
|
|
|
<section xml:id="sessionhandler.examples">
|
|
<example>
|
|
<title>
|
|
Using <classname>SessionHandler</classname> to add encryption to internal PHP save handlers.
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
/**
|
|
* decrypt AES 256
|
|
*
|
|
* @param data $edata
|
|
* @param string $password
|
|
* @return decrypted data
|
|
*/
|
|
function decrypt($edata, $password) {
|
|
$data = base64_decode($edata);
|
|
$salt = substr($data, 0, 16);
|
|
$ct = substr($data, 16);
|
|
|
|
$rounds = 3; // depends on key length
|
|
$data00 = $password.$salt;
|
|
$hash = array();
|
|
$hash[0] = hash('sha256', $data00, true);
|
|
$result = $hash[0];
|
|
for ($i = 1; $i < $rounds; $i++) {
|
|
$hash[$i] = hash('sha256', $hash[$i - 1].$data00, true);
|
|
$result .= $hash[$i];
|
|
}
|
|
$key = substr($result, 0, 32);
|
|
$iv = substr($result, 32,16);
|
|
|
|
return openssl_decrypt($ct, 'AES-256-CBC', $key, true, $iv);
|
|
}
|
|
|
|
/**
|
|
* crypt AES 256
|
|
*
|
|
* @param data $data
|
|
* @param string $password
|
|
* @return base64 encrypted data
|
|
*/
|
|
function encrypt($data, $password) {
|
|
// Set a random salt
|
|
$salt = openssl_random_pseudo_bytes(16);
|
|
|
|
$salted = '';
|
|
$dx = '';
|
|
// Salt the key(32) and iv(16) = 48
|
|
while (strlen($salted) < 48) {
|
|
$dx = hash('sha256', $dx.$password.$salt, true);
|
|
$salted .= $dx;
|
|
}
|
|
|
|
$key = substr($salted, 0, 32);
|
|
$iv = substr($salted, 32,16);
|
|
|
|
$encrypted_data = openssl_encrypt($data, 'AES-256-CBC', $key, true, $iv);
|
|
return base64_encode($salt . $encrypted_data);
|
|
}
|
|
|
|
class EncryptedSessionHandler extends SessionHandler
|
|
{
|
|
private $key;
|
|
|
|
public function __construct($key)
|
|
{
|
|
$this->key = $key;
|
|
}
|
|
|
|
public function read($id)
|
|
{
|
|
$data = parent::read($id);
|
|
|
|
if (!$data) {
|
|
return "";
|
|
} else {
|
|
return decrypt($data, $this->key);
|
|
}
|
|
}
|
|
|
|
public function write($id, $data)
|
|
{
|
|
$data = encrypt($data, $this->key);
|
|
|
|
return parent::write($id, $data);
|
|
}
|
|
}
|
|
|
|
// we'll intercept the native 'files' handler, but will equally work
|
|
// with other internal native handlers like 'sqlite', 'memcache' or 'memcached'
|
|
// which are provided by PHP extensions.
|
|
ini_set('session.save_handler', 'files');
|
|
|
|
$key = 'secret_string';
|
|
$handler = new EncryptedSessionHandler($key);
|
|
session_set_save_handler($handler, true);
|
|
session_start();
|
|
|
|
// proceed to set and retrieve values by key from $_SESSION
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<note>
|
|
<para>
|
|
Since this class' methods are designed to be called internally by PHP as part of the normal session workflow,
|
|
child class calls to parent methods (i.e. the actual internal native handlers) will return &false; unless
|
|
the session has actually been started (either automatically, or by explicit <function>session_start</function>.
|
|
This is important to consider when writing unit tests where the class methods might be invoked manually.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
</partintro>
|
|
|
|
&reference.session.entities.sessionhandler;
|
|
|
|
</phpdoc:classref>
|
|
<!-- 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
|
|
-->
|