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

FreeBSD Manual Pages


home | help
ipsec(7P)			   Protocols			     ipsec(7P)

       ipsec - Internet	Protocol Security Architecture

       The  IP	Security Architecture (IPsec) provides protection for IP data-
       grams. The protection can include confidentiality, strong integrity  of
       the data, partial sequence integrity  (replay protection), and data au-
       thentication. IPsec is performed	inside the IP processing, and  it  can
       be applied with or without the knowledge	of an Internet application.

       IPsec applies to	both IPv4 and IPv6. See	ip(7P) and ip6(7P).

   Protection Mechanisms
       IPsec  provides	two mechanisms for protecting data. The	Authentication
       Header (AH) provides strong integrity, replay protection, and data  au-
       thentication. AH	protects as much of the	IP datagram as it can. AH can-
       not protect fields that change nondeterministically between sender  and

       The  Encapsulating Security Payload (ESP) provides confidentiality over
       what it encapsulates, as	well as	the services  that  AH	provides,  but
       only over that which it encapsulates. ESP's authentication services are
       optional, which allow ESP and AH	to be used together on the same	 data-
       gram without redundancy.

       Authentication  and encryption algorithms are used for IPsec. Authenti-
       cation algorithms produce an integrity checksum value or	"digest" based
       on  the	data and a key.	Encryption algorithms operate on data in units
       of a "block size."

   Security Associations
       AH and ESP use Security Associations (SA). SA's are entities that spec-
       ify security properties from one	host to	another. Two communicating ma-
       chines require two SAs (at a minimum) to	communicate securely. However,
       communicating  machines that use	multicast can share the	same multicast
       SA. SAs are managed through the pf_key(7P) interface. For  IPv4,	 auto-
       matic  SA  management  is  available  through the Internet Key Exchange
       (IKE), as implemented  by  in.iked(1M).	A  command-line	 front-end  is
       available  by means of ipseckey(1M). An IPsec SA	is identified by a tu-
       ple of <AH or ESP, destination IP address, and SPI>.  The Security  Pa-
       rameters	 Index	(SPI) is an arbitrary 32-bit value that	is transmitted
       on the wire with	an AH or ESP packet. See ipsecah(7P)  or  ipsecesp(7P)
       for an explanation about	where the SPI falls in a protected packet.

   Protection Policy and Enforcement Mechanisms
       Mechanism and policy are	separate. The policy for applying IPsec	is en-
       forced on a system-wide or  per-socket  level.  Configuring  systemwide
       policy  is  done	 via the ipsecconf(1M) command.	Configuring per-socket
       policy is discussed later in this section.

       Systemwide IPsec	policy is applied to incoming and outgoing  datagrams.
       Some  additional	 rules can be applied to outgoing datagrams because of
       the additional data known by the	system.	Inbound	datagrams can  be  ac-
       cepted  or  dropped. The	decision to drop or accept an inbound datagram
       is based	on several criteria which sometimes overlap or conflict.  Con-
       flict  resolution  is  resolved by which	rule is	parsed first, with one
       exception: if a policy entry states  that  traffic  should  bypass  all
       other  policy,  it  is automaticaly be accepted.	Outbound datagrams are
       sent with or without protection.	Protection may (or may	not)  indicate
       specific	 algorithms.  If  policy normally would	protect	a datagram, it
       can be bypassed either by an exception in systemwide policy or  by  re-
       questing	a bypass in per-socket policy.

       Intra-machine traffic policies are enforced, but	actual security	mecha-
       nisms are not applied;  rather, the outbound policy on an intra-machine
       packet translates into an inbound packet	with those mechanisms applied.

       IPsec policy is enforced	in the ip(7P) driver; several ndd tunables for
       /dev/ip affect policy enforcement. These	include:


	   If equal to 1 (the default),	allow certain cleartext	icmp  messages
	   to bypass policy. For ICMP echo requests ("ping" messages), protect
	   the response	like the request. If zero, treat  icmp	messages  like
	   other IP traffic.


	   If 1, allow inbound cleartext IGMP messages to bypass IPsec policy.


	   If 1, allow inbound cleartext PIM messages to bypass	IPsec policy.

   Per-Socket Policy
       The  IP_SEC_OPT or IPV6_SEC_OPT socket option is	used to	set per-socket
       IPsec policy.  The structure used for an	IP_SEC_OPT request is:

       typedef struct ipsec_req	{
	   uint_t      ipsr_ah_req;	      /* AH request */
	   uint_t      ipsr_esp_req;	      /* ESP request */
	   uint_t      ipsr_self_encap_req;   /* Self-Encap request */
	   uint8_t     ipsr_auth_alg;	      /* Auth algs for AH */
	   uint8_t     ipsr_esp_alg;	      /* Encr algs for ESP */
	   uint8_t     ipsr_esp_auth_alg;     /* Auth algs for ESP */
       } ipsec_req_t;

       The IPsec request has fields for	both AH	and ESP. Algorithms may	or may
       not  be	specified.  The	actual request for AH or ESP services can take
       one of the following values:


	   Bypass all policy. Only the superuser may request this service.


	   Regardless of other policy, require the use of the  IPsec  service.

       The following value can be logically  ORed  to  an  IPSEC_PREF_REQUIRED


	   Regardless  of other	policy,	enforce	a unique SA for	traffic	origi-
	   nating from this socket.

       In the event IP options not normally encapsulated by ESP	 need  to  be,
       the ipsec_self_encap_req	is used	to add an additional IP	header outside
       the original one. Algorithm values from <net/pfkeyv2.h> are as follows:


	   Uses	the MD5-HMAC (RFC 2403)	 algorithm for authentication.


	   Uses	the SHA1-HMAC (RFC 2404) algorithm for authentication.


	   Uses	the DES	(RFC 2405) algorithm for encryption.


	   Uses	the Triple  DES	 (RFC 2451)   algorithm	for encryption.


	   Uses	the Blowfish (RFC 2451)	algorithm for encryption.


	   Uses	 the  Advanced Encryption Standard  algorithm for encryption.

       An application should use either	the getsockopt(3SOCKET)	 or  the  set-
       sockopt(3SOCKET)	call to	manipulate IPsec requests.  For	example:

       #include	<sys/socket.h>
       #include	<netinet/in.h>
       #include	<net/pfkeyv2.h>	  /* For SADB_*ALG_* */
       /* .... socket setup skipped */
       rc = setsockopt(s, IPPROTO_IP, IP_SEC_OPT,
	  (const char *)&ipsec_req, sizeof (ipsec_req_t));

       While  IPsec  is	an effective tool in securing network traffic, it will
       not make	security problems disappear. Security issues beyond the	mecha-
       nisms that IPsec	offers may be discussed	in similar "Security Consider-
       ation" sections within individual reference manual pages.

       While a non-root	user cannot bypass IPsec, a non-root user can set pol-
       icy  to	be  different from the system-wide policy. For ways to prevent
       this, consult the ndd(1M) variables in /dev/ip.

       See attributes(5)  for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Evolving			   |

       in.iked(1M), ipsecconf(1M), ipseckey(1M), ndd(1M), getsockopt(3SOCKET),
       setsockopt(3SOCKET),    attributes(5),	inet(7P),   ip(7P),   ip6(7P),
       ipsecah(7P), ipsecesp(7P), pf_key(7P)

       Kent, S., and Atkinson, R., RFC 2401, Security Architecture for the In-
       ternet Protocol,	The Internet Society, 1998.

       Kent,  S. and Atkinson, R., RFC 2406, IP	Encapsulating Security Payload
       (ESP), The Internet Society, 1998.

       Madson, C., and Doraswamy, N., RFC 2405,	The ESP	DES-CBC	 Cipher	 Algo-
       rithm with Explicit IV, The Internet Society, 1998.

       Madsen,	C.  and	Glenn, R., RFC 2403, The Use of	HMAC-MD5-96 within ESP
       and AH, The Internet Society, 1998.

       Madsen, C. and Glenn, R., RFC 2404, The Use of HMAC-SHA-1-96 within ESP
       and AH, The Internet Society, 1998.

       Pereira,	 R.  and  Adams,  R.,  RFC 2451, The ESP CBC-Mode Cipher Algo-
       rithms, The Internet Society, 1998.

SunOS 5.10			  9 Dec	2002			     ipsec(7P)


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

home | help