klips2-design-api.txt

FREESWAN VPN源代码包

1#  -*- mode: Outline -*-
# 
#  klips2-design-api.txt
#	Richard Guy Briggs <[e-mail]>
#
#  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 [e-mail] \
			"))){
			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