README PLUGINS, versione 0.0.1 formato dei plugin 1 Come creare plugins per innova. innova e` un framework, come tale ha delle strutture utilizzate per passare i dati e per specificare gli hook da eseguire a seconda del plugin avviato. Le strutture interne ad innova, con le quali si avra` a che fare se si programmano plugin sono 4: innova_options (struttura per memorizzare le opzioni inserite tramite riga di comando o eventuali file di configurazione) innova_mangle (struttura contentene i puntatori alle funzioni eseguite durante il percorso del pacchetto nel framework di innova) innova_packet (struttura descrivente il pacchetto, i suoi campi, le sue informazioni, ecc...) innova_struct (struttura generica di innova, serve per tener traccia delle informazioni principali e collegare le altre strutture, nel caso si volessero sostituire completamente) Per comprendere il funzionamento del framework, oltre alle strutture occorre conoscere altre parti, trattate qui di seguito. Se durante la prima lettura tutto sembrera` caotico, alla seconda dovrebbe essere tutto molto piu` chiaro. Abbiate fede :) =-=-=-=- =-=-=-=- =-=-=-=- =-=-=-=- =-=-=-=- =-=-=-=- =-=-=-=- =-=-=-=- =-=-=-= innova_options: char *plug_dir; char *plug_name; char *plug_opt; char *chroot; char *interface; int timeout; char **argv; int argc; * Queste sono principalmente le informazioni passate da linea di comando, * ogni plugin ha una funzione ben precisa di analisi delle opzioni, le * opzioni passate con -o ad innova sono riservate esplicitcamente al plugin e * nell'analisi della stringa passata si puo' poi andare a leggere file di * configurazione dai quali prendere piu' input, o una serie di stringhe o chi * lo sa. struct hostent *remote, *contact; struct netent *network, *retwork; struct servent *rem_serv, *loc_serv; struct protoent *protocol, *retocol; * Questa e` la serie di informaioni che delinea i 2 peer il cui traffico * verra` selezionato da innova e passato ai plugin. char *local_match_ext; char *remote_match_ext; * Nel caso si vogliano avviare delle estensioni di iptables, in fase di * analisi delle opzioni si possono riempire queste stringhe contenenti parti * di comando di iptables, ad esempio: * * local_match_ext="-m length --length 56" * * fara` si` che i pacchetti matchati, oltre alle regole imposte dal * funzionamento di innova, siano necessariamente quelli lunghi 56 byte. int (*foo_options_f)(int, char **, v_innova_options_p); void *foo; * Le funzioni e i campi "foo" sono abbastanza comuni in innova, sperando di * fornire una buona estensibilita` per i plugin non previsti al momento del * design: ho messo campi generici e puntatori a funzione, in modo che a * seconda della necessita` si possa scrivere un codice che si adatti al suo * utilizzo. * Questa funzione ad esempio viene chiamata prima di ogni inizializzazione e * se e` presente puo' essere valida per ritoccare i parametri di avvio * (l'inizializzazione non avviene solo una volta, come il cleanup, ma e` il * plugin che decide se si ritorna o meno all'esecuzione del core di innova). * In quest'ottica, poter ricalcolare le opzioni che altrimenti verrebbero * impostate solo una volta, potrebbe essere utile. -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= - innova_mangle: char *(* get_io_desc)(int *); * Torna un puntatore al nome del plugin, cosi` da poter stampare cosa * si sta avviando (certo, nulla nega di mettere all'interno del codice che * venga avviato per primo). * Restituisce la versione del formato dei plugin in modo che innova possa * verificare se e` supportata o no. int (* mangle_init)(v_innova_struct_p); * Viene chiamato nel loop principale, all'inzio di ogni "sessione". Serve per * inizializzare il plugin int (* mangle_cleanup)(v_innova_struct_p, int); * Viene chiamato alla fine di ogni "sessione": questo non vuol dire che innova * uscira`, ma a seconda del codice di ritorno di questa funzione sara` invece * possibile far si` che innova torni ad eseguire codice aspettando una nuova * sessione o quant'altro. * Il secondo argomento e` il codice di errore che ha generato il cleanup. int (* mangle_opt_parse)(v_innova_struct_p, v_innova_options_p); * E` la funzione necessaria per analizzare le opzioni del plugin, e` avviata * prima di entrare nel ciclo principale di innova ed e` tramite questa che si * puo' settare foo_options_f, in modo che le opzioni eventualmente mutino di * sessione in sessione. int (* local_mangle)(v_innova_struct_p, v_innova_packet_p); int (* remote_mangle)(v_innova_struct_p, v_innova_packet_p); * Queste sono le funzioni di manipolazioni dei pacchetti, local_mangle e` * chiamata per i pacchetti intercettati dal traffico locale, quindi quelli in * uscita dalla nostra applicazione. * La funzione remote_mangle si riferisce ai pacchetti letti da remoto, in * arrivo sulla nostra macchina. * Queste sono le funzioni che normalmente svolgono il grosso del lavoro di * innova (normalmente perche`, essendo un sistema modulare, non so a cosa * potra` portare la fantasia :) int (* io_timeexceed)(v_innova_struct_p, int *); * Questa funzione viene avviata allo scadere del timeout (se impostato e se * utilizzato dal plugin), viene usato come parametro per una select, dalla * man page si evince che se viene azzerato si evita che venga considerato * dalla syscall. #define INIT_HOOK 0 #define CLEANUP_HOOK 1 #define OPT_PARSE_HOOK 2 #define LOCAL_M_HOOK 3 #define REMOTE_M_HOOK 4 #define UNKNOW_M_HOOK 5 #define TIMEEXC_HOOK 6 int (* foo_mangle_f)(unsigned char, v_innova_struct_p, v_innova_packet_p, void *); void *foo; * I campi per espansioni generiche, la funzione foo_mangle_f viene verificata * e, se diversa da NULL, avviata prima di ogni funzione di mangle. Quando * viene avviata e` passato come primo argomento un valore da 0 a 6 (quelli * espressi nei define precedenti) in modo da indicare al plugin qual e` la * prossima funzione che viene eseguita (nel caso si voglia usare la * foo_mangle_f prima di una o piu` specifiche funzioni, o quant'altro possa * vernire in mente :) -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= - innova_packet: struct iphdr *ip; unsigned char *ip_opt; unsigned char ip_opt_len; struct tcphdr *tcp; unsigned char *tcp_opt; unsigned char tcp_opt_len; struct udphdr *udp; struct icmphdr *icmp; void *raw; int length; unsigned char *data; int data_len; * Puntatori e valori che vengono riempiti prima di passare il pacchetto alle * funzioni di mangle #define LOCAL 0 #define REMOTE 1 unsigned char IO; * IO serve per capire se un pacchetto e` in uscita (LOCAL) o se e` appena * stato ricevuto (REMOTE): il valore viene assegnato a seconda del file * descriptor dal quale e` stato letto. unsigned int sec; unsigned int usec; unsigned int mark; unsigned int diff; * Secondi e millisecondi della ricezione, mark e` l'eventuale mark di * netfilter e diff e` la differenza temporale tra questo pacchetto e * l'ultimo ricevuto sullo stesso flusso. struct innova_packet *next; * Nel caso una delle funzioni di mangle si trovi a duplicare i pacchetti, * sarebbe piu` corretto anziche` farli inviare dal plugin di mangle, usare * questo campo per creare una linked list di pacchetti che verranno inviati * seguendo il framework innova e le funzioni previste. int (* foo_packet_f)(v_innova_struct_p, v_innova_mangle_p, v_innova_packet_p); void *foo; * FIXME - quando viene usato ? controllare che l'uso della next sia correto * in fase di riinvio e di esecuzione della foo_packet_f -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= -= - innova_struct struct ipulog_handle *local; int lremotp; int rawfd; int local_nlg; int local_mark; int innova_table; int MTU, min_MSS; int ifd; * Dati usati per gestire le librerie di ulogd e i file descriptor per l'invio * dei pacchetti in uscita, per tenere informazioni relative ai 2 peer e la * gestione di essi, vengono usati dal framework innova, possono essere toccati * nei plugin nel caso si volesse cambiare radicalmente il sistema di IO. struct innova_mangle *m; struct innova_options *o; * Puntatore alle funzioni di mangle e di options. Nel caso si vogliano * cambiare (?) in modo radicale ...