////////////////////////////////////////////////////////////////////////////////
Copyright 2013, 2015 Newport Software Technologies, UNICEN

This file is part of XGAP.

XGAP is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

XGAP is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with XGAP.  If not, see <http://www.gnu.org/licenses/>.
////////////////////////////////////////////////////////////////////////////////

:encoding: utf-8
= Personalización de la seguridad =
:lang: es
:toc:
:imagesdir: ../img/
:icons:
:iconsdir: ../img/icons
:ascii-ids:

Esta sección describe la manera de personalizar los objetos de Seguridad
empleados por XGAP, para adecuarlos a las necesidades específicas de una
aplicación. Para ello se explica primero el funcionamiento de las clases
e interfaces que definen los mecanismos de seguridad predeterminados y a
continuación se brinda un ejemplo para ilustrar su extensión.

== Esquema de seguridad ==

Las interfaces que definen el esquema de seguridad se encuentran dentro del
motor, en el archivo `interfaces/iSeguridad.inc.php` y son:

- `iSeguridadConexion`
- `iSeguridad`

Las clases que provean la seguridad de una aplicación deben implementar estas
interfaces.

La implementación provista por XGAP se encuentra en el archivo
`clases/seguridad.inc.php` y está compuesta por las clases:

- `SeguridadConexionBase`, implementa `iSeguridadConexion`
- `SeguridadConexion`, hereda de `SeguridadConexionBase`
- `Seguridad`, implementa `iSeguridad`

.Estructura de clases de seguridad
[plantuml]
----
interface iSeguridad
interface iSeguridadConexion
abstract SeguridadConexionBase

iSeguridadConexion <|-- SeguridadConexionBase
SeguridadConexionBase <|-- SeguridadConexion
iSeguridad <|-- Seguridad
Seguridad o-- SeguridadConexion
----

La clase `Seguridad` contiene la lógica necesaria para poder determinar:

- Si un usuario puede o no ver una página determinada
- Obtener las páginas permitidas para un determinado usuario en un determinado
  rol
- Obtener los roles disponibles para un determinado usuario
- Actualizar los permisos de seguridad para un usuario determinado en una
  aplicación determinada.

El objetivo de la clase `SeguridadConexion` es servir de nexo entre la clase
`Seguridad` y la clase de conexión, de manera que la clase `Seguridad` sea
independiente de la base de datos.

== Definición de seguridad personalizada ==

Para personalizar la implementación de seguridad en una aplicación se debe
informar a XGAP qué clases alternativas se van a usar. Para ello existen tres
parámetros de configuración:

`clase_seguridad`:: Indica la implementación de la interfaz `iSeguridad` que
debe emplearse. Si este parámetro no es proporcionado, se emplea la clase
predeterminada.
`clase_seguridad_conexion`:: Indica la implementación de la interfaz
`iSeguridadConexion` que debe emplearse. Si este parámetro no es proporcionado,
se emplea la clase predeterminada.
`archivo_seguridad`:: Especifica el archivo que contiene las clases de
seguridad a emplear, definidas por los parámetros `clase_seguridad` y
`clase_seguridad_conexion`. Ambas clases deben definirse en este archivo.

NOTE: Si se define el parámetro `archivo_seguridad` pero no
`clase_seguridad` o `clase_seguridad_conexion`, la clase correspondiente es
ignorada por XGAP a pesar de estar definida en el archivo indicado.

Ahora nos concentraremos en lo que podemos definir dentro de este archivo.

La manera más simple de personalizar la seguridad consiste en definir nuevas
clases que hereden de las predeterminadas; de este modo sólo será necesario
reimplementar los métodos que proveen la funcionalidad que se desea modificar.
Por otro lado, nada impide que las aplicaciones implementen clases de seguridad
completamente nuevas e independientes de las predeterminadas; el único requisito
es que implementen las interfaces mencionadas.

El ejemplo que se da a continuación muestra el contenido mínimo que debe tener
un archivo de personalización con clases de seguridad que heredan de las
predeterminadas.

.Archivo mínimo para personalización de seguridad
====
[source,php]
----
<?php
class SeguridadConexionApp extends SeguridadConexion {
    /**
     * @param conexión $conexion
     */
    public function __construct($conexion) {
        parent::__construct($conexion);
    }
}

class SeguridadApp extends Seguridad {
    public function __construct($seguridad_conexion) {
        parent::__construct($seguridad_conexion);
    }
}
----
====

En este archivo se definen las clases `SeguridadApp` y `SeguridadConexionApp` como
subclases de `Seguridad` y `SeguridadConexion`.

Para que XGAP utilice estas clases, es necesario cambiar los parámetros de
configuración de la aplicación. Si el archivo de configuración tiene el nombre
`seguridadapp.inc.php`, entonces habrá que definir las siguientes constantes
dentro del archivo `conf.inc.php`:

[source,php]
----
<?php
define('XGAP_CONF_ARCHIVO_SEGURIDAD', 'seguridadapp.inc.php');
define('XGAP_CONF_CLASE_SEGURIDAD', 'SeguridadApp');
define('XGAP_CONF_CLASE_SEGURIDAD_CONEXION', 'SeguridadConexionApp');
----

El ejemplo anterior simplemente define nuevas clases, pero no modifica la
implementación de la seguridad. A continuación se provee un ejemplo más
completo.

.Personalización de seguridad con métodos reimplementados
====
[source,php]
----
<?php
class SeguridadConexionApp extends SeguridadConexionBase {
    /**
      * @param conexión
      */
    public function __construct($conexion) {
        parent::__construct($conexion);
    }

    /**
      * Retorna una consulta que agrega seguridad a una consulta dada.
      * @param string $consulta
      * @return mixed string
      */
    public function obtenerConsultaSegura($consulta) {
        // Hacer cambios a $consulta aquí
        return $consulta;
    }

    /**
      * Retorna una consulta SQL para comprobar la seguridad de una página.
      * @param string $pagina
      * @return mixed boolean | lista de permisos
      */
    public function verificarSeguridadPagina($pagina) {
        // .....
    }

    public function borrarPermisosDePagina($aplicacion, $rol_usuario,
            $tipo_pagina) {
        // .....
    }

    public function agregarPaginaSiNoExiste($aplicacion, $pagina) {
        // .....
    }

    public function agregarPermisoAPagina($aplicacion, $rol_usuario, $pagina,
            $operaciones) {
        // .....
    }

    public function obtenerPaginasPermitidas($aplicacion, $rol_usuario,
            $tipo_pagina) {
        // .....
    }

    public function obtenerRolesDisponibles() {
        // .....
    }
}

class SeguridadApp extends Seguridad {
    public function __construct($seguridad_conexion) {
        parent::__construct($seguridad_conexion);
    }

    public function verificarSeguridad($error) {
        // .....
    }
}
----
====

TIP: La implementación provista por XGAP puede observarse en el archivo `clases/seguridad.inc.php` del motor.

// vim: set syntax=asciidoc textwidth=80: