1.\" $OpenBSD: ipsec.4,v 1.89 2022/12/23 07:16:55 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: December 23 2022 $ 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 2 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, 121it knows no one tampered with the data (integrity), the address information 122(authenticity) or a sequence number (replay protection). 123It 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 ipsec.conf 5 . 152Information on automated key management for IKEv1 can be found in 153.Xr isakmpd 8 154and for IKEv2 in 155.Xr iked.conf 5 . 156.Ss Security Parameter Indexes (SPIs) 157In order to identify an SA, we need to have a unique name for it. 158This name is a triplet, consisting of the destination address, security 159parameter index (aka SPI) and the security protocol (ESP or AH). 160Since the destination address is part of the name, an SA is necessarily a 161unidirectional construct. 162For a bidirectional communication channel, two SAs are required, one 163outgoing and one incoming, where the destination address is our local 164IP address. 165The SPI is just a number that helps us make the name unique; 166it can be arbitrarily chosen in the range 0x100 \- 0xffffffff. 167The security protocol number should be 50 for ESP and 51 for AH, 168as these are the protocol numbers assigned by IANA. 169.Ss Modes of Operation 170IPsec can operate in two modes, either tunnel or transport mode. 171In transport mode the ordinary IP 172header is used to deliver the packets to their endpoint; 173in tunnel mode the ordinary IP 174header just tells us the address of a security gateway 175which knows how to verify/decrypt the payload and forward the 176packet to a destination given by another IP 177header contained in the protected payload. 178Tunnel mode can be used for establishing virtual private networks (VPNs), 179where parts of the networks can be spread out over an 180unsafe public network, but security gateways at each subnet are responsible 181for encrypting and decrypting the data passing over the public net. 182An SA will contain information specifying 183whether it is a tunnel or transport mode SA, 184and for tunnels it will contain values to fill in into the outer IP header. 185.Ss Lifetimes 186The SA also holds a couple of other parameters, especially useful for 187automatic keying, called lifetimes, which puts a limit on how much we can 188use an SA for protecting our data. 189These limits can be in wall-clock time or in volume of our data. 190.Ss IPsec Examples 191To better illustrate how IPsec works, consider a typical TCP packet: 192.Pp 193.Dl [IP header] [TCP header] [data...] 194.Pp 195If we apply ESP in transport mode to the above packet, we will get: 196.Pp 197.Dl [IP header] [ESP header] [TCP header] [data...] 198.Pp 199Everything after the ESP 200header is protected by whatever services of ESP we are using 201(authentication/integrity, replay protection, confidentiality). 202This means the IP header itself is not protected. 203.Pp 204If we apply ESP in tunnel mode to the original packet, we would get: 205.Pp 206.Dl [IP header] [ESP header] [IP header] [TCP header] [data...] 207.Pp 208Again, everything after the ESP header is cryptographically protected. 209Notice the insertion of an IP header between the ESP and TCP header. 210This mode of operation allows us to hide who the true 211source and destination addresses of a packet are 212(since the protected and the unprotected IP 213headers don't have to be exactly the same). 214A typical application of this is in Virtual Private Networks (or VPNs), 215where two firewalls use IPsec 216to secure the traffic of all the hosts behind them. 217For example: 218.Bd -literal -offset indent 219Net A <----> Firewall 1 <--- Internet ---> Firewall 2 <----> Net B 220.Ed 221.Pp 222Firewall 1 and Firewall 2 can protect all communications between Net A 223and Net B by using IPsec in tunnel mode, as illustrated above. 224.Pp 225This implementation makes use of a virtual interface, 226.Nm enc0 , 227which can be used in packet filters to specify those packets that have 228been or will be processed by IPsec. 229.Pp 230NAT can also be applied to 231.Nm enc# 232interfaces, but special care should be taken because of the interactions 233between NAT and the IPsec flow matching, especially on the packet output path. 234Inside the TCP/IP stack, packets go through the following stages: 235.Bd -literal -offset indent 236UL/R -> [X] -> PF/NAT(enc0) -> IPsec -> PF/NAT(IF) -> IF 237UL/R <-------- PF/NAT(enc0) <- IPsec <- PF/NAT(IF) <- IF 238.Ed 239.Pp 240With IF being the real interface and UL/R the Upper Layer or Routing code. 241The [X] 242stage on the output path represents the point where the packet 243is matched against the IPsec flow database (SPD) to determine if and how 244the packet has to be IPsec-processed. 245If, at this point, it is determined that the packet should be IPsec-processed, 246it is processed by the PF/NAT code. 247Unless PF drops the packet, it will then be IPsec-processed, even if the 248packet has been modified by NAT. 249.Pp 250Security Associations can be set up manually with 251.Xr ipsecctl 8 252or automatically with the 253.Xr isakmpd 8 254or 255.Xr iked 8 256key management daemons. 257.Ss Additional Variables 258A number of 259.Xr sysctl 8 260variables are relevant to 261.Nm . 262These are generally 263.Va net.inet.ah.* , 264.Va net.inet.esp.* , 265.Va net.inet.ip.forwarding , 266.Va net.inet6.ip6.forwarding , 267and 268.Va net.inet.ip.ipsec-* . 269Full explanations can be found in 270.Xr sysctl 2 , 271and variables can be set using the 272.Xr sysctl 8 273interface. 274.Pp 275A number of kernel options are also relevant to 276.Nm . 277See 278.Xr options 4 279for further information. 280.Ss API Details 281The following IP-level 282.Xr setsockopt 2 283and 284.Xr getsockopt 2 285options are specific to 286.Nm ipsec . 287A socket can specify security levels for three different categories: 288.Bl -tag -width IP_ESP_NETWORK_LEVEL -offset 2n 289.It IP_AUTH_LEVEL 290Specifies the use of authentication for packets sent or received by the 291socket. 292.It IP_ESP_TRANS_LEVEL 293Specifies the use of encryption in transport mode for packets sent or 294received by the socket. 295.It IP_ESP_NETWORK_LEVEL 296Specifies the use of encryption in tunnel mode. 297.El 298.Pp 299For each of the categories there are five possible levels which 300specify the security policy to use in that category: 301.Bl -tag -width IPSEC_LEVEL_REQUIRE -offset 2n 302.It IPSEC_LEVEL_BYPASS 303Bypass the default system security policy. 304This option can only be used by privileged processes. 305This level is necessary for the key management daemon, 306.Xr isakmpd 8 . 307.It IPSEC_LEVEL_AVAIL 308If a Security Association is available, it will be used for sending packets 309by that socket. 310.It IPSEC_LEVEL_USE 311Use IP Security for sending packets but still accept packets which are not 312secured. 313.It IPSEC_LEVEL_REQUIRE 314Use IP Security for sending packets and also require IP Security for 315received data. 316.It IPSEC_LEVEL_UNIQUE 317The outbound Security Association will only be used by this socket. 318.El 319.Pp 320When a new socket is created, it is assigned the default system security 321level in each category. 322These levels can be queried with 323.Xr getsockopt 2 . 324Only a privileged process can lower the security level with a 325.Xr setsockopt 2 326call. 327.Pp 328For example, a server process might want to accept only authenticated 329connections to prevent session hijacking. 330It would issue the following 331.Xr setsockopt 2 332call: 333.Bd -literal -offset 4n 334int level = IPSEC_LEVEL_REQUIRE; 335error = setsockopt(s, IPPROTO_IP, IP_AUTH_LEVEL, &level, sizeof(int)); 336.Ed 337.Pp 338The system does guarantee that it will succeed at establishing the 339required security associations. 340In any case a properly configured key management daemon is required which 341listens to messages from the kernel. 342.Pp 343A list of all security associations in the kernel tables can be 344obtained using the 345.Xr ipsecctl 8 346command. 347.Sh DIAGNOSTICS 348A socket operation may fail with one of the following errors returned: 349.Bl -tag -width [EINVAL] 350.It Bq Er EACCES 351An attempt was made to lower the security level below the system default 352by a non-privileged process. 353.It Bq Er EINVAL 354The length of option field did not match or an unknown security level 355was given. 356.El 357.Pp 358.Xr netstat 1 359can be used to obtain some statistics about AH or ESP usage: 360.Bd -literal -offset indent 361$ netstat -s -p ah 362$ netstat -s -p esp 363.Ed 364.Pp 365The 366.Xr ipsecctl 8 367command can be used to display information about IPsec flows. 368.Pp 369.Xr vmstat 8 370displays information about memory use by IPsec with the 371.Fl m 372flag (look for 373.Dq tdb 374and 375.Dq xform 376allocations). 377.Sh SEE ALSO 378.Xr enc 4 , 379.\".Xr ipcomp 4 , 380.Xr options 4 , 381.Xr ipsec.conf 5 , 382.Xr iked 8 , 383.Xr ipsecctl 8 , 384.Xr isakmpd 8 , 385.Xr sysctl 8 386.Sh HISTORY 387IPsec was originally designed to provide security services 388for Internet Protocol IPv6. 389It has since been engineered to provide those services for 390the original Internet Protocol, IPv4. 391.Pp 392The IPsec protocol design process was started in 1992 by 393John Ioannidis, Phil Karn, and William Allen Simpson. 394In 1995, the former wrote an implementation for 395.Bsx . 396Angelos D. Keromytis ported it to 397.Ox 398and 399.Nx . 400The latest transforms and new features were 401implemented by Angelos D. Keromytis and Niels Provos. 402.Sh AUTHORS 403.An -nosplit 404The authors of the IPsec code proper are 405.An John Ioannidis , 406.An Angelos D. Keromytis , 407and 408.An Niels Provos . 409.Pp 410.An Niklas Hallqvist 411and 412.An Niels Provos 413are the authors of 414.Xr isakmpd 8 . 415.Pp 416.An Eric Young Ap s 417libdeslite was used in this implementation for the DES algorithm. 418.Pp 419.An Steve Reid Ap s 420SHA-1 code was also used. 421.Pp 422The 423.Xr setsockopt 2 Ns / Ns Xr getsockopt 2 424interface follows somewhat loosely the 425draft-mcdonald-simple-ipsec-api 426(since expired). 427.Sh BUGS 428There's a lot more to be said on this subject. 429This is just a beginning. 430At the moment the socket options are not fully implemented. 431