*=============================================================================*
| NOVITA' DELLA 2.5.7 x GLI SVILUPPATORI: RENDIAMO SICURE LE NOSTRE VARIABILI |
*=============================================================================*
                                                                   v.20060113


INTRODUZIONE
------------
La versione 2.5.7 di FlatNuke porta con se', tra le novita' piu' rilevanti,
alcune migliorie per quanto riguarda il fronte della sicurezza interna.

E' stata integrata nel pacchetto ufficiale la libreria esterna "sanitize"
(http://www.owasp.org/) che fornisce una serie di funzioni utili a processare
le variabili utilizzate in un programma, rendendole sicure secondo vari gradi
prestabiliti. La libreria si trova nella directory /include/ (cartella che d'ora
in avanti sara' destinata ad accogliere il codice di terze parti da utilizzare)
e viene inclusa nel file shared.php; diventa lo standard di fatto in FlatNuke
per quanto riguarda la messa in sicurezza del codice.

A fianco di questa funzione ne e' stata creata un'altra, fnsanitize(), contenuta
in shared.php, ancora piu' vicina alle esigenze specifiche di FlatNuke.


STRUTTURA
---------
Per comodita', e per rendere il codice il pi strutturato possibile, le due
singole funzioni non saranno mai richiamate direttamente (potrebbe succedere
per esempio che in un futuro le si voglia sostituire con altre senza dover
riscriverne tutti i richiami..), ma e' stata codificata una ulteriore funzione
'cappello' che usa i puntatori per eseguire, a seconda di un parametro definito,
la funzione desiderata.
La nuova funzione, che e' quella che effettivamente verra' utilizzata dallo
sviluppatore, si chiama getparam() e si trova in shared.php; la documentazione:

	function getparam($param, $opt, $sanitize)

dove:

	@param string $param    Nome del parametro
	@param string $opt      Metodo da utilizzare (POST, GET, ALL, COOKIE, SESSION)
	@param string $sanitize Puntatore a funzione che sanitizza il parametro

Se la variabile esiste, viene restituita la stringa con il contenuto sanitizzato
del parametro stesso, altrimento viene restituita una stringa vuota.


ESEMPI DI UTILIZZO
------------------
Ogni volta che deve essere utilizzata una variabile di tipo POST, GET, COOKIE o
SERVER, dobbiamo utilizzare la nuova funzione, cosi' come anche per i parametri
utilizzati all'interno delle funzioni.

Variabili di tipo $_GET (es. $_GET['mod']):
	$mod = getparam("mod", PAR_GET, SAN_FLAT);
da questo punto in poi, nel codice faremo riferimento unicamente a $mod.

Variabili di tipo $_POST (es. $_POST['mod']):
	$mod = getparam("mod", PAR_POST, SAN_FLAT);

Se abbiamo una variabile che pu essere sia di tipo GET che POST:
	$mod = getparam("mod", PAR_ALL, SAN_FLAT);

Variabili di tipo $_SERVER (es. $_SERVER['REQUEST_URI']):
	$req = getparam("REQUEST_URI", PAR_SERVER, SAN_FLAT);

Variabili di tipo $_COOKIE (es. $_COOKIE['myforum']):
	$myforum = getparam("myforum", PAR_COOKIE, SAN_FLAT);


Come detto precedentemente, quando costruisco una funzione che prende in input
una o piu' variabili, devo sanitizzare anche queste; un semplice esempio:

	function my_function($param){
		$param = getparam($param, PAR_NULL, SAN_FLAT);
		$param++;
		return $param;
	}

In questo caso il metodo utilizzato e' PAR_NULL, dato che non si tratta di una
variabile che uso per passare dei valori tramite le pagine HTML.


ATTENZIONE
----------
Alle regole generali di utilizzo, ci sono alcune eccezioni a seconda di usi
specifici delle variabili, e del loro contenuto.

La funzione fnsanitize() per esempio, elimina dalla stringa in input anche il
carattere di ritono a capo (corrispondente al carattere 10), per cui e' ovvio
che non puo' essere utilizzata nel caso in cui io debba sanitizzare ad esempio
il contenuto di una textarea; in questo caso, facendo dei test sul risultato
che si ottiene, si puo' usare una di queste due possibilita':

	$textarea = getparam("textarea", PAR_POST, SAN_NULL);

oppure:

	if(isset($_POST['textarea']))
		$textarea = $_POST['textarea'];
	else
		$textarea = "";

In entrambi i casi devo ricordarmi di gestire il caso in cui la variabile sia
valorizzata come una stringa vuota.
