1.\" $NetBSD: ipsec.4,v 1.43 2018/01/10 12:16:39 wiz Exp $ 2.\" $KAME: ipsec.4,v 1.17 2001/06/27 15:25:10 itojun Exp $ 3.\" 4.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the project nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd January 10, 2018 32.Dt IPSEC 4 33.Os 34.Sh NAME 35.Nm ipsec 36.Nd IP security protocol 37.Sh DESCRIPTION 38This manual pages describes the IPsec protocol. 39For the network device driver please see 40.Xr ipsecif 4 . 41.Pp 42.Nm 43is a security protocol in the Internet Protocol (IP) layer. 44.Nm 45is defined for both IPv4 and IPv6 46.Po 47.Xr inet 4 48and 49.Xr inet6 4 50.Pc . 51.Nm 52consists of two sub-protocols: 53.Bl -hang 54.It Em Encapsulated Security Payload Pq ESP 55protects IP payloads from wire-tapping (interception) by encrypting them with 56secret key cryptography algorithms. 57.It Em Authentication Header Pq AH 58guarantees the integrity of IP packets 59and protects them from intermediate alteration or impersonation, 60by attaching cryptographic checksums computed by one-way hash functions. 61.El 62.Pp 63.Nm 64has two operation modes: 65.Bl -hang 66.It Em Transport mode 67is for protecting peer-to-peer communication between end nodes. 68.It Em Tunnel mode 69includes IP-in-IP encapsulation operation 70and is designed for security gateways, as in Virtual Private Network (VPN) 71configurations. 72.El 73.Pp 74Since version 6, 75.Nx 76uses the IPsec implementation formerly known as FAST_IPSEC. 77Its specifics and kernel options are described in the 78.Xr fast_ipsec 4 79manual page. 80.Ss Kernel interface 81.Nm 82is controlled by two engines in the kernel: one for key management 83and one for policy. 84.Pp 85The key management engine can be accessed from userland by using 86.Dv PF_KEY 87sockets. 88The 89.Dv PF_KEY 90socket API is defined in RFC2367. 91.Pp 92The policy engine can be controlled through the 93.Dv PF_KEY 94API, 95.Xr setsockopt 2 96operations, and 97the 98.Xr sysctl 3 99interface. 100The kernel implements an 101extended version of the 102.Dv PF_KEY 103interface and allows you to define IPsec policy like per-packet filters. 104.Xr setsockopt 2 105is used to define per-socket behavior, and 106.Xr sysctl 3 107is used to define host-wide default behavior. 108.Pp 109The kernel does not implement dynamic encryption key exchange protocols 110like IKE 111.Pq Internet Key Exchange . 112That should be done in userland 113.Pq usually as a daemon , 114using the APIs described above. 115.\" 116.Ss Policy management 117The kernel implements experimental policy management code. 118You can manage the IPsec policy in two ways. 119One is to configure per-socket policy using 120.Xr setsockopt 2 . 121The other is to configure kernel packet filter-based policy using the 122.Dv PF_KEY 123interface, via 124.Xr setkey 8 . 125In both cases, IPsec policy must be specified with syntax described in 126.Xr ipsec_set_policy 3 . 127.Pp 128With 129.Xr setsockopt 2 , 130you can define IPsec policy on a per-socket basis. 131You can enforce particular IPsec policy on packets that go through a 132particular socket. 133.Pp 134With 135.Xr setkey 8 136you can define IPsec policy for packets using a form of packet 137filtering rules. 138See 139.Xr setkey 8 140for details. 141.Pp 142In the latter case, 143.Dq Li default 144policy is allowed for use with 145.Xr setkey 8 . 146By configuring policy to 147.Li default , 148you can refer to system-wide 149.Xr sysctl 8 150variables for default settings. 151The following variables are available. 152.Li 1 153means 154.Dq Li use , 155and 156.Li 2 157means 158.Dq Li require 159in the syntax. 160.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx 161.It Sy Name Ta Sy Type Ta Sy Changeable 162.It net.inet.ipsec.esp_trans_deflev Ta integer Ta yes 163.It net.inet.ipsec.esp_net_deflev Ta integer Ta yes 164.It net.inet.ipsec.ah_trans_deflev Ta integer Ta yes 165.It net.inet.ipsec.ah_net_deflev Ta integer Ta yes 166.It net.inet6.ipsec6.esp_trans_deflev Ta integer Ta yes 167.It net.inet6.ipsec6.esp_net_deflev Ta integer Ta yes 168.It net.inet6.ipsec6.ah_trans_deflev Ta integer Ta yes 169.It net.inet6.ipsec6.ah_net_deflev Ta integer Ta yes 170.El 171.Pp 172If the kernel finds no matching policy, the system-wide default 173value is applied. 174System-wide defaults are specified by the following 175.Xr sysctl 8 176variables. 177.Li 0 178means 179.Dq Li discard 180which asks the kernel to drop the packet. 181.Li 1 182means 183.Dq Li none . 184.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx 185.It Sy Name Ta Sy Type Ta Sy Changeable 186.It net.inet.ipsec.def_policy Ta integer Ta yes 187.It net.inet6.ipsec6.def_policy Ta integer Ta yes 188.El 189.\" 190.Ss Miscellaneous sysctl variables 191The following variables are accessible via 192.Xr sysctl 8 , 193for tweaking kernel IPsec behavior: 194.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx 195.It Sy Name Ta Sy Type Ta Sy Changeable 196.It net.inet.ipsec.ah_cleartos Ta integer Ta yes 197.It net.inet.ipsec.ah_offsetmask Ta integer Ta yes 198.It net.inet.ipsec.crypto_support Ta integer Ta yes 199.It net.inet.ipsec.dfbit Ta integer Ta yes 200.It net.inet.ipsec.ecn Ta integer Ta yes 201.It net.inet.ipsec.debug Ta integer Ta yes 202.It net.inet6.ipsec6.ecn Ta integer Ta yes 203.It net.inet6.ipsec6.debug Ta integer Ta yes 204.El 205.Pp 206The variables are interpreted as follows: 207.Bl -tag -width "123456" 208.It Li ipsec.ah_cleartos 209If set to non-zero, the kernel clears the type-of-service field in the 210IPv4 header during AH authentication data computation. 211The variable is for tweaking AH behavior to interoperate with devices that 212implement RFC1826 AH. 213It should be set to non-zero 214.Pq clear the type-of-service field 215for RFC2402 conformance. 216.It Li ipsec.ah_offsetmask 217During AH authentication data computation, the kernel will include a 21816 bit fragment offset field 219.Pq including flag bits 220in the IPv4 header, after computing logical AND with the variable. 221The variable is for tweaking AH behavior to interoperate with devices that 222implement RFC1826 AH. 223It should be set to zero 224.Pq clear the fragment offset field during computation 225for RFC2402 conformance. 226.It Li ipsec.crypto_support 227This variable configures the kernel behavior for selecting encryption drivers. 228If set to > 0, the kernel will select a hardware encryption driver first. 229If set to < 0, the kernel will select a software encryption driver first. 230If set to 0, the kernel will select either a hardware or software driver. 231.It Li ipsec.dfbit 232This variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation. 233If set to 0, the DF bit on the outer IPv4 header will be cleared. 2341 means that the outer DF bit is set from the inner DF bit. 2352 means that the DF bit is copied from the inner header to the outer. 236The variable is supplied to conform to RFC2401 chapter 6.1. 237.It Li ipsec.ecn 238If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will 239be friendly to ECN 240.Pq explicit congestion notification , 241as documented in 242.Li draft-ietf-ipsec-ecn-02.txt . 243.Xr gif 4 244talks more about the behavior. 245.It Li ipsec.debug 246If set to non-zero, debug messages will be generated via 247.Xr syslog 3 . 248.El 249.Pp 250Variables under the 251.Li net.inet6.ipsec6 252tree have similar meanings to their 253.Li net.inet.ipsec 254counterparts. 255.\" 256.Sh PROTOCOLS 257The 258.Nm 259protocol works like a plug-in to 260.Xr inet 4 261and 262.Xr inet6 4 263protocols. 264Therefore, 265.Nm 266supports most of the protocols defined upon those IP-layer protocols. 267Some of the protocols, like 268.Xr icmp 4 269or 270.Xr icmp6 4 , 271may behave differently with 272.Nm ipsec . 273This is because 274.Nm 275can prevent 276.Xr icmp 4 277or 278.Xr icmp6 4 279routines from looking into IP payload. 280.\" 281.Sh SEE ALSO 282.Xr ioctl 2 , 283.Xr socket 2 , 284.Xr ipsec_set_policy 3 , 285.Xr fast_ipsec 4 , 286.Xr icmp6 4 , 287.Xr intro 4 , 288.Xr ip6 4 , 289.Xr ipsecif 4 , 290.Xr racoon 8 , 291.Xr setkey 8 , 292.Xr sysctl 8 293.Sh STANDARDS 294.Rs 295.%A Daniel L. McDonald 296.%A Craig Metz 297.%A Bao G. Phan 298.%T "PF_KEY Key Management API, Version 2" 299.%R RFC 300.%N 2367 301.Re 302.Sh BUGS 303IPsec support is subject to change as the IPsec protocols develop. 304.Pp 305There is no single standard for policy engine API, 306so the policy engine API described herein is just for the version 307introduced by KAME. 308.Pp 309AH and tunnel mode encapsulation may not work as you might expect. 310If you configure inbound 311.Dq require 312policy against AH tunnel or any IPsec encapsulating policy with AH 313.Po 314like 315.Dq Li esp/tunnel/A-B/use ah/transport/A-B/require 316.Pc , 317tunneled packets will be rejected. 318This is because we enforce policy check on inner packet on reception, 319and AH authenticates encapsulating 320.Pq outer 321packet, not the encapsulated 322.Pq inner 323packet 324.Po 325so for the receiving kernel there's no sign of authenticity 326.Pc . 327The issue will be solved when we revamp our policy engine to keep all the 328packet decapsulation history. 329.Pp 330Under certain condition, 331truncated result may be raised from the kernel 332against 333.Dv SADB_DUMP 334and 335.Dv SADB_SPDDUMP 336operation on 337.Dv PF_KEY 338socket. 339This occurs if there are too many database entries in the kernel 340and socket buffer for the 341.Dv PF_KEY 342socket is insufficient. 343If you manipulate many IPsec key/policy database entries, 344increase the size of socket buffer or use 345.Xr sysctl 8 346interface. 347