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
(inet(4) 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 algo

rithms. AH
both authenticates guarantees the integrity of an IP packet

by attaching
a cryptographic checksum computed using one-way hash func

tions. ipsec
has operates in one of two modes: transport mode or tunnel

mode. Transport mode is used to protect peer-to-peer communication be

tween 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. Pol

icy management
dictates when new security associations created or de

stroyed.

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,
setsockopt(2) operations, and sysctl(3) interface. The ker

nel 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 behav

ior, and
sysctl(3) interface is used to define host-wide default be

havior.

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 imple

mented 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 ``de

fault'' option
you can have the system use its default policy, explained

below, for processing packets. The following sysctl variables are avail

able 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 ``re

quire'', 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 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
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 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
kernel'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 in

ter-operate
with devices that implement RFC1826 AH. It should

be set to nonzero (clear the type-of-service field) for RFC2402

conformance.

ipsec.ah_offsetmask

During AH authentication data computation, the ker

nel 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 de

vices that implement RFC1826 AH. It should be set to zero (clear

the fragment
offset field during computation) for RFC2402 confor

mance.

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 encapsula

tion/decapsulation
behavior will be friendly to ECN (explicit conges

tion 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).

Variables under the net.inet6.ipsec6 tree have similar mean

ings to those
described above.

PROTOCOLS

The ipsec protocol acts as a plug-in to the inet(4) and in

et6(4) protocols and therefore supports most of the protocols defined

upon those IPlayer protocols. The icmp(4) and icmp6(4) protocols may be

have 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), in

tro(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 proto

cols 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
encapsulating policy with AH (like ``esp/tunnel/A-B/use
ah/transport/A-B/require''), tunnelled packets will be re

jected. This is
because the policy check is enforced on the inner packet on

reception,
and AH authenticates encapsulating (outer) packet, not the

encapsulated
(inner) packet (so for the receiving kernel there is no sign

of authenticity). The issue will be solved when we revamp our policy

engine to
keep all the packet decapsulation history.

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.

BSD February 14, 2006

BSD