home | help
IPSEC(4)		     Kernel Interfaces Manual			IPSEC(4)

NAME
     ipsec -- IP security protocol

SYNOPSIS
     #include <sys/types.h>
     #include <netinet/in.h>
     #include <netinet6/ipsec.h>

DESCRIPTION
     ipsec is a security protocol implemented within the Internet Protocol layer
     of  the  TCP/IP  stack.   ipsec  is  defined  for	both  IPv4  and IPv6 and
     inet6(4)).  ipsec contains two protocols, ESP,  the  encapsulated	security
     payload  protocol and AH, the authentication header protocol.  ESP prevents
     unauthorized parties from reading the payload of an IP packet by encrypting
     it using secret key cryptography algorithms.  AH both authenticates guaran-
     tees the integrity of an IP packet by attaching  a  cryptographic	checksum
     computed  using  one-way  hash functions.	ipsec has operates in one of two
     modes: transport mode or tunnel mode.  Transport mode is  used  to  protect
     peer-to-peer  communication between end nodes.  Tunnel mode encapsulates IP
     packets within other IP packets and is designed for security gateways  such
     as VPN endpoints.

   Kernel interface
     ipsec  is	controlled by a key management and policy engine, that reside in
     the operating system kernel.  Key management is the process of  associating
     keys  with security associations, also know as SAs.  Policy management dic-
     tates when new security associations created or destroyed.

     The key management engine can be accessed from  userland  by  using  PF_KEY
     sockets.  The PF_KEY socket API is defined in RFC2367.

     The policy engine is controlled by an extension to the PF_KEY API, setsock-
     opt(2)  operations,  and sysctl(3) interface.  The kernel implements an ex-
     tended version of the PF_KEY interface, and allows the programmer to define
     IPsec policies which are similar to the per-packet filters.   The	setsock-
     opt(2)  interface	is used to define per-socket behavior, and sysctl(3) in-
     terface is used to define host-wide default behavior.

     The kernel code does not implement a dynamic encryption key exchange proto-
     col such as IKE (Internet Key Exchange).  Key exchange protocols are beyond
     what is necessary in  the	kernel	and  should  be  implemented  as  daemon
     processes which call the APIs.

   Policy management
     IPsec  policies  can  be  managed in one of two ways, either by configuring
     per-socket policies using the setsockopt(2) system calls, or by configuring
     kernel level packet filter-based policies using the PF_KEY  interface,  via
     the  setkey(8)  command.	In either case, IPsec policies must be specified
     using the syntax described in ipsec_set_policy(3).   Please  refer  to  the
     setkey(8) man page for instructions on its use.

     When  setting policies using the setkey(8) command the "default" option you
     can have the system use its default policy, explained below, for processing
     packets.  The following sysctl variables are available for configuring  the
     system's  IPsec  behavior.   The variables can have one of two values.  A 1
     means "use", which means that if there is a security association  then  use
     it  but  if  there is not then the packets are not processed by IPsec.  The
     value 2 is synonymous with "require", which requires that a security  asso-
     ciation  must  exist  for	the  packets to move, and not be dropped.  These
     terms are defined in ipsec_set_policy(8).

     Name				  Type		Changeable
     net.inet.ipsec.esp_trans_deflev	  integer	yes
     net.inet.ipsec.esp_net_deflev	  integer	yes
     net.inet.ipsec.ah_trans_deflev	  integer	yes
     net.inet.ipsec.ah_net_deflev	  integer	yes
     net.inet6.ipsec6.esp_trans_deflev	  integer	yes
     net.inet6.ipsec6.esp_net_deflev	  integer	yes
     net.inet6.ipsec6.ah_trans_deflev	  integer	yes
     net.inet6.ipsec6.ah_net_deflev	  integer	yes

     If the kernel does not find a matching, system wide, policy  then	the  de-
     fault value is applied.  The system wide default policy is specified by the
     following	sysctl(8) variables.  0 means "discard" which asks the kernel to
     drop the packet.  1 means "none".

     Name			    Type	  Changeable
     net.inet.ipsec.def_policy	    integer	  yes
     net.inet6.ipsec6.def_policy    integer	  yes

   Miscellaneous sysctl variables
     The following variables are accessible via sysctl(8), for tweaking the ker-
     nel's IPsec behavior:

     Name				  Type		Changeable
     net.inet.ipsec.ah_cleartos 	  integer	yes
     net.inet.ipsec.ah_offsetmask	  integer	yes
     net.inet.ipsec.dfbit		  integer	yes
     net.inet.ipsec.ecn 		  integer	yes
     net.inet.ipsec.debug		  integer	yes
     net.inet6.ipsec6.ecn		  integer	yes
     net.inet6.ipsec6.debug		  integer	yes

     The variables are interpreted as follows:

     ipsec.ah_cleartos
	     If set to non-zero, the kernel clears the type-of-service field  in
	     the  IPv4	header	during AH authentication data computation.  This
	     variable is used to get current systems to inter-operate  with  de-
	     vices  that  implement  RFC1826  AH.   It should be set to non-zero
	     (clear the type-of-service field) for RFC2402 conformance.

     ipsec.ah_offsetmask
	     During AH authentication data computation, the kernel will  include
	     a	16bit  fragment  offset  field (including flag bits) in the IPv4
	     header, after computing logical AND with the variable.   The  vari-
	     able  is  used  for  inter-operating  with  devices  that implement
	     RFC1826 AH.  It should be set to zero (clear  the	fragment  offset
	     field during computation) for RFC2402 conformance.

     ipsec.dfbit
	     This  variable  configures the kernel behavior on IPv4 IPsec tunnel
	     encapsulation.  If set to 0, the DF bit on the  outer  IPv4  header
	     will  be cleared while 1 means that the outer DF bit is set regard-
	     less from the inner DF bit and 2  indicates  that	the  DF  bit  is
	     copied  from  the	inner  header to the outer one.  The variable is
	     supplied to conform to RFC2401 chapter 6.1.

     ipsec.ecn
	     If set to non-zero, IPv4 IPsec  tunnel  encapsulation/decapsulation
	     behavior  will  be  friendly  to ECN (explicit congestion notifica-
	     tion), as documented in draft-ietf-ipsec-ecn-02.txt.  gif(4)  talks
	     more about the behavior.

     ipsec.debug
	     If set to non-zero, debug messages will be generated via syslog(3).

     Variables	under  the  net.inet6.ipsec6 tree have similar meanings to those
     described above.

PROTOCOLS
     The ipsec protocol acts as a plug-in to the inet(4) and inet6(4)  protocols
     and  therefore  supports  most of the protocols defined upon those IP-layer
     protocols.  The icmp(4) and icmp6(4) protocols may behave differently  with
     ipsec  because  ipsec can prevent icmp(4) or icmp6(4) routines from looking
     into the IP payload.

SEE ALSO
     ioctl(2),	socket(2),  ipsec_set_policy(3),  icmp6(4),  intro(4),	 ip6(4),
     setkey(8), sysctl(8)

     S. Kent and R. Atkinson, IP Authentication Header, RFC 2404.

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

STANDARDS
     Daniel L. McDonald, Craig Metz, and Bao G. Phan, PF_KEY Key Management API,
     Version 2, RFC, 2367.

     D. L. McDonald, A Simple IP Security API Extension to BSD Sockets, internet
     draft, draft-mcdonald-simple-ipsec-api-03.txt, work in progress material.

HISTORY
     The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack.

BUGS
     The IPsec support is subject to change as the IPsec protocols develop.

     There is no single standard for the policy engine API, so the policy engine
     API described herein is just for KAME implementation.

     AH  and tunnel mode encapsulation may not work as you might expect.  If you
     configure inbound "require" policy with an AH tunnel or any IPsec	encapsu-
     lating policy with AH (like "esp/tunnel/A-B/use ah/transport/A-B/require"),
     tunnelled	packets  will  be rejected.  This is because the policy check is
     enforced on the inner packet on reception, and AH authenticates encapsulat-
     ing (outer) packet, not the encapsulated (inner) packet (so for the receiv-
     ing kernel there is no sign of authenticity).  The  issue	will  be  solved
     when  we revamp our policy engine to keep all the packet decapsulation his-
     tory.

     When a large database of security associations or policies  is  present  in
     the  kernel the SADB_DUMP and SADB_SPDDUMP operations on PF_KEY sockets may
     fail due to lack of space.  Increasing the socket buffer size may alleviate
     this problem.

FreeBSD 6.4			February 14, 2006			IPSEC(4)

home | help