Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
IPSEC_SET_POLICY(3)	 BSD Library Functions Manual	   IPSEC_SET_POLICY(3)

     ipsec_set_policy, ipsec_get_policylen, ipsec_dump_policy -- manipulate
     IPsec policy specification	structure from readable	string

     IPsec Policy Control Library (libipsec, -lipsec)

     #include <netinet6/ipsec.h>

     char *
     ipsec_set_policy(char *policy, int	len);

     ipsec_get_policylen(char *buf);

     char *
     ipsec_dump_policy(char *buf, char *delim);

     The ipsec_set_policy() function generates IPsec policy specification
     structure,	namely struct sadb_x_policy and/or struct sadb_x_ipsecrequest
     from human-readable policy	specification.	Policy specification must be
     given as C	string policy and length len of	policy.	 The
     ipsec_set_policy()	function will return the buffer	of IPsec policy	speci-
     fication structure.  The buffer is	dynamically allocated, and must	be
     freed by the caller by calling free(3).

     You may want the length of	the generated buffer such when calling
     setsockopt(2).  The ipsec_get_policylen() function	will return the

     The ipsec_dump_policy() function converts IPsec policy structure into
     readable form.  Therefore,	ipsec_dump_policy() can	be regarded as inverse
     conversion	of ipsec_set_policy().	buf points to an IPsec policy struc-
     ture, struct sadb_x_policy.  delim	is a delimiter string, which is	usu-
     ally a blank character.  If you set delim to NULL,	single whitespace is
     assumed.  The ipsec_dump_policy() function	returns	a pointer to dynami-
     cally allocated string.  It is caller's responsibility to reclaim the re-
     gion, by using free(3).

     policy is formatted as either of the following:

     direction discard
	      direction	must be	in or out.  direction specifies	which direc-
	      tion the policy needs to be applied.  With discard policy, pack-
	      ets will be dropped if they match	the policy.

     direction entrust
	      entrust means to consult to SPD defined by setkey(8).

     direction bypass
	      bypass means to be bypassed the IPsec processing.	 (packet will
	      be transmitted in	clear).	 This is for privileged	socket.

     direction ipsec request ...
	      ipsec means that the matching packets are	subject	to IPsec pro-
	      cessing.	ipsec can be followed by one or	more request string,
	      which is formatted as below:

	      protocol / mode /	src - dst [/level]
		       protocol	is either ah, esp or ipcomp.

		       mode is either transport	or tunnel.

		       src and dst specifies IPsec endpoint.  src always means
		       "sending	node" and dst always means "receiving node".
		       Therefore, when direction is in,	dst is this node and
		       src is the other	node (peer).  If mode is transport,
		       Both src	and dst	can be omitted.

		       level must be set to one	of the following: default,
		       use, require or unique.	default	means that the kernel
		       should consult the system default policy	defined	by
		       sysctl(8), such as net.inet.ipsec.esp_trans_deflev.
		       See ipsec(4) regarding the system default.  use means
		       that a relevant SA can be used when available, since
		       the kernel may perform IPsec operation against packets
		       when possible.  In this case, packets can be transmit-
		       ted in clear (when SA is	not available),	or encrypted
		       (when SA	is available).	require	means that a relevant
		       SA is required, since the kernel	must perform IPsec op-
		       eration against packets.	 unique	is the same as
		       require,	but adds the restriction that the SA for out-
		       bound traffic is	used only for this policy.  You	may
		       need the	identifier in order to relate the policy and
		       the SA when you define the SA by	manual keying.	You
		       can put the decimal number as the identifier after
		       unique like unique: number.  number must	be between 1
		       and 32767 .  If the request string is kept unambiguous,
		       level and slash prior to	level can be omitted.  How-
		       ever, it	is encouraged to specify them explicitly to
		       avoid unintended	behaviors.  If level is	omitted, it
		       will be interpreted as default.

     Note that there is	a bit difference of specification from setkey(8).  In
     specification by setkey(8), both entrust and bypass are not used.	Refer
     to	setkey(8) for detail.

     Here are several examples (long lines are wrapped for readability):

	   in discard
	   out ipsec esp/transport//require
	   in ipsec ah/transport//require
	   out ipsec esp/tunnel/
	   in ipsec ipcomp/transport//use

     The ipsec_set_policy() function returns a pointer to the allocated	buffer
     of	policy specification if	successful; otherwise a	NULL pointer is	re-
     turned.  The ipsec_get_policylen()	function returns with positive value
     (meaning the buffer size) on success, and negative	value on errors.  The
     ipsec_dump_policy() function returns a pointer to dynamically allocated
     region on success,	and NULL on errors.

     ipsec_strerror(3),	ipsec(4), setkey(8)

     The functions first appeared in WIDE/KAME IPv6 protocol stack kit.

     IPv6 and IPsec support based on the KAME Project (
     stack was initially integrated into FreeBSD 4.0

BSD				  May 5, 1998				   BSD


Want to link to this manual page? Use this URL:

home | help