.\" $OpenBSD: ipsec.4,v 1.47 2001/08/03 15:21:16 mpech Exp $
.\"
.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed by Niels Provos.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" Manual page, using -mandoc macros
.\"
.Dd September 5, 1997
.Dt IPSEC 4
.Os
.Sh NAME
.Nm IPsec
.Nd IP Security Protocol
.Sh NOTE
.Tn IPsec
is enabled with the following
.Xr sysctl 3
variables in
.Pa /etc/sysctl.conf :
.Bl -tag -width xxxxxxxxxxxxxxxxxxxxx
.It net.inet.esp.enable
Enable the ESP IPsec protocol
.It net.inet.ah.enable
Enable the AH IPsec protocol
.El
.Sh DESCRIPTION
.Tn IPsec
is a pair of protocols,
.Tn ESP
(for Encapsulating Security
Payload) and
.Tn AH
(for Authentication Header), which provide
security services for IP datagrams.
.Pp
The internet protocol,
.Tn IP ,
aka
.Tn IPv4 ,
does not inherently provide any
protection to your transferred data.  It does not even guarantee that
the sender is who he says he is.
.Tn IPsec
tries to remedy this.  There
are several kinds of properties you might want to add to your
communication, the most common are:
.Bl -inset -offset indent
.It	Confidentiality
- Make sure it is hard for anyone but the
receiver to understand what data has been communicated.
You do not want anyone to see your passwords when logging
into a remote machine over the Internet.
.It	Integrity
- Guarantee that the data does not get changed on
the way.  If you are on a line carrying invoicing data you
probably want to know that the amounts and account numbers
are correct and not altered while in-transit.
.It	Authenticity
- Sign your data so that others can see that it
is really you that sent it.  It is clearly nice to know that
documents are not forged.
.It	Replay protection
- We need ways to ensure a transaction can only be carried out once unless
we are authorized to repeat it.  I.e. it should not be possible for someone
to record a transaction, and then replaying it verbatim, in order to get an
effect of multiple transactions being received by the peer.  Consider the
attacker has got to know what the traffic is all about by other means than
cracking the encryption, and that the traffic causes events favourable for him,
like depositing money into his account.  We need to make sure he cannot just
replay that traffic later. WARNING: as per the standards specification, replay
protection is not performed when using manual-keyed IPsec (e.g., when using
.Xr ipsecadm 8 ) .
.El
.Pp
.Tn IPsec
can provide all of these properties, in two new protocols,
called
.Tn AH ,
Authentication header, and
.Tn ESP ,
Encapsulated security payload.
.Pp
.Tn ESP
can provide authentication, integrity, replay protection, and
confidentiality of the data (it secures everything in the packet that
follows the
.Tn IP
header). Replay protection requires authentication and
integrity (these two go always together). Confidentiality (encryption)
can be used with or without authentication/integrity. Similarly,
one could use authentication/integrity with or without confidentiality.
.Pp
.Tn AH
provides authentication, integrity, and replay protection (but not
confidentiality). Its main difference with
.Tn ESP
is that
.Tn AH
also secures
parts of the
.Tn IP
header of the packet (like the source/destination
addresses).
.Pp
These protocols need some parameters for each connection, telling
exactly how the wanted protection will be added.  These parameters are
collected in an entity called a security association, or SA for short.
Typical parameters are: encryption algorithm, hash algorithm,
encryption key, authentication key etc.  When two peers have setup
matching SAs at both ends, packets protected with one end's SA, will
be possible to verify and/or decrypt using the other end's SA.  The
only problem left is to see that both ends have matching SAa, which
can be done manually, or automatically with a key management daemon.
.Pp
Further information on manual SA establishment is described in
.Xr ipsecadm 8 ,
and we provide two key management daemons,
.Xr photurisd 8
and
.Xr isakmpd 8 .
.Pp
.Tn AH
works by doing a computation of a value depending on all of the payload
data, some of the
.Tn IP
header data and a certain secret value, the
authentication key and sending this value along with the rest of each
packet.  The receiver will do the same computation, and if the value matches,
he knows no one tampered with the data (integrity), the address information
(authenticity) or a sequence number (replay protection).  He knows this because
the secret authentication key makes sure no man in the middle can recompute the
correct value after altering the packet.  The algorithms used for the
computations are called hash algorithms and is a parameter in the SA, just
like the authentication key.
.Pp
.Tn ESP
optionally does almost everything that
.Tn AH
does except that it does not
protect the outer
.Tn IP
header but furthermore it encrypts the payload data
with an encryption algorithm using a secret encryption key.  Only the ones
knowing this key can decrypt the data, thus providing confidentiality.  Both
the algorithm and the encryption key are parameters of the SA.
.Pp
In order to identify a SA we need to have a unique name for it.  This name is
a triplet, consisting of the destination address, security parameter index
(aka SPI) and the security protocol.  Since the destination address is part
of the name, a SA is a unidirectional construct.  For a bidirectional
communication channel, two SAs are needed, one outgoing and one incoming,
where the destination address is our local IP address.  The SPI is just a
number that helps us making the name unique, it can be arbitrarily chosen
in the range 0x100 - 0xffffffff.  The security protocol number should be 50
for
.Tn ESP
and 51 for
.Tn AH ,
as these are the protocol numbers assigned by IANA.
.Pp
.Tn IPsec
can operate in two modes, either tunnel or transport mode.  In transport
mode the ordinary
.Tn IP
header is used to deliver the packets to their endpoint,
in tunnel mode the ordinary
.Tn IP
header just tells us the address of a
security gateway, knowing how to verify/decrypt the payload and forward the
packet to a destination given by another
.Tn IP
header contained in the
protected payload.  Tunnel mode can be used for establishing VPNs, virtual
private networks, where parts of the networks can be spread out over an
unsafe public network, but security gateways at each subnet are responsible
for encrypting and decrypting the data passing over the public net.  A SA
will hold information telling if it is a tunnel or transport mode SA, and for
tunnels, it will contain values to fill in into the outer
.Tn IP
header.
.Pp
The SA also holds a couple of other parameters, especially useful for
automatic keying, called lifetimes, which puts a limit on how much we can
use a SA for protecting our data.  These limits can be in wall-clock time
or in volume of our data.
.Pp
To better illustrate how
.Tn IPsec
works, consider a typical
.Tn TCP
packet:
.Bd -literal -offset indent
[IP header] [TCP header] [data...]
.Ed
.Pp
If we apply
.Tn ESP
in transport mode to the above packet, we will get:
.Bd -literal -offset indent
[IP header] [ESP header] [TCP header] [data...]
.Ed
.Pp
where everything after the
.Tn ESP
header is protected by whatever services of
.Tn ESP
we are using (authentication/integrity, replay protection,
confidentiality). This means the
.Tn IP
header itself is not protected.
.Pp
If we apply
.Tn ESP
in tunnel mode to the original packet, we would get:
.Bd -literal -offset indent
[IP header] [ESP header] [IP header] [TCP header] [data...]
.Ed
.Pp
where, again, everything after the
.Tn ESP
header is cryptographically
protected. Notice the insertion of an
.Tn IP
header between the
.Tn ESP
and
.Tn TCP
header. This mode of operation allows us to hide who the true
source and destination addresses of a packet are (since the protected
and the unprotected
.Tn IP
headers don't have to be exactly the same). A
typical application of this is in Virtual Private Networks (or VPNs),
where two firewalls use
.Tn IPsec
to secure the traffic of all the hosts behind them. For example:
.Bd -literal -offset indent
Net A <----> Firewall 1 <--- Internet ---> Firewall 2 <----> Net B
.Ed
.Pp
Firewall 1 and Firewall 2 can protect all communications between Net A
and Net B by using
.Tn IPsec
in tunnel mode, as illustrated above.
.Pp
This implementation makes use of a virtual interface
.Nm enc0 ,
which can be used in packet filters to specify those
packets that have been or will be processed by
.Tn IPsec.
.Pp
NAT can also be applied to
.Nm enc#
interfaces, but special care should be taken because of the interactions
between NAT and the IPsec flow matching, especially on the packet output path.
Inside the TCP/IP stack, packets go through the following stages:
.Bd -literal -offset indent
UL/R -> [X] -> PF/NAT(enc0) -> IPSec -> PF/NAT(IF) -> IF
UL/R <-------- PF/NAT(enc0) <- IPSec -> PF/NAT(IF) <- IF
.Ed
.Pp
With
.Tn IF
being the real interface and
.Tn UL/R
the Upper Layer or Routing code.
The
.Tn [X]
Stage on the output path represents the point where the packet
is matched against the IPsec flow database (SPD) to determine if and how
the packet has to be IPsec-processed. If, at this point, it is determined
that the packet should be IPSec-processed, it is processed by the PF/NAT code.
Unless PF drops the packet, it will then be IPsec-processed, even if the
packet has been modified by NAT.
.Pp
Security Associations can be set up manually with the
.Xr ipsecadm 8
utility or automatically with the
.Xr photurisd 8
or
.Xr isakmpd 8
key management daemons.
.Pp
The following
.Tn IP-level
.Xr setsockopt 2
and
.Xr getsockopt 2
options are specific to
.Xr ipsec 4 .
A socket can specify security levels for three different categories:
.Bl -tag -width IP_ESP_NETWORK_LEVEL
.It IP_AUTH_LEVEL
Specifies the use of authentication for packets sent or received by the
socket.
.It IP_ESP_TRANS_LEVEL
Specifies the use of encryption in transport mode for packets sent or
received by the socket.
.It IP_ESP_NETWORK_LEVEL
Specifies the use of encryption in tunnel mode.
.El
.Pp
For each of the categories there are five possible levels which
specify the security policy to use in that category:
.Bl -tag -width IPSEC_LEVEL_REQUIRE
.It IPSEC_LEVEL_BYPASS
Bypass the default system security policy. This option can only be used
by privileged processes.
This level is necessary for key management daemons like
.Xr photurisd 8
or
.Xr isakmpd 8 .
.It IPSEC_LEVEL_AVAIL
If a Security Association is available it will be used for sending packets
by that socket.
.It IPSEC_LEVEL_USE
Use IP Security for sending packets but still accept packets which are not
secured.
.It IPSEC_LEVEL_REQUIRE
Use IP Security for sending packets and also require IP Security for
received data.
.It IPSEC_LEVEL_UNIQUE
The outbound Security Association will only be used by this socket.
.El
.Pp
When a new socket is created, it is assigned the default system security
level in each category.
These levels can be queried with
.Xr getsockopt 2 .
Only a privileged process can lower the security level with a
.Xr setsockopt 2
call.
.Pp
For example, a server process might want to accept only authenticated
connections to prevent session hijacking.
It would issue the following
.Xr setsockopt 2
call:
.Bd -literal -offset 4n
int level = IPSEC_LEVEL_REQUIRE;
error = setsockopt(s, IPPROTO_IP, IP_AUTH_LEVEL, &level, sizeof(int));
.Ed
.Pp
The system does guarantee that it will succeed at establishing the
required security associations.  In any case a properly configured
key management daemon is required which listens to messages from the
kernel.
.Pp
A list of all security associations in the kernel tables can be
obtained via the kernfs file
.Aq Pa ipsec
(typically in
.Aq Pa /kern/ipsec
).
.Sh DIAGNOSTICS
A socket operation may fail with one of the following errors returned:
.Bl -tag -width [EINVAL]
.It Bq Er EACCES
when an attempt is made to lower the security level below the system default
by a non-privileged process.
.It Bq Er EINVAL
The length of option field did not match or an unknown security level
was given.
.El
.Pp
.Xr netstat 1
can be used to obtain some statistics about
.Tn AH
and
.Tn ESP
usage, using the
.Fl p
flag.  Using the
.Fl r
flag,
.Xr netstat 1
displays information about
.Tn IPsec
flows.
.Pp
.Xr vmstat 8
displays information about memory use by IPsec with the
.Fl m
flag (look for ``tdb'' and ``xform'' allocations).
.Sh BUGS
There's a lot more to be said on this subject. This is just a beginning.
At the moment the socket options are not fully implemented.
.Sh SEE ALSO
.Xr enc 4 ,
.Xr icmp 4 ,
.Xr inet 4 ,
.Xr ip 4 ,
.Xr netintro 4 ,
.Xr tcp 4 ,
.Xr udp 4 ,
.Xr ipsecadm 8 ,
.Xr isakmpd 8 ,
.Xr photurisd 8 ,
.Xr vpn 8
.Sh ACKNOWLEDGMENTS
The authors of the
.Tn IPsec
code proper are John Ioannidis, Angelos D. Keromytis, and Niels Provos.
.Pp
Niklas Hallqvist and Niels Provos are the authors of
.Xr isakmpd 8 .
.Pp
Eric Young's libdeslite was used in this implementation for the
DES algorithm.
.Pp
Steve Reid's SHA-1 code was also used.
.Pp
The
.Xr setsockopt 2 / Ns Xr getsockopt 2
interface follows somewhat loosely the draft-mcdonald-simple-ipsec-api,
which is work in progress.
.Sh HISTORY
The
.Tn IPsec
protocol design process was started in 1992 by John Ioannidis, Phil Karn
and William Allen Simpson. In 1995, the former wrote an
implementation for
.Bsx .
Angelos D. Keromytis ported it to
.Ox
and
.Nx .
The latest transforms and new features were
implemented by Angelos D. Keromytis and Niels Provos.