sessionhandler.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 4d17b7b4947e7819ff5036715dd706be87ae4def Maintainer: seros Status: ready -->
<!-- Reviewed: no -->
<reference xml:id="class.sessionhandler" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">

 <title>La clase SessionHandler</title>
 <titleabbrev>SessionHandler</titleabbrev>

 <partintro>

  <!-- {{{ SessionHandler intro -->
  <section xml:id="sessionhandler.intro">
   &reftitle.intro;
   <para>
    <classname>SessionHandler</classname> es una clase especial que puede usarse
    para exponer el gestor de almacenamiento de sesiones interno actual de PHP por herencia.
    Existen siete métodos que envuelven las sietes retrollamadas del gestor de almacenamiento
    de sesiones (<parameter>open</parameter>, <parameter>close</parameter>,
    <parameter>read</parameter>, <parameter>write</parameter>,
    <parameter>destroy</parameter>, <parameter>gc</parameter> y
    <parameter>create_sid</parameter>). Por defecto, esta clase envolverá
    cualquier gestor de almacenamiento que esté establecido como está definido por la
    directiva de configuración <link linkend="ini.session.save-handler">session.save_handler</link>,
    el cual normalmente es <parameter>files</parameter> por
    omisión. Otros gestores de almacenamiento de sesión internos son proporcionados por
    extensiones de PHP tales como SQLite (como <parameter>sqlite</parameter>), Memcache (como
    <parameter>memcache</parameter>), y Memcached (como
    <parameter>Memcached</parameter>).
   </para>
   <para>
    Cuando se establece una simple instancia de <classname>SessionHandler</classname> como el gestor de almacenamiento usando
    <function>session_set_save_handler</function>, envolverá los gestores de almacenamiento actuales.
    Una clase que extienda de <classname>SessionHandler</classname> permite sobrescribir
    los métodos o interceptarlos o filtrarlos llamando a los métodos de la clase madre, los cuales en última instancia envolverán
    los gestores de sesiones de PHP internos.
   </para>
   <para>
    Esto permite, por ejemplo, interceptar los métodos <parameter>read</parameter> y <parameter>write</parameter>
    para encriptar/desencriptar la información de sesión y luego pasar el resultado hacia y desde la clase madre.
    De forma alternativa se podría elegir sobrescribir por completo un método como la llamada de retorno del recolector de basura
    <parameter>gc</parameter>.
   </para>
   <para>
    Ya que <classname>SessionHandler</classname> envuelve los métodos del gestor de almacenamiento interno
    actual, el ejemplo de arriba de encriptación puede aplicarse a cualquier gestor de almacenamiento interno sin
    tener que conocer los entresijos de los gestores.
   </para>
   <para>
    Para usar esta clase, primero establezca el gestor de almacenamiento que desee exponer usando
    <link linkend="ini.session.save-handler">session.save_handler</link> y luego pasar una instancia de
    <classname>SessionHandler</classname> o una que la extienda a <function>session_set_save_handler</function>.
   </para>
   <para>
    Observe que los métodos de llamda de retorno de esta clase están diseñados para ser llamados internamente por
    PHP y no para ser llamados desde código de espacio de usuario. Los valores devueltos son igualmente procesados internamente
    por PHP. Para más información sobre el flujo de trabajo de sesiones consulte <function>session_set_save_handler</function>.
   </para>
  </section>
  <!-- }}} -->

  <section xml:id="sessionhandler.synopsis">
   &reftitle.classsynopsis;

   <!-- {{{ Synopsis -->
   <classsynopsis class="class">
    <ooclass>
     <classname>SessionHandler</classname>
    </ooclass>

    <oointerface>
     <modifier>implements</modifier>
     <interfacename>SessionHandlerInterface</interfacename>
    </oointerface>

    <oointerface>
     <interfacename>SessionIdInterface</interfacename>
    </oointerface>

    <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[@role='SessionHandler'])">
     <xi:fallback/>
    </xi:include>
   </classsynopsis>
   <!-- }}} -->

  </section>

  <section xml:id="session.notes">
   &reftitle.notes;
   <warning>
    <para>
     Esta clase está diseñada para exponer el gestor de almacenamiento de sesiones interno de PHP, si quiere
     escribir sus propios gestores de almacenamiento, implemente la interfaz <classname>SessionHandlerInterface</classname>
     en lugar de extender desde <classname>SessionHandler</classname>.
    </para>
   </warning>
  </section>

  <section xml:id="sessionhandler.examples">
   &reftitle.examples;
   <example>
    <title>
     Usar <classname>SessionHandler</classname> para añadir encriptación a los gestores de almacenamiento internos de PHP.
    </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) {
    // Generate a cryptographically secure random salt using random_bytes()
    $salt = random_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);
    }
}

// interceptaremos el manejador nativo 'files', pero funcionaría igualmente
// con otros manejadores nativos internos como 'sqlite', 'memcache' o 'memcached'
// que son proporcionados por extensiones de PHP.
ini_set('session.save_handler', 'files');

$key = 'secret_string';
$handler = new EncryptedSessionHandler($key);
session_set_save_handler($handler, true);
session_start();

// proceder para establecer y recuperar valores por clave desde $_SESSION
]]>
    </programlisting>
   </example>
   <note>
    <para>
     Ya que los métodos de esta clase están diseñados para se llamados internamente por PHP como parte del flujo de trabajo normal,
     las llamadas de las clases hijas a los métodos padre (es decir, los gestores nativos internos reales) devolverán &false; a menos que
     la sesión haya sido iniciada realmente (automáticamente o explícitamente mediante <function>session_start</function>).
     Es importante considerar esto cuando se escriben unidades de pruebas donde los métodos de la clase podrían ser invocados manualmente.
    </para>
   </note>
  </section>

 </partintro>

 &reference.session.entities.sessionhandler;

</reference>
<!-- 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
-->