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

FreeBSD Manual Pages

  
 
  

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

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

LIBRARY
       IPsec Policy Control Library (libipsec, -lipsec)

SYNOPSIS
       #include	<netipsec/ipsec.h>

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

       int
       ipsec_get_policylen(char	*buf);

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

DESCRIPTION
       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 spec-
       ification  structure.  The buffer is dynamically	allocated, and must be
       freed by	using 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
       structure, struct sadb_x_policy.	 delim is a delimiter string, which is
       usually	a  blank  character.  If you set delim to NULL,	a single white
       space is	assumed.  The ipsec_dump_policy() function returns  a  pointer
       to  dynamically 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 bypass 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	Proto-
			 col 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
			 always	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 omitted.

			 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 poli-
			 cies 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 transmit-
			 ted in	the clear.  The	use option is not  recommended
			 because  it  allows for accidental mis-configurations
			 where encrypted or authenticated link	becomes	 unen-
			 crypted  or  unauthenticated,	the require keyword is
			 recommended instead of	use where possible.  Using the
			 require keyword means that a relevant SA is required,
			 and that the kernel must perform IPsec	processing  on
			 all matching packets.

			 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 identifier	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
			 encouraged  to	specify	them explicitly	to avoid unin-
			 tended	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),
       neither entrust nor bypass are used.  Refer to setkey(8)	for details.

RETURN VALUES
       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 al-
       located region containing a human readable security policy on  success,
       and NULL	on error.

EXAMPLES
       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  pro-
       tocol.

	     in	ipsec ah/transport//require

       Tunnel packets outbound through the endpoints at	10.1.1.2 and 10.1.1.1.

	     out ipsec esp/tunnel/10.1.1.2-10.1.1.1/require

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

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

       IPv6 and	IPsec support based on the KAME	Project	(http://www.kame.net/)
       stack was initially integrated into FreeBSD 4.0.

FreeBSD	14.3		       February	14, 2006	   IPSEC_SET_POLICY(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ipsec_set_policy&sektion=3&manpath=FreeBSD+14.3-RELEASE+and+Ports>

home | help