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