1#  -*- mode: Outline -*-# #  klips2-design-api.txt#	Richard Guy Briggs <rgb@conscoop.ottawa.on.ca>##  RCSID $Id: klips2-design-api.txt,v 1.1.1.1 2002/09/05 03:13:16 ken Exp $#* Outline Commands cheat sheet (C-c C-s to see this)        C-c C-t         Hide EVERYTHING in buffer        C-c C-a         Show EVERYTHING in buffer        C-c C-d         Hide THIS item and subitems (subtree)        C-c C-s         Show THIS item and subitems (subtree)        C-c C-c         Hide ONE item        C-c C-e         Show ONE item* Introduction	This document describes all the APIs used in this design.	Please see klips2-design.txt for an overview of the	architecture.  This document is divided into an emacs outline	mode cheat sheet, Introduction, Generic Iptables	interfaces, KLIPS2 Interfaces, Definitions and Data structures	used, and document version.** Interface:	interface description, listing origin and destination	entities, separated by an ">->" with diagram label, if it	exists within double quotes ``"''** Label:	diagram label** Name:	the name of the function used and a very brief description** Synopsis:	function form, argument position, type and return type** Arguments:	description of each argument** Description:	description of interface and function** Implementation notes:	caveats and side effects** Return value:	function return values** Example:	usage example** See also:	related documentation or further explanation* Generic Iptables interfaces** iptables(8) >-> generic match iptables(8) library** ip6tables(8) >-> generic match ip6tables(8) library	Interface:		iptables(8) >-> generic match iptables(8) library		ip6tables(8) >-> generic match ip6tables(8) library	Label:	Name:		(*generic_parse) - parse, convert and check generic options	Synopsis:		static int		generic_parse(			int c,			char **argv,			int invert,			unsigned int *flags,			const struct ipt_entry *entry,			unsigned int *nfcache,			struct ipt_entry_match **match		)	Arguments:		c			argument count		argv			text arguments to be parsed by this match		invert			invert this match?		flags			bitmap to indicate which arguments have been processed		entry			pointer to table entry associated with match		nfcache			bitmap of skb parts examined by this match		match			match data -- customised match data is contained in			"data" member	Description:		This function parses, converts and checks iptables(8)		and ip6tables(8) command line "generic" text		arguments for use by the "generic" match NetFilter kernel		module.		Input is expected to be in the form of a text string		specifying a "generic" characteristic associated with the		packet.	Implementation notes:		A data structure to store parsed and converted		arguments in a form consumable by the corresponding		kernel module is pointed to by match->data.  Replace		ipt_generic_info with the customised data structure.	Return value:		1 if an option was eaten, 0 if not.	Example:		static int		generic_parse(			int c,			char **argv,			int invert,			unsigned int *flags,			const struct ipt_entry *entry,			unsigned int *nfcache,			struct ipt_entry_match **match		) {			struct ipt_generic_info *info = (struct ipt_generic_info*)(*match)->data;			/* parse option arguments */			...			return 1;		}		struct iptables_match generic_match_lib = {			NULL,			"generic",			NETFILTER_VERSION,			IPT_ALIGN(sizeof(struct ipt_generic_info)),			IPT_ALIGN(sizeof(struct ipt_generic_info)),			&generic_help,			&generic_init,			&generic_parse,			&generic_final_check,			&generic_print,			&generic_save,			generic_opts		};		void		_init(void)		{			register_match(&generic_match_lib);		}	See also:** iptables(8) >-> GENERIC target iptables(8) library** ip6tables(8) >-> GENERIC target ip6tables(8) library		Interface:		iptables(8) >-> GENERIC target iptables(8) library		ip6tables(8) >-> GENERIC target ip6tables(8) library	Label:	Name:	Synopsis:		static int generic_parse(			int c,			char **argv,			int invert,			unsigned int *flags,			const struct ipt_entry *entry,			struct ipt_entry_target **target		)	Arguments:		c			argument count		argv			text arguments to be parsed by this target		invert			invert flag (doesn't make sense for targets)		flags			bitmap to indicate which arguments have been processed		entry			pointer to table entry associated with target		target			target data -- customised target data is contained in			"data" member	Description:		This function parses, converts and checks iptables(8)		and ip6tables(8) command line "GENERIC" text		arguments for use by the "GENERIC" target NetFilter kernel		module.		Input is expected to be in the form of a text string		specifying a "generic" characteristic to be applied to the		packet.	Implementation notes:		A data structure to store parsed and converted		arguments in a form consumable by the corresponding		kernel module is pointed to by target->data.  Replace		ipt_generic_target_info with the customised data		structure, if there is any.	Return value:		1 if an option was eaten, 0 if not.	Example:		static int		generic_parse(			int c,			char **argv,			int invert,			unsigned int *flags,			const struct ipt_entry *entry,			struct ipt_entry_target **target		) {			struct ipt_generic_target_info *info = (struct ipt_generic_target_info*)(*target)->data;			/* parse option arguments */			...			return 1;		}		struct iptables_target generic_target_lib = {			NULL,			"GENERIC",			NETFILTER_VERSION,			IPT_ALIGN(sizeof(struct ipt_generic_target_info)),			IPT_ALIGN(sizeof(struct ipt_generic_target_info)),			&generic_help,			&generic_init,			&generic_parse,			&generic_final_check,			&generic_print,			&generic_save,			generic_opts		};		void		_init(void)		{			register_target(&generic_target_lib);		}	See also:		http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html** NetFilter >-> generic match NetFilter kernel module	Interface:		NetFilter >-> generic match NetFilter kernel module	Label:	Name:		(*generic_match) - does the packet match the generic		specifications?	Synopsis:		static int generic_match(			const struct sk_buff *skb,			const struct net_device *in,			const struct net_device *out,			const void *matchinfo,			int offset,			const void *hdr,			u_int16_t datalen,			int *hotdrop		)	Arguments:		skb			skb to test for match		in			incoming network interface		out			outgoing network interface		matchinfo			match information		offset			packet offset		hdr			transport layer header pointer		datalen			length of skb		hotdrop			flag to immediately drop packet	Description:		This function checks if the skb supplied matches		the generic packet characteristics specified in		matchinfo.	Implementation notes:		Replace ipt_generic_info with the customised data		structure.	Return value:		It returns true (1) for	match, false (0) for no match.	Example:		static int		generic_match(			const struct sk_buff *skb,			const struct net_device *in,			const struct net_device *out,			const void *matchinfo,			int offset,			const void *hdr,			u_int16_t datalen,			int *hotdrop		) {			struct ipt_generic_info *info = (struct ipt_generic_info*)matchinfo;			if(/* test skb for match to matchinfo data */) {				return 1;			}			return 0;		}		static struct ipt_match generic_match_mod = {			{ NULL, NULL },			"generic",			&generic_match,			&generic_checkentry,			NULL,			THIS_MODULE		};		static int __init		init(void)		{			return ipt_register_match(&generic_match_mod);		}		static void __exit		fini(void)		{			ipt_unregister_match(&generic_match_mod);		}	See also:		http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html** NetFilter >-> GENERIC target NetFilter kernel module	Interface:		NetFilter >-> GENERIC target NetFilter kernel module	Label:	Name:		(*generic_target) - process outgoing packet with		"generic" information supplied	Synopsis:		static unsigned int		generic_target(			struct sk_buff **pskb,			unsigned int hooknum,			const struct net_device *in,			const struct net_device *out,			const void *targinfo,			void *userinfo		)	Arguments:		pskb			skb to be processed by target        	hooknum			which hook from which it was called		in			network device it came from		out			network device to which it is headed		targinfo			data used by target for processing		userinfo			optional user data passed in from mainline			hook	Description:		This is a NetFilter target.  It applies the generic		information supplied with the target to the outgoing		packet.	Implementation notes:		Replace ipt_generic_target_info with the customised data		structure, if there is one.	Return value:	       It returns <verdict>.	Example:		File net/ipv4/netfilter/ipt_GENERIC.c:		#include <linux/netfilter_ipv4/ip_tables.h>		static unsigned int		generic_target(struct sk_buff **pskb,			unsigned int hooknum,			const struct net_device *in,			const struct net_device *out,			const void *targinfo,			void *userinfo)		{			struct ipt_generic_target_info *info = (struct ipt_generic_target_info*)targinfo;			/* do target processing */			return <verdict>;		}		static struct ipt_target generic_target_mod = {			{ NULL, NULL },			"GENERIC",			generic_target,			generic_checkentry,			NULL,			THIS_MODULE		};		static int __init init(void)		{			if (ipt_register_target(&generic_target_mod))				return -EINVAL;			return 0;		}		static void __exit fini(void)		{			ipt_unregister_target(&generic_target_mod);		}	See also:		http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html* KLIPS2 Interfaces** KMd >-> iptables(8) "Policy"** KMd >-> ip6tables(8) "Policy"	Interface:		KMd >-> iptables(8)		KMd >-> ip6tables(8)	Label:		"Policy"	Name:		system(3) call to iptables(8) - execute a shell		command to do IP packet filter administration to set		ipsec policy	Synopsis:		#include <stdlib.h>		int system(const char * "iptables \			--table ipsec \			--new-table chain ");		int system(const char * "iptables \			--table ipsec \			--policy chain target");		int system(const char * "iptables \			--table ipsec \			--{append,delete,insert,replace} chain \			--protocol protocol \			--source src \			--destination dst \			--jump target \			--in-interface IPSECdev \			--out-interface IPSECdev \			--source-port SPORT \			--destination-port DPORT \			--uid-owner UID \			--gid-owner GID \			--pid-owner PID \			--sid-owner SID \			--espspi SPI \			--seclev seclevstr \			--salist SAList \		");	Arguments:		--table ipsec			specify ipsec SPDB NetFilter kernel table		--new-chain chain			create new chain in ipsec SPDB		--policy chain target			set default target for specified chain		--{append,delete,insert,replace} chain			manipulate a rule in the specified chain		--protocol protocol			protocol for the matching rule		--source src			source address for the matching rule		--destination dst			destination address for the matching rule		--in-interface IPSECdev			incoming ipsec device for the matching rule		--out-interface IPSECdev			outgoing ipsec device for the matching rule		--source-port SPORT			source port for the matching rule (tcp or udp)		--destination-port DPORT			destination port for the matching rule (tcp or udp)		--uid-owner UID			user ID for the matching rule		--espspi SPI			Encapsulation Security Payload Security Parameters			Index for the matching rule		--seclev seclevstr			security or sensitivity level or label for the			matching rule		--salist SAList			Security Association IDentifier list for the matching			rule		--jump target			target for a matching packet	Description:		This is the SPDB (or as yet undefined PF_POLICY)		interface from the key management daemons to the		kernel via netfilter.		The default chains of in and out are created when the		table is created.  Additional chains can be created as		needed with the iptables --new-chain command and can		be listed as targets to match entries.		The default policy of each chain can be changed from		the initialised value of DROP (TRAP?) with the		iptables --policy command.  The default policy of each		chain is one of the standard NetFilter targets of		ACCEPT, DROP, REJECT.  IPSec adds the targets TRAP,		HOLD (internal), PEEK and IPSEC.  Only the IPSEC		target takes any arguments, which consists of a list		of SAs to be used for processing.		Rules are appended, inserted, deleted or replaced to		set the IPSec policy.		Packets can be matched on IP transport protocol,		source or destination address, incoming or outgoing		ipsec device, source or destination port for tcp or		udp, user ID, Encapsulation Security Payload or		Authentication Header Security Parameters Index,		security or sensitivity level or label, Security		Association IDentifier list.  A target must be		specified for each matching rule using the iptables		--jump option.	Implementation notes:		If the in and out chains don't yet exist, they must be		created with the iptables --new-chain command.  (These		will most likely be created by loading the module and		so this paragraph may disappear.)  		An alternative may be to have the KMd link directly		with iptables.o rather than invoking system(3) to call		iptables(8).		It looks like it may be possible to call the libipt		functions directly, which will be a big help in		speeding things up since text conversion and parsing		won't have to be done.  This will change most of the		char fields to binary fields and change the calling		function and return codes.	Return value:		system(3) returns:		The value returned is 127 if the execve() call for		/bin/sh fails, -1 if there was another error.		iptables(8) returns:		Various error messages are printed to standard error.		The exit code is 0 for correct functioning.  Errors		which appear to be caused by invalid or abused command		line parameters cause an exit code of 2, and other		errors cause an exit code of 1.	Example:		#include <stdlib.h>		int return;		...		if((return = system("iptables \			--table ipsec \			--insert out \			--source this-subnet.example.com \			--destination that-subnet.example.com \			--jump IPSEC \			--use-salist esp.12345678@that-sg.example.com \			"))){			fprintf(stderr, "error $d calling iptables\n");			exit 1;		}	See also:		system(3), iptables(8)** iptables(8) >-> seclev match iptables(8) library** ip6tables(8) >-> seclev match ip6tables(8) library	Interface:		iptables(8) >-> seclev match iptables(8) library