klips2-design-api.txt

FREESWAN VPN源代码包

		out of buffers, -EPERM if a verdicet of NF_DROP was
		returned because the firewall refused to let it pass.
		Other errors are possible from other output functions
		associated with firewall targets.

	Example:

		ip_finish_output(skb);

	See also:



** NetFilter >-> IPSEC target NetFilter kernel module

	Interface:

		NetFilter >-> IPSEC target NetFilter kernel module

	Label:

	Name:

		(*ipsec_target) - process outgoing packet with
		specified Security Associations

	Synopsis:

		see: NetFilter >-> GENERIC target NetFilter kernel module

	Arguments:

		see: NetFilter >-> GENERIC target NetFilter kernel module

	Description:

		This is a NetFilter target.  It looks up the Security
		Associations listed as an argument, in the Security
		Association DataBase, and applies them in sequence to
		the outgoing packet.

	Implementation notes:

		Use the data structure ipt_ipsec_target_info.

	Return value:

	       It returns NF_STOLEN.

	Example:

		see: NetFilter >-> GENERIC target NetFilter kernel module

	See also:

		NetFilter >-> GENERIC target NetFilter kernel module
		http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html



** IPSEC target NetFilter kernel module >-> SADB "SAID"

	Interface:

		IPSEC target NetFilter kernel module >-> SADB

	Label: 

		SAID

	Name:

		ipsec_getsa - get an SA from the SADB by SAID

	Synopsis: 

		#include <ipsec_sadb.h>

		struct ipsec_sa *
		ipsec_getsa(
			struct ipsec_said asaid
		);

	Arguments:

		asaid
			Security Association IDentifier to try to
			match in SADB


	Description:

		Retrieve a Security Association from the system
		Security Association DataBase that matches the
		supplied Security Association IDentifier.

		The Security Association IDentifier must be supplied
		as a completely filled struct ipsec_said.  ipsec_getsa() attempts
		to exactly match the SAID structure of an SA
		entry in the global SADB hash table ipsec_sadb with
		the SAID argument.  If this succeeds, 
		a pointer to the matching SA is returned.

	Implementation notes:

		The reference count of the matching SA is atomically
		incremented by ipsec_getsa() and must be atomically
		decremented when the caller of ipsec_getsa() has
		finished with the SA.

		The global SADB hash table struct
		ipsec_sa*ipsec_sadb[] is locked by ipsec_getsa()
		during lookup.

	Return values:

		A pointer to a valid Security Association is returned
		if a match was found, otherwise NULL is returned.

	Example:

		struct ipsec_sa *sa;
		struct ipsec_said said;
		...
		sa = ipsec_getsa(said);
		...
		if(atomic_dec_and_test(sa->refcount)) {
			ipsec_sa_free(sa);
		}

	See also:



** IPSEC target NetFilter kernel module >-> NetFilter

	Interface:

		IPSEC target NetFilter kernel module >-> NetFilter

	Label:

	Name:

		ip_queue_xmit - re-submit the packet to the output
		queue, now that the packet has been IPSec pocessed.

		NF_HOOK(PF_INET, NF_IP_LOCAL_OUT, skb, NULL, rt->u.dst.dev, ip_queue_xmit2);

		NF_HOOK(PF_INET, NF_IP_LOCAL_OUT, skb, NULL, rt->u.dst.dev, ip_send);

	Synopsis:

		int
		ip_queue_xmit(
			struct sk_buff *skb
		)

	Arguments:

		skb
			socket buffer to be sent

	Description:

		This interface is to re-inject packets before
		NF_IP_LOCAL_OUT after the packet has been processed.

	Implementation notes:

		int ip_queue_xmit(struct sk_buff *skb) is another possibility...

	Return value:

		0 if everything worked out.  -ENOMEM if the kernel ran
		out of buffers.  -EPERM if a verdicet of NF_DROP was
		returned because the firewall refused to let it pass.
		-EHOSTUNREACH if routing failed.
		Other errors are possible from other output functions
		associated with firewall targets.

	Example:

		struct salist SAs;
		...

		skb->salist = SAs;
		ip_queue_xmit(skb);

	See also:

		http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html



** SADB >-> KMd "PF_KEYv2 EXPIRE"

	Interface:

		SADB >-> KMd "PF_KEYv2 EXPIRE"

	Label:

		see RFC2367, PF_KEYv2 EXPIRE

	Name:

		see RFC2367, PF_KEYv2 EXPIRE

	Synopsis:

		see RFC2367, PF_KEYv2 EXPIRE

	Arguments:

		see RFC2367, PF_KEYv2 EXPIRE

	Description:

		This interface is used by the kernel to notify key
		management daemons that a security association has
		either soft or hard expired and to negotiate a
		replacement.

	Implementation notes:

	Return value:

		see RFC2367, PF_KEYv2 EXPIRE

	Example:

	See also:


** Routing Table >-> IPSEC target NetFilter kernel module "IPSECdev"

	Interface:

		Routing Table >-> IPSEC target NetFilter kernel module

	Label:

		 "IPSECdev"

	Name:

	Synopsis:

	Arguments:

	Description:

		This interface provides a way of routing packets
		through a specific IPSec virtual tunnel.  This is
		standard linux network routing.

	Implementation notes:

	Return value:

	Example:

	See also:



** KMd >-> Routing Table "Routing"

	Interface:

		KMd >-> Routing Table

	Label:

		"Routing"

	Name:

		system(3) call to route(8) - execute a shell
		command to do IP packet routing administration to set
		ipsec policy

	Synopsis:

		#include <stdlib.h>

		int
		system(
			const char * "route \
			{add,del} -{host,net} \
			{<host>,<net>[/mask]} \
			gw <gateway> \
			dev <device> \
		");

	Arguments:

		add
			add an entry to the routing table

		del
			delete an entry from the routing table

		-host
			add or delete a host

		-net
			add or delete a network

		<host>
			host FQDN or IPv4 or IPv6 address

		<net>[/mask]
			network FQDN or IPv4 or IPv6 address with netmask

		gw <gateway>
			nexthop gateway address

		dev <device>

		char[] IPSECdev
		unsigned char exit_code

	Description:

		This is an interface from the key management daemon to
		explicitly route traffic through an IPSEC virtual
		device which is defined by a pair of IPSEC tunnel
		endpoints and a set of Security Associations.

	Implementation notes:

		currently done by system(3) calls to _updown.

	Return value:

	Example:

	See also:

		system(3), route(8), iproute2(8)



** Transport Layer De-mux >-> IPSec DECRYPT kernel module

	Interface:

		Transport Layer De-mux >-> IPSec DECRYPT kernel module

	Label:

	Name:

		ipsec_rcv - process an incoming IPSec packet
	Synopsis:
		
		#include <ipsec_rcv.h>

		int
		ipsec_rcv(
			struct sk_buff *skb,
			unsigned short xlen
		)

	Arguments:

		skb
			skb to be processed

		xlen
			length of skb buffer

	Description:

		This interface is to call the IPSEC ESP transport
		layer protocol handler to process (decrypt) an
		incoming packet.

		The packet is freed, being re-injected before the
		NF_IP_PRE_ROUTING hook.

	Implementation notes:

	Return value:

	       ipsec_rcv() returns zero (0).

	Example:

	See also:



** IPSec DECRYPT kernel module >-> SADB "SAID"

	Interface:

		IPSec DECRYPT kernel module >-> SADB

	Label:

		see "SAID"

	Name:

		ipsec_getsa - get an SA from the SADB by SAID

	Synopsis:

		see: IPSEC target NetFilter kernel module >-> SADB "SAID"

	Arguments:

		see: IPSEC target NetFilter kernel module >-> SADB "SAID"

	Description:

		see: IPSEC target NetFilter kernel module >-> SADB "SAID"

	Implementation notes:

		see: IPSEC target NetFilter kernel module >-> SADB "SAID"

	Return value:

		see: IPSEC target NetFilter kernel module >-> SADB "SAID"

	Example:

		see: IPSEC target NetFilter kernel module >-> SADB "SAID"

	See also:

		IPSEC target NetFilter kernel module >-> SADB "SAID"


** IPSec DECRYPT kernel module >-> NetFilter

	Interface:

		IPSec DECRYPT kernel module >-> NetFilter

	Label:

	Name:

		int netif_rx(struct sk_buff *skb) - post  buffer to the network code, always succeeds

		ip_rcv - receive an IP packet for input processing

		NF_HOOK(PF_INET, NF_IP_PRE_ROUTING, skb, dev, NULL, ip_rcv_finish);

	Synopsis:

		int
		ip_rcv(
			struct sk_buff *skb,
			struct net_device *dev,
			struct packet_type *pt
		)

	Arguments:

		skb
			packet to be re-injected

		dev
			incoming device, virtual if there is one.

		pt
			packet type (not used)


	Description:

		This interface is to re-start the packet input
		processing procedure once an IPSec layer has been
		peeled away.  The packet is made available to the
		input stream before NF_IP_PRE_ROUTE to check policy
		with processed (decrypted) connection information.

	Implementation notes:

	Return value:

		0 if everything worked out, -ENOMEM if the kernel ran
		out of buffers, -EPERM if a verdicet of NF_DROP was
		returned because the firewall refused to let it pass.
		Other errors are possible from other output functions
		associated with firewall targets.

	Example:

		struct salist SAs;
		...

		skb->salist = SAs;
		ip_rcv(skb, skb->dev, NULL)

	See also:



** NetFilter >-> PEEK target NetFilter kernel module

	Interface:

		NetFilter >-> PEEK target NetFilter kernel module

	Label:

	Name:

		(*peek_target) - PEEK at packets to initiate opportunism

	Synopsis:

		see: NetFilter >-> GENERIC target NetFilter kernel module

	Arguments:

		see: NetFilter >-> GENERIC target NetFilter kernel module

	Description:

		This interface is used by the kernel netfilter table
		as a target for packets to be PEEKed at to notify the
		key management daemons to acquire a new set of
		Security Associations and to set up an ACCEPT to allow
		packets in and avoid overloading the KMds.

	Implementation notes:

	Return value:

		It returns NF_ACCEPT.

	Example:

		see: NetFilter >-> GENERIC target NetFilter kernel module

	See also:

		NetFilter >-> GENERIC target NetFilter kernel module
		http://netfilter.samba.org/unreliable-guides/netfilter-hacking-HOWTO/netfilter-hacking-HOWTO.linuxdoc-4.html



** PEEK target NetFilter kernel module >-> KMds "PF_KEYv2 ACQUIRE"

	Interface:

		PEEK target NetFilter kernel module >-> KMds

	Label:

		"PF_KEYv2 ACQUIRE"

	Name:

		see RFC2367, PF_KEYv2 ACQUIRE

	Synopsis:

		see RFC2367, PF_KEYv2 ACQUIRE

	Arguments:

		see RFC2367, PF_KEYv2 ACQUIRE

	Description:

		This interface is used to make requests from the
		kernel to key management daemons for a set of Security
		Associations to cover the specified traffic named to a
		remote host.

	Implementation notes:

	Return value:

		see RFC2367, PF_KEYv2 ACQUIRE

	Example:

	See also:

		see RFC2367, PF_KEYv2 ACQUIRE



** New I/F section template

	Interface:

	Label:

	Name:

	Synopsis:

	Arguments:

	Description:

	Implementation notes:

	Return value:

	Example:

	See also:



* Definitions and Data structures used

SAList := <SAID>[,<SAID>[,<SAID>[,<SAID>]]]

<SAID> := <proto><PF><spi>@<dstaddr>

<proto> := ah | esp | comp | tun

<PF> := . | : (indicates IPv4 or IPv6 respectively)

<spi> := <8-digit hexadecimal string>

<dstaddr> := <any valid FQDN or IP address of the appropriate family>


const struct ipt_entry is already defined in netfilter.

struct ipt_entry_match is already defined in netfilter.

struct ipsec_seclev remains to be defined.

struct ipt_seclev_info {
	struct ipsec_seclev;		/* Security Level data */
	u_int8_t  invert;	/* Invert match */
};

struct ipsec_salist {
	struct ipsec_said said1;
	struct ipsec_said said2;
	struct ipsec_said said3;
	struct ipsec_said said4;
}

struct ipt_salist_info {
	struct ipsec_salist salist;	/* Security Association List data */
	u_int8_t  invert;	/* Invert match */
};

struct ipt_ipsec_target_info {
	struct ipsec_said said1;
	struct ipsec_said said2;
	struct ipsec_said said3;
	struct ipsec_said said4;
};

struct ipsec_said{		/* to identify an SA, we need: */
	ip_address dst;		/* A. destination host */
	ipsec_spi_t spi;	/* B. 32-bit SPI, assigned by dest. host */
#		define	SPI_PASS	256	/* magic values... */
#		define	SPI_DROP	257	/* ...for use... */
#		define	SPI_REJECT	258	/* ...with SA_INT */
#		define	SPI_HOLD	259
#		define	SPI_TRAP	260
	int proto;		/* C. protocol */
#		define	SA_ESP	50	/* IPPROTO_ESP */
#		define	SA_AH	51	/* IPPROTO_AH */
#		define	SA_IPIP	4	/* IPPROTO_IPIP */
#		define	SA_COMP	108	/* IPPROTO_COMP */
#		define	SA_INT	61	/* IANA reserved for internal use */
};

typedef struct {
	union {
		struct sockaddr_in v4;
		struct sockaddr_in6 v6;
	} u;
} ip_address;

struct ipsec_sa {
	/* copy most from struct tdb */
};

struct ipsecinfo {
	struct ipt_entry_target t;
	struct ipt_ipsec_target_info salist;
};

struct trapinfo {
	struct ipt_entry_target t;
};

struct peekinfo {
	struct ipt_entry_target t;
};

struct holdinfo {
	struct ipt_entry_target t;
};

* Version:

	$Id: klips2-design-api.txt,v 1.1.1.1 2002/09/05 03:13:16 ken Exp $