1.\" $OpenBSD: ipsec.4,v 1.47 2001/08/03 15:21:16 mpech Exp $ 2.\" 3.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by Niels Provos. 17.\" 4. The name of the author may not be used to endorse or promote products 18.\" derived from this software without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 21.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 22.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 23.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 25.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 29.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.\" Manual page, using -mandoc macros 32.\" 33.Dd September 5, 1997 34.Dt IPSEC 4 35.Os 36.Sh NAME 37.Nm IPsec 38.Nd IP Security Protocol 39.Sh NOTE 40.Tn IPsec 41is enabled with the following 42.Xr sysctl 3 43variables in 44.Pa /etc/sysctl.conf : 45.Bl -tag -width xxxxxxxxxxxxxxxxxxxxx 46.It net.inet.esp.enable 47Enable the ESP IPsec protocol 48.It net.inet.ah.enable 49Enable the AH IPsec protocol 50.El 51.Sh DESCRIPTION 52.Tn IPsec 53is a pair of protocols, 54.Tn ESP 55(for Encapsulating Security 56Payload) and 57.Tn AH 58(for Authentication Header), which provide 59security services for IP datagrams. 60.Pp 61The internet protocol, 62.Tn IP , 63aka 64.Tn IPv4 , 65does not inherently provide any 66protection to your transferred data. It does not even guarantee that 67the sender is who he says he is. 68.Tn IPsec 69tries to remedy this. There 70are several kinds of properties you might want to add to your 71communication, the most common are: 72.Bl -inset -offset indent 73.It Confidentiality 74- Make sure it is hard for anyone but the 75receiver to understand what data has been communicated. 76You do not want anyone to see your passwords when logging 77into a remote machine over the Internet. 78.It Integrity 79- Guarantee that the data does not get changed on 80the way. If you are on a line carrying invoicing data you 81probably want to know that the amounts and account numbers 82are correct and not altered while in-transit. 83.It Authenticity 84- Sign your data so that others can see that it 85is really you that sent it. It is clearly nice to know that 86documents are not forged. 87.It Replay protection 88- We need ways to ensure a transaction can only be carried out once unless 89we are authorized to repeat it. I.e. it should not be possible for someone 90to record a transaction, and then replaying it verbatim, in order to get an 91effect of multiple transactions being received by the peer. Consider the 92attacker has got to know what the traffic is all about by other means than 93cracking the encryption, and that the traffic causes events favourable for him, 94like depositing money into his account. We need to make sure he cannot just 95replay that traffic later. WARNING: as per the standards specification, replay 96protection is not performed when using manual-keyed IPsec (e.g., when using 97.Xr ipsecadm 8 ) . 98.El 99.Pp 100.Tn IPsec 101can provide all of these properties, in two new protocols, 102called 103.Tn AH , 104Authentication header, and 105.Tn ESP , 106Encapsulated security payload. 107.Pp 108.Tn ESP 109can provide authentication, integrity, replay protection, and 110confidentiality of the data (it secures everything in the packet that 111follows the 112.Tn IP 113header). Replay protection requires authentication and 114integrity (these two go always together). Confidentiality (encryption) 115can be used with or without authentication/integrity. Similarly, 116one could use authentication/integrity with or without confidentiality. 117.Pp 118.Tn AH 119provides authentication, integrity, and replay protection (but not 120confidentiality). Its main difference with 121.Tn ESP 122is that 123.Tn AH 124also secures 125parts of the 126.Tn IP 127header of the packet (like the source/destination 128addresses). 129.Pp 130These protocols need some parameters for each connection, telling 131exactly how the wanted protection will be added. These parameters are 132collected in an entity called a security association, or SA for short. 133Typical parameters are: encryption algorithm, hash algorithm, 134encryption key, authentication key etc. When two peers have setup 135matching SAs at both ends, packets protected with one end's SA, will 136be possible to verify and/or decrypt using the other end's SA. The 137only problem left is to see that both ends have matching SAa, which 138can be done manually, or automatically with a key management daemon. 139.Pp 140Further information on manual SA establishment is described in 141.Xr ipsecadm 8 , 142and we provide two key management daemons, 143.Xr photurisd 8 144and 145.Xr isakmpd 8 . 146.Pp 147.Tn AH 148works by doing a computation of a value depending on all of the payload 149data, some of the 150.Tn IP 151header data and a certain secret value, the 152authentication key and sending this value along with the rest of each 153packet. The receiver will do the same computation, and if the value matches, 154he knows no one tampered with the data (integrity), the address information 155(authenticity) or a sequence number (replay protection). He knows this because 156the secret authentication key makes sure no man in the middle can recompute the 157correct value after altering the packet. The algorithms used for the 158computations are called hash algorithms and is a parameter in the SA, just 159like the authentication key. 160.Pp 161.Tn ESP 162optionally does almost everything that 163.Tn AH 164does except that it does not 165protect the outer 166.Tn IP 167header but furthermore it encrypts the payload data 168with an encryption algorithm using a secret encryption key. Only the ones 169knowing this key can decrypt the data, thus providing confidentiality. Both 170the algorithm and the encryption key are parameters of the SA. 171.Pp 172In order to identify a SA we need to have a unique name for it. This name is 173a triplet, consisting of the destination address, security parameter index 174(aka SPI) and the security protocol. Since the destination address is part 175of the name, a SA is a unidirectional construct. For a bidirectional 176communication channel, two SAs are needed, one outgoing and one incoming, 177where the destination address is our local IP address. The SPI is just a 178number that helps us making the name unique, it can be arbitrarily chosen 179in the range 0x100 - 0xffffffff. The security protocol number should be 50 180for 181.Tn ESP 182and 51 for 183.Tn AH , 184as these are the protocol numbers assigned by IANA. 185.Pp 186.Tn IPsec 187can operate in two modes, either tunnel or transport mode. In transport 188mode the ordinary 189.Tn IP 190header is used to deliver the packets to their endpoint, 191in tunnel mode the ordinary 192.Tn IP 193header just tells us the address of a 194security gateway, knowing how to verify/decrypt the payload and forward the 195packet to a destination given by another 196.Tn IP 197header contained in the 198protected payload. Tunnel mode can be used for establishing VPNs, virtual 199private networks, where parts of the networks can be spread out over an 200unsafe public network, but security gateways at each subnet are responsible 201for encrypting and decrypting the data passing over the public net. A SA 202will hold information telling if it is a tunnel or transport mode SA, and for 203tunnels, it will contain values to fill in into the outer 204.Tn IP 205header. 206.Pp 207The SA also holds a couple of other parameters, especially useful for 208automatic keying, called lifetimes, which puts a limit on how much we can 209use a SA for protecting our data. These limits can be in wall-clock time 210or in volume of our data. 211.Pp 212To better illustrate how 213.Tn IPsec 214works, consider a typical 215.Tn TCP 216packet: 217.Bd -literal -offset indent 218[IP header] [TCP header] [data...] 219.Ed 220.Pp 221If we apply 222.Tn ESP 223in transport mode to the above packet, we will get: 224.Bd -literal -offset indent 225[IP header] [ESP header] [TCP header] [data...] 226.Ed 227.Pp 228where everything after the 229.Tn ESP 230header is protected by whatever services of 231.Tn ESP 232we are using (authentication/integrity, replay protection, 233confidentiality). This means the 234.Tn IP 235header itself is not protected. 236.Pp 237If we apply 238.Tn ESP 239in tunnel mode to the original packet, we would get: 240.Bd -literal -offset indent 241[IP header] [ESP header] [IP header] [TCP header] [data...] 242.Ed 243.Pp 244where, again, everything after the 245.Tn ESP 246header is cryptographically 247protected. Notice the insertion of an 248.Tn IP 249header between the 250.Tn ESP 251and 252.Tn TCP 253header. This mode of operation allows us to hide who the true 254source and destination addresses of a packet are (since the protected 255and the unprotected 256.Tn IP 257headers don't have to be exactly the same). A 258typical application of this is in Virtual Private Networks (or VPNs), 259where two firewalls use 260.Tn IPsec 261to secure the traffic of all the hosts behind them. For example: 262.Bd -literal -offset indent 263Net A <----> Firewall 1 <--- Internet ---> Firewall 2 <----> Net B 264.Ed 265.Pp 266Firewall 1 and Firewall 2 can protect all communications between Net A 267and Net B by using 268.Tn IPsec 269in tunnel mode, as illustrated above. 270.Pp 271This implementation makes use of a virtual interface 272.Nm enc0 , 273which can be used in packet filters to specify those 274packets that have been or will be processed by 275.Tn IPsec. 276.Pp 277NAT can also be applied to 278.Nm enc# 279interfaces, but special care should be taken because of the interactions 280between NAT and the IPsec flow matching, especially on the packet output path. 281Inside the TCP/IP stack, packets go through the following stages: 282.Bd -literal -offset indent 283UL/R -> [X] -> PF/NAT(enc0) -> IPSec -> PF/NAT(IF) -> IF 284UL/R <-------- PF/NAT(enc0) <- IPSec -> PF/NAT(IF) <- IF 285.Ed 286.Pp 287With 288.Tn IF 289being the real interface and 290.Tn UL/R 291the Upper Layer or Routing code. 292The 293.Tn [X] 294Stage on the output path represents the point where the packet 295is matched against the IPsec flow database (SPD) to determine if and how 296the packet has to be IPsec-processed. If, at this point, it is determined 297that the packet should be IPSec-processed, it is processed by the PF/NAT code. 298Unless PF drops the packet, it will then be IPsec-processed, even if the 299packet has been modified by NAT. 300.Pp 301Security Associations can be set up manually with the 302.Xr ipsecadm 8 303utility or automatically with the 304.Xr photurisd 8 305or 306.Xr isakmpd 8 307key management daemons. 308.Pp 309The following 310.Tn IP-level 311.Xr setsockopt 2 312and 313.Xr getsockopt 2 314options are specific to 315.Xr ipsec 4 . 316A socket can specify security levels for three different categories: 317.Bl -tag -width IP_ESP_NETWORK_LEVEL 318.It IP_AUTH_LEVEL 319Specifies the use of authentication for packets sent or received by the 320socket. 321.It IP_ESP_TRANS_LEVEL 322Specifies the use of encryption in transport mode for packets sent or 323received by the socket. 324.It IP_ESP_NETWORK_LEVEL 325Specifies the use of encryption in tunnel mode. 326.El 327.Pp 328For each of the categories there are five possible levels which 329specify the security policy to use in that category: 330.Bl -tag -width IPSEC_LEVEL_REQUIRE 331.It IPSEC_LEVEL_BYPASS 332Bypass the default system security policy. This option can only be used 333by privileged processes. 334This level is necessary for key management daemons like 335.Xr photurisd 8 336or 337.Xr isakmpd 8 . 338.It IPSEC_LEVEL_AVAIL 339If a Security Association is available it will be used for sending packets 340by that socket. 341.It IPSEC_LEVEL_USE 342Use IP Security for sending packets but still accept packets which are not 343secured. 344.It IPSEC_LEVEL_REQUIRE 345Use IP Security for sending packets and also require IP Security for 346received data. 347.It IPSEC_LEVEL_UNIQUE 348The outbound Security Association will only be used by this socket. 349.El 350.Pp 351When a new socket is created, it is assigned the default system security 352level in each category. 353These levels can be queried with 354.Xr getsockopt 2 . 355Only a privileged process can lower the security level with a 356.Xr setsockopt 2 357call. 358.Pp 359For example, a server process might want to accept only authenticated 360connections to prevent session hijacking. 361It would issue the following 362.Xr setsockopt 2 363call: 364.Bd -literal -offset 4n 365int level = IPSEC_LEVEL_REQUIRE; 366error = setsockopt(s, IPPROTO_IP, IP_AUTH_LEVEL, &level, sizeof(int)); 367.Ed 368.Pp 369The system does guarantee that it will succeed at establishing the 370required security associations. In any case a properly configured 371key management daemon is required which listens to messages from the 372kernel. 373.Pp 374A list of all security associations in the kernel tables can be 375obtained via the kernfs file 376.Aq Pa ipsec 377(typically in 378.Aq Pa /kern/ipsec 379). 380.Sh DIAGNOSTICS 381A socket operation may fail with one of the following errors returned: 382.Bl -tag -width [EINVAL] 383.It Bq Er EACCES 384when an attempt is made to lower the security level below the system default 385by a non-privileged process. 386.It Bq Er EINVAL 387The length of option field did not match or an unknown security level 388was given. 389.El 390.Pp 391.Xr netstat 1 392can be used to obtain some statistics about 393.Tn AH 394and 395.Tn ESP 396usage, using the 397.Fl p 398flag. Using the 399.Fl r 400flag, 401.Xr netstat 1 402displays information about 403.Tn IPsec 404flows. 405.Pp 406.Xr vmstat 8 407displays information about memory use by IPsec with the 408.Fl m 409flag (look for ``tdb'' and ``xform'' allocations). 410.Sh BUGS 411There's a lot more to be said on this subject. This is just a beginning. 412At the moment the socket options are not fully implemented. 413.Sh SEE ALSO 414.Xr enc 4 , 415.Xr icmp 4 , 416.Xr inet 4 , 417.Xr ip 4 , 418.Xr netintro 4 , 419.Xr tcp 4 , 420.Xr udp 4 , 421.Xr ipsecadm 8 , 422.Xr isakmpd 8 , 423.Xr photurisd 8 , 424.Xr vpn 8 425.Sh ACKNOWLEDGMENTS 426The authors of the 427.Tn IPsec 428code proper are John Ioannidis, Angelos D. Keromytis, and Niels Provos. 429.Pp 430Niklas Hallqvist and Niels Provos are the authors of 431.Xr isakmpd 8 . 432.Pp 433Eric Young's libdeslite was used in this implementation for the 434DES algorithm. 435.Pp 436Steve Reid's SHA-1 code was also used. 437.Pp 438The 439.Xr setsockopt 2 / Ns Xr getsockopt 2 440interface follows somewhat loosely the draft-mcdonald-simple-ipsec-api, 441which is work in progress. 442.Sh HISTORY 443The 444.Tn IPsec 445protocol design process was started in 1992 by John Ioannidis, Phil Karn 446and William Allen Simpson. In 1995, the former wrote an 447implementation for 448.Bsx . 449Angelos D. Keromytis ported it to 450.Ox 451and 452.Nx . 453The latest transforms and new features were 454implemented by Angelos D. Keromytis and Niels Provos. 455