File: readme.es

@Sauth README file.

sauth es una clase que nos permite implementar en todo 
nuestro site un sistema muy facil de usar de autentificacion y
seguimiento de usuarios.
Este seguimiento se realiza mediante un uniqueid de sesion unico
que es generado en el momento de inicio de sesion, justo despues
de producirse la autentificacion (validada por supuesto).
De este modo podemos usar esta clase como complemento a otras
para gestionar por ejemplo un site orientado al comercion 
elctronico.

La autentificacion puede llevar de forma opcional el modo
paranioco, que nos valida ademas de por el uniqueid por la ip.
Esto ha sido incluido de forma opcional debido a problemas 
detectados con algunos proxys.

Como otra medida de seguridad esta el timeout de sesion, que 
nos hacer caducar la sesion cada x segundos en los que no hayamos
tenido ningun movimiento dentro del site (o de la parte en la 
que sea necesario autentificacion), retornandonos al sitio 
donde nos quedamos una vez nos hayamos autentificado de nuevo.

Para realizar los tests como primer paso debemos crear una base
de datos con dos tablas, una para los datos de los usuarios 
y la segunda para almacenar las sesiones de estos.

Para crear la base de datos nada mas simple que esto:

root@localhost# mysqladmin -u root -ppass create sauth
Database "sauth" created.

Y un usuario para acceder a esta base de datos:

root@localhost# mysql -u root -ppass mysql

mysql> GRANT insert, select, update, delete
    -> ON sauth.*
    -> TO sauth@localhost
    -> IDENTIFIED BY 'sauth';
Query OK, 0 rows affected (0.01 sec)

Ahora pasamos a hacer un volcado de la estructua:

mysql> use sauth;
Database changed
mysql>

Estructura de la base de datos que vamos a usar para el test:


mysql> CREATE TABLE session (
    -> id tinyint(3) unsigned NOT NULL auto_increment,
    -> uniqid char(100) NOT NULL,
    -> timestart int(20) unsigned NOT NULL,
    -> userdataid tinyint(3) unsigned NOT NULL,
    -> paranoical tinyint(1) unsigned DEFAULT '1' NOT NULL,
    -> sessionip char(15) NOT NULL,
    -> PRIMARY KEY (id),
    -> KEY id (id),
    -> UNIQUE id_2 (id, uniqid)
    -> );
Query OK, 0 rows affected (0.00 sec)

mysql> CREATE TABLE userdata (
    -> id tinyint(3) unsigned NOT NULL auto_increment,
    -> name char(15) NOT NULL,
    -> passname char(15) NOT NULL,
    -> timeout smallint(5) unsigned DEFAULT '60' NOT NULL,
    -> PRIMARY KEY (id),
    -> KEY id (id),
    -> UNIQUE id_2 (id, name)
    -> );
Query OK, 0 rows affected (0.00 sec)

Y un par de usuarios del site con los que comprobar el sistema:

mysql> INSERT INTO userdata (id, name, passname, timeout) VALUES ('', 'demo1','demo1', '60');
Query OK, 1 row affected (0.00 sec)

mysql> INSERT INTO userdata (id, name, passname, timeout) VALUES ('', 'demo2','demo2', '30');
Query OK, 1 row affected (0.00 sec)

mysql> quit;



++++++++++++++++++++++++++
Descripcion de los metodos
++++++++++++++++++++++++++

[metodos publicos]

sauth:
argumentos...:
	server......: nombre del servidor de base de datos (mysql en este caso).
	user........: nombre del usuario con permisos para atacar esta db.
	pass........: password del usuario.
	database....: nombre de la base de datos.
funcion......:
	metodo constructor.
retorno......:
	devuelve el objeto o falso si no ha sido instanciado.


StartSession:
argumentos...:
	Username....: nombre del usuario para el inicio de la sesion
	Passname....: clave de acceso del usuario para el inicio de la sesion
	ParanoicMode: indica si la session ha de ser en modo paranoia una vez
				haya tenido lugar la autentificacion con exito. este
				flag activa el seguimiento de la sesion con la ip 
				ademas de con el uniqid de la misma
funcion......:
	Inicia una nueva sesion de usuario. 
retorno......:
	devuelve el identificador (uniqid) de la sesion o falso en caso de fallo.


CheckSessionId:
argumentos...: 
	uniqid......: numero unico de identificador de session de usuario.
	UserIp`.....: ip del usuario remoto.
funcion......:
	valida el uniqid y el timeout de la session, asi como la ip si ha sido seleccionado
	en el inicio de la sesion el modo paranoia.
retorno......:
	devuelve verdadero en caso de exito o falso en caso de fallo.

++++++++++++++++++++++++++

[metodos privados]

ConnectMysql:
argumentos...:
funcion......:
	metodo de conexion al servidor mysql que contiene la base de datos con los
	usuarios y sus sesiones para el seguimiento.
retorno......: 
	verdadero en caso de realizarse la conexion con exito o falso en caso
	de fallo.		


CloseMysql:
argumentos...:
funcion......:
	cierra una conexion previamente establecida.
retorno......: 
	verdadero.


ValidateUser:
argumentos...:
funcion......:
	valida un nombre de usuario junto con su contraseña contra una base de datos.
retorno......:
	el id del registro del usuario en la base de datos en caso de exito o falso en caso
	de fallo.

GetUserData:
argumentos...:
	Selected....: nombre de los campos de donde vamos a coger los datos.
	Table.......: nombre de la tabla de donde vamos a coger los datos.
	Data........: clausualas adicionales. este argumentos es una matriz asociativa donde
				cada pareja clave/valor representa una clausula condicional a la
				consulta.
funcion......:
	devuelve una matriz simple con los datos solicitados.
retorono.....:
	la matriz con los datos solicitados o falso en caso de fallo


UpdateSessionId:
argumentos...:
	UpdateId....: id del usuario en la base de datos que ha iniciado una nueva sesion
funcion......:
	Inserta en la base de datos de sesiones una nueva sesion de usuario.
retorno......:
	Verdadero en caso de exito, falso en caso de fallo.


ExecSql:
argumentos...:
	Sql.........: sentencia sql a ejecutar.
funcion......:
	ejecuta una sentencia sql. este metodo es valido para sentencia tipo UPDATE, INSERT, etc, no
	para sentencias del tipo SELECT en las que el query devuelve un identificador o resultado
	con el cual extraer los datos.
retorno......:
	verdadero en caso de exito, falso en caso de fallo.


GetSessionId:
argumentos...:
funcion......:
	genera un unqid valido para poder iniciar la sesion.
retorno......:
	el nuevo identificador en caso de exito o falso en caso de fallo.


UpdateTimeSessionId:
argumentos...:
funcion......:
	actualiza en timeout de la sesion.
retorno......:


DeleteSessionId:
argumentos...:
funcion......:
	borra una session de usuario de la base de datos.
retorno......:



Notas
@---@

- Por lo general siempre es mas conveniente que la validacion username/password sea case sensitive
por mayor seguridad, aunque pueden haber casos en los que no importe esta medida y convenga quitar
esta propiedad. Para ello tan solo tendremos que cambiar en el metodo ValidateUser la siguiente linea:

if ((ereg("^$NameUser$", $this->UsernameSession('')))&&(ereg("^$PassUser$", $this->PasswordSession('')))){

,por esta otra:

if ((eregi("^$NameUser$", $this->UsernameSession('')))&&(eregi("^$PassUser$", $this->PasswordSession('')))){



mArKitos]|) ))  ))) [xP]
markitos@office.com