path: root/share/man/man4/ipsec.4

.\" $OpenBSD: ipsec.4,v 1.10 1998/09/26 01:14:16 provos 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 SYNOPSIS
.Fd #include <net/encap.h>
.Fd #include <netinet/ip_ipsp.h>
.Fd #include <netinet/ip_esp.h>
.Fd #include <netinet/ip_ah.h>
.Ft int
.Fn socket AF_ENCAP SOCK_RAW AF_UNSPEC
.Sh DESCRIPTION
.Tn IPSec is a pair of protocols,
.Nm ESP
(for Encapsulting Security
Payload) and
.Nm AH
(for Authentication Header), which provide
security services for IP datagrams. Specifically,
.Nm ESP
provides
confidentiality, connectionless
integrity, anti-replay service and limited traffic flow
confidentiality. It optionally provides data origin authentication.
.Nm AH
provides connectionless integrity, data
origin authentication and anti-replay service.
.Pp
This is done by inserting the appropriate header
.Nm ( ESP
or
.Nm AH )
between the IP header and the payload. The inserted header,
along with the IP header destination address, provide enough
information to find the relevant state in the kernel (security
association) and handle the packet appropriately (decrypt,
authenticate etc.)
.Pp
An SA (Security Association) is uniquely defined by the
.Nm SPI
(Security Parameter Index), which is a 32-bit integer,
the remote IP address and the security protocol.
.Pp
The payload can be any of the usual IP protocols (TCP, UDP, ICMP
etc.) or IP itself, for those situations where IP tunneling is
required.
.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 successfully processed by IPSec.
.Pp
Security Associations can be set up manually with
the
.Xr ipsecadm 1
utility or the
.Xr photurisd 8
key management daemon.
.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 catagory:
.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 .
.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
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
.Dv EMT_NOTIFY
messages on a
.Dv PF_ENCAP
socket.
.Sh DIAGNOSTICS
A socket operation may fail with one of the following errors returned:
.Bl -tag -width [EINVAL]
.It Bq Er EACESS
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
.Sh BUGS
There's a lot more to be said on this subject. This is just a beginning.
.Br
At the moment the socket options are not fully implemented.
.Sh SEE ALSO
.Xr ip 4 ,
.Xr intro 4 ,
.Xr inet 4 ,
.Xr tcp 4 ,
.Xr udp 4 ,
.Xr icmp 4 ,
.Xr ipsecadm 1 ,
.Xr photurisd 8 ,
.Xr vpn 8 .
.Sh ACKNOWLEDGMENTS
The authors of this code are John Ioannidis, Angelos D.
Keromytis and Niels Provos.
.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 getsockotp 2
interface follows somewhat loosely the draft-mcdonald-simple-ipsec-api,
which is work in progress.
.Sh HISTORY
The IPsec protocol started in 1992, by John Ioannidis, Phil Karn
and William Allen Simpson. In 1995, the former wrote an
implementation for BSD/OS. Angelos D. Keromytis ported it to
OpenBSD and NetBSD. The latest transforms and new features were
implemented by Angelos D. Keromytis and Niels Provos.