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