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