.\" $OpenBSD: ipsec.4,v 1.8 1998/05/24 23:46:59 provos Exp $ .\" Copyright 1997 Niels Provos .\" 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 .Fd #include .Fd #include .Fd #include .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 options 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 . .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.