Manual Pages  — IPSEC

System configuration requires the crypto(4) subsystem.

The packets can be passed to a virtual enc(4) interface, to perform packet filtering before outbound encryption and after decapsulation inbound.

To properly filter on the inner packets of an ipsec tunnel with firewalls, you can change the values of the following sysctls

Name Ta Default	Enable
net.inet.ipsec.filtertunnel Ta 0	1
net.inet6.ipsec6.filtertunnel Ta 0	1

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

The kernel code does not implement a dynamic encryption key exchange protocol 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.

Depending on the socket's address family, IPPROTO_IP or IPPROTO_IPV6 transport level and IP_IPSEC_POLICY or IPV6_IPSEC_POLICY socket options may be used to configure per-socket security policies. A properly-formed IPsec policy specification structure can be created using ipsec_set_policy(3) function and used as socket option value for the setsockopt(2) call.

When setting policies using the setkey(8) command, the "default" option instructs the system to use its default policy, as 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 association must exist for the packets to move, and not be dropped. These terms are defined in ipsec_set_policy(8).

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

If the kernel does not find a matching, system wide, policy then the default 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 Ta Type	Changeable
net.inet.ipsec.def_policy Ta integer	yes
net.inet6.ipsec6.def_policy Ta integer	yes

In addition the following variables are accessible via sysctl(8), for tweaking the kernel's IPsec behavior:

Name Ta Type	Changeable
net.inet.ipsec.ah_cleartos Ta integer	yes
net.inet.ipsec.ah_offsetmask Ta integer	yes
net.inet.ipsec.dfbit Ta integer	yes
net.inet.ipsec.ecn Ta integer	yes
net.inet.ipsec.debug Ta integer	yes
net.inet.ipsec.natt_cksum_policy Ta integer	yes
net.inet.ipsec.check_policy_history Ta integer	yes
net.inet6.ipsec6.ecn Ta integer	yes
net.inet6.ipsec6.debug Ta 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 devices 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 variable 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 regardless 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 notification), 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).
ipsec.natt_cksum_policy
	Controls how the kernel handles TCP and UDP checksums when ESP in UDP encapsulation is used for IPsec transport mode. If set to a non-zero value, the kernel fully recomputes checksums for inbound TCP segments and UDP datagrams after they are decapsulated and decrypted. If set to 0 and original addresses were configured for corresponding SA by the IKE daemon, the kernel incrementally recomputes checksums for inbound TCP segments and UDP datagrams. If addresses were not configured, the checksums are ignored.
ipsec.check_policy_history
	Enables strict policy checking for inbound packets. By default, inbound security policies check that packets handled by IPsec have been decrypted and authenticated. If this variable is set to a non-zero value, each packet handled by IPsec is checked against the history of IPsec security associations. The IPsec security protocol, mode, and SA addresses must match.

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

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

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

For FreeBSD 5.0 a fully locked IPsec implementation called fast_ipsec was brought in. The protocols drew heavily on the OpenBSD implementation of the IPsec protocols. The policy management code was derived from the KAME implementation found in their IPsec protocols. The fast_ipsec implementation lacked ip6(4) support but made use of the crypto(4) subsystem.

For FreeBSD 7.0 ip6(4) support was added to fast_ipsec. After this the old KAME IPsec implementation was dropped and fast_ipsec became what now is the only ipsec implementation in FreeBSD .

The IPcomp protocol may occasionally error because of zlib(3) problems.

This documentation needs more review.