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

FreeBSD Manual Pages


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

     ipsec_set_policy, ipsec_get_policylen, ipsec_dump_policy -- create	an
     IPsec policy structure from a human readable string

     IPsec Policy Control Library (libipsec, -lipsec)

     #include <netipsec/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 an IPsec	policy specification
     structure,	struct sadb_x_policy and/or struct sadb_x_ipsecrequest from a
     human-readable policy specification.  The policy specification must be
     given as a	C string, passed in the	policy argument	and the	length of the
     string, given as len.  The	ipsec_set_policy() function returns pointer to
     a buffer which contains a properly	formed IPsec policy specification
     structure.	 The buffer is dynamically allocated, and must be freed	by us-
     ing the free(3) library function.

     The ipsec_get_policylen() function	returns	the length of the buffer which
     is	needed when passing the	specification structure	to the setsockopt(2)
     system call.

     The ipsec_dump_policy() function converts an IPsec	policy structure into
     a human readable form.  The buf argument 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,	a single white space
     is	assumed.  The ipsec_dump_policy() function returns a pointer to	dynam-
     ically allocated string.  It is the caller's responsibility to free the
     returned pointer using the	free(3)	library	call.

     A policy is given in the following	way:

     direction discard
	      The direction must be in or out and specifies which direction
	      the policy needs to be applied, either on	inbound	or outbound
	      packets.	When the discard policy	is selected, packets will be
	      dropped if they match the	policy.

     direction entrust
	      entrust means to consult the security policy database (SPD) in
	      the kernel, as controlled	by setkey(8).

     direction bypass
	      A	direction of bypass indicates that IPsec processing should not
	      occur and	that the packet	will be	transmitted in clear.  The by-
	      pass option is only available to privileged sockets.

     direction ipsec request ...
	      A	direction of ipsec means that matching packets are processed
	      by IPsec.	 ipsec can be followed by one or more request string,
	      which is formatted as:

	      protocol / mode /	src - dst [/level]
		       The protocol is one of: ah, esp or ipcomp indicating
		       Authentication Header, Encapsulating Security Protocol
		       or IP Compression protocol is used.

		       The mode	is either transport or tunnel the meanings of
		       both modes are described	in ipsec(4).

		       The src and dst specify the IP address, either v4 or
		       v6, of the source and destination systems.  The src al-
		       ways stands for the "sending node" and dst always
		       stands for the "receiving node".	 When direction	is in,
		       dst is this local node and src is the remote node or
		       peer.  If mode is transport, both src and dst can be

		       The level must be set to	one of the following: default,
		       use, require or unique.	default	means that the kernel
		       should consult the default security policies as defined
		       by a set	of sysctl(8), variables.  The relevant
		       sysctl(8) variables are described in ipsec(4).

		       When use	is selected a relevant security	association
		       (SA) can	be used	when available but is not necessary.
		       If the SA is available then packets will	be handled by
		       IPsec, i.e., encrypted and/or authenticated but if an
		       SA is not available then	packets	will be	transmitted in
		       the clear.  The use option is not recommended because
		       it allows for accidental	mis-configurations where en-
		       crypted or authenticated	link becomes unencrypted or
		       unauthenticated,	the require keyword is recommended in-
		       stead of	use where possible.  Using the require keyword
		       means that a relevant SA	is required, and that the ker-
		       nel must	perform	IPsec processing on all	matching pack-

		       The unique keyword has the same effect as require, but
		       adds the	restriction that the SA	for outbound traffic
		       is used only for	this policy.  You may need the identi-
		       fier in order to	relate the policy and the SA when you
		       define the SA by	manual keying using setkey(8).	Put
		       the decimal number as the identifier after the unique
		       keyword in this way: unique: number, where number must
		       be between 1 and	32767.

		       If the request string is	kept unambiguous, level	and
		       the slash prior to level	can be omitted but you are en-
		       couraged	to specify them	explicitly to avoid unintended
		       behaviors.  If level is omitted,	it will	be interpreted
		       as default.

     Note that there is	a difference between the specification allowed here
     and in setkey(8).	When specifying	security policies with setkey(8), nei-
     ther entrust nor bypass are used.	Refer to setkey(8) for details.

     The ipsec_set_policy() function returns a pointer to the allocated	buffer
     containing	a the policy specification if successful; otherwise a NULL
     pointer is	returned.

     The ipsec_get_policylen() function	returns	a positive value, indicating
     the buffer	size, on success, and a	negative value on error.

     The ipsec_dump_policy() function returns a	pointer	to a dynamically allo-
     cated region containing a human readable security policy on success, and
     NULL on error.

     Set a policy that all inbound packets are discarded.

	   in discard

     All outbound packets are required to be processed by IPsec	and trans-
     ported using ESP.

	   out ipsec esp/transport//require

     All inbound packets are required to be authenticated using	the AH proto-

	   in ipsec ah/transport//require

     Tunnel packets outbound through the endpoints at and

	   out ipsec esp/tunnel/

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

     These 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.

FreeBSD	13.0		       February	14, 2006		  FreeBSD 13.0


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

home | help