1.\" $KAME: ipsec.4,v 1.17 2001/06/27 15:25:10 itojun Exp $ 2.\" 3.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. 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. Neither the name of the project nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd November 29, 2009 33.Dt IPSEC 4 34.Os 35.Sh NAME 36.Nm IPsec 37.Nd Internet Protocol Security protocol 38.Sh SYNOPSIS 39.Cd "options IPSEC" 40.Cd "device crypto" 41.Pp 42.In sys/types.h 43.In netinet/in.h 44.In netipsec/ipsec.h 45.In netipsec/ipsec6.h 46.Sh DESCRIPTION 47.Nm 48is a security protocol implemented within the Internet Protocol layer 49of the networking stack. 50.Nm 51is defined for both IPv4 and IPv6 52.Xr ( inet 4 53and 54.Xr inet6 4 ) . 55.Nm 56is a set of protocols, 57.Tn ESP 58(for Encapsulating Security Payload) 59.Tn AH 60(for Authentication Header), 61and 62.Tn IPComp 63(for IP Payload Compression Protocol) 64that provide security services for IP datagrams. 65AH both authenticates and guarantees the integrity of an IP packet 66by attaching a cryptographic checksum computed using one-way hash functions. 67ESP, in addition, prevents unauthorized parties from reading the payload of 68an IP packet by also encrypting it. 69IPComp tries to increase communication performance by compressing IP payload, 70thus reducing the amount of data sent. 71This will help nodes on slow links but with enough computing power. 72.Nm 73operates in one of two modes: transport mode or tunnel mode. 74Transport mode is used to protect peer-to-peer communication between end nodes. 75Tunnel mode encapsulates IP packets within other IP packets 76and is designed for security gateways such as VPN endpoints. 77.Pp 78System configuration requires the 79.Xr crypto 4 80subsystem. 81.Pp 82The packets can be passed to a virtual 83.Xr enc 4 84interface, 85to perform packet filtering before outbound encryption and after decapsulation 86inbound. 87.Pp 88To properly filter on the inner packets of an 89.Nm 90tunnel with firewalls, you can change the values of the following sysctls 91.Bl -column net.inet6.ipsec6.filtertunnel default enable 92.It Sy "Name Default Enable" 93.It "net.inet.ipsec.filtertunnel 0 1" 94.It "net.inet6.ipsec6.filtertunnel 0 1" 95.El 96.\" 97.Ss Kernel interface 98.Nm 99is controlled by a key management and policy engine, 100that reside in the operating system kernel. 101Key management 102is the process of associating keys with security associations, also 103know as SAs. 104Policy management dictates when new security 105associations created or destroyed. 106.Pp 107The key management engine can be accessed from userland by using 108.Dv PF_KEY 109sockets. 110The 111.Dv PF_KEY 112socket API is defined in RFC2367. 113.Pp 114The policy engine is controlled by an extension to the 115.Dv PF_KEY 116API, 117.Xr setsockopt 2 118operations, and 119.Xr sysctl 3 120interface. 121The kernel implements 122an extended version of the 123.Dv PF_KEY 124interface and allows the programmer to define IPsec policies 125which are similar to the per-packet filters. 126The 127.Xr setsockopt 2 128interface is used to define per-socket behavior, and 129.Xr sysctl 3 130interface is used to define host-wide default behavior. 131.Pp 132The kernel code does not implement a dynamic encryption key exchange protocol 133such as IKE 134(Internet Key Exchange). 135Key exchange protocols are beyond what is necessary in the kernel and 136should be implemented as daemon processes which call the 137.Nm APIs. 138.\" 139.Ss Policy management 140IPsec policies can be managed in one of two ways, either by 141configuring per-socket policies using the 142.Xr setsockopt 2 143system calls, or by configuring kernel level packet filter-based 144policies using the 145.Dv PF_KEY 146interface, via the 147.Xr setkey 8 148you can define IPsec policies against packets using rules similar to packet 149filtering rules. 150Refer to 151.Xr setkey 8 152on how to use it. 153.Pp 154When setting policies using the 155.Xr setkey 8 156command, the 157.Dq Li default 158option instructs the system to use its default policy, as 159explained below, for processing packets. 160The following sysctl variables are available for configuring the 161system's IPsec behavior. 162The variables can have one of two values. 163A 164.Li 1 165means 166.Dq Li use , 167which means that if there is a security association then use it but if 168there is not then the packets are not processed by IPsec. 169The value 170.Li 2 171is synonymous with 172.Dq Li require , 173which requires that a security association must exist for the packets 174to move, and not be dropped. 175These terms are defined in 176.Xr ipsec_set_policy 8 . 177.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx 178.It Sy "Name Type Changeable" 179.It "net.inet.ipsec.esp_trans_deflev integer yes" 180.It "net.inet.ipsec.esp_net_deflev integer yes" 181.It "net.inet.ipsec.ah_trans_deflev integer yes" 182.It "net.inet.ipsec.ah_net_deflev integer yes" 183.It "net.inet6.ipsec6.esp_trans_deflev integer yes" 184.It "net.inet6.ipsec6.esp_net_deflev integer yes" 185.It "net.inet6.ipsec6.ah_trans_deflev integer yes" 186.It "net.inet6.ipsec6.ah_net_deflev integer yes" 187.El 188.Pp 189If the kernel does not find a matching, system wide, policy then the 190default value is applied. 191The system wide default policy is specified 192by the following 193.Xr sysctl 8 194variables. 195.Li 0 196means 197.Dq Li discard 198which asks the kernel to drop the packet. 199.Li 1 200means 201.Dq Li none . 202.Bl -column net.inet6.ipsec6.def_policy integerxxx 203.It Sy "Name Type Changeable" 204.It "net.inet.ipsec.def_policy integer yes" 205.It "net.inet6.ipsec6.def_policy integer yes" 206.El 207.\" 208.Ss Miscellaneous sysctl variables 209When the 210.Nm 211protocols are configured for use, all protocols are included in the system. 212To selectively enable/disable protocols, use 213.Xr sysctl 8 . 214.Bl -column net.inet.ipcomp.ipcomp_enable 215.It Sy "Name Default" 216.It "net.inet.esp.esp_enable On" 217.It "net.inet.ah.ah_enable On" 218.It "net.inet.ipcomp.ipcomp_enable On" 219.El 220.Pp 221In addition the following variables are accessible via 222.Xr sysctl 8 , 223for tweaking the kernel's IPsec behavior: 224.Bl -column net.inet6.ipsec6.inbonud_call_ike integerxxx 225.It Sy "Name Type Changeable" 226.It "net.inet.ipsec.ah_cleartos integer yes" 227.It "net.inet.ipsec.ah_offsetmask integer yes" 228.It "net.inet.ipsec.dfbit integer yes" 229.It "net.inet.ipsec.ecn integer yes" 230.It "net.inet.ipsec.debug integer yes" 231.It "net.inet6.ipsec6.ecn integer yes" 232.It "net.inet6.ipsec6.debug integer yes" 233.El 234.Pp 235The variables are interpreted as follows: 236.Bl -tag -width 6n 237.It Li ipsec.ah_cleartos 238If set to non-zero, the kernel clears the type-of-service field in the IPv4 header 239during AH authentication data computation. 240This variable is used to get current systems to inter-operate with devices that 241implement RFC1826 AH. 242It should be set to non-zero 243(clear the type-of-service field) 244for RFC2402 conformance. 245.It Li ipsec.ah_offsetmask 246During AH authentication data computation, the kernel will include a 24716bit fragment offset field 248(including flag bits) 249in the IPv4 header, after computing logical AND with the variable. 250The variable is used for inter-operating with devices that 251implement RFC1826 AH. 252It should be set to zero 253(clear the fragment offset field during computation) 254for RFC2402 conformance. 255.It Li ipsec.dfbit 256This variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation. 257If set to 0, the DF bit on the outer IPv4 header will be cleared while 2581 means that the outer DF bit is set regardless from the inner DF bit and 2592 indicates that the DF bit is copied from the inner header to the 260outer one. 261The variable is supplied to conform to RFC2401 chapter 6.1. 262.It Li ipsec.ecn 263If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will 264be friendly to ECN 265(explicit congestion notification), 266as documented in 267.Li draft-ietf-ipsec-ecn-02.txt . 268.Xr gif 4 269talks more about the behavior. 270.It Li ipsec.debug 271If set to non-zero, debug messages will be generated via 272.Xr syslog 3 . 273.El 274.Pp 275Variables under the 276.Li net.inet6.ipsec6 277tree have similar meanings to those described above. 278.\" 279.Sh PROTOCOLS 280The 281.Nm 282protocol acts as a plug-in to the 283.Xr inet 4 284and 285.Xr inet6 4 286protocols and therefore supports most of the protocols defined upon 287those IP-layer protocols. 288The 289.Xr icmp 4 290and 291.Xr icmp6 4 292protocols may behave differently with 293.Nm 294because 295.Nm 296can prevent 297.Xr icmp 4 298or 299.Xr icmp6 4 300routines from looking into the IP payload. 301.\" 302.Sh SEE ALSO 303.Xr ioctl 2 , 304.Xr socket 2 , 305.Xr ipsec_set_policy 3 , 306.Xr crypto 4 , 307.Xr enc 4 , 308.Xr icmp6 4 , 309.Xr intro 4 , 310.Xr ip6 4 , 311.Xr setkey 8 , 312.Xr sysctl 8 313.\".Xr racoon 8 314.Rs 315.%A "S. Kent" 316.%A "R. Atkinson" 317.%T "IP Authentication Header" 318.%O "RFC 2404" 319.Re 320.Rs 321.%A "S. Kent" 322.%A "R. Atkinson" 323.%T "IP Encapsulating Security Payload (ESP)" 324.%O "RFC 2406" 325.Re 326.Sh STANDARDS 327.Rs 328.%A Daniel L. McDonald 329.%A Craig Metz 330.%A Bao G. Phan 331.%T "PF_KEY Key Management API, Version 2" 332.%R RFC 333.%N 2367 334.Re 335.Pp 336.Rs 337.%A "D. L. McDonald" 338.%T "A Simple IP Security API Extension to BSD Sockets" 339.%R internet draft 340.%N "draft-mcdonald-simple-ipsec-api-03.txt" 341.%O work in progress material 342.Re 343.Sh HISTORY 344The original 345.Nm 346implementation appeared in the WIDE/KAME IPv6/IPsec stack. 347.Pp 348For 349.Fx 5.0 350a fully locked IPsec implementation called fast_ipsec was brought in. 351The protocols drew heavily on the 352.Ox 353implementation of the 354.Tn IPsec 355protocols. 356The policy management code was derived from the 357.Tn KAME 358implementation found 359in their 360.Tn IPsec 361protocols. 362The fast_ipsec implementation lacked 363.Xr ip6 4 364support but made use of the 365.Xr crypto 4 366subsystem. 367.Pp 368For 369.Fx 7.0 370.Xr ip6 4 371support was added to fast_ipsec. 372After this the old KAME IPsec implementation was dropped and fast_ipsec 373became what now is the only 374.Nm 375implementation in 376.Fx . 377.Sh BUGS 378There is no single standard for the policy engine API, 379so the policy engine API described herein is just for this implementation. 380.Pp 381AH and tunnel mode encapsulation may not work as you might expect. 382If you configure inbound 383.Dq require 384policy with an AH tunnel or any IPsec encapsulating policy with AH 385(like 386.Dq Li esp/tunnel/A-B/use ah/transport/A-B/require ) , 387tunnelled packets will be rejected. 388This is because the policy check is enforced on the inner packet on reception, 389and AH authenticates encapsulating 390(outer) 391packet, not the encapsulated 392(inner) 393packet 394(so for the receiving kernel there is no sign of authenticity). 395The issue will be solved when we revamp our policy engine to keep all the 396packet decapsulation history. 397.Pp 398When a large database of security associations or policies is present 399in the kernel the 400.Dv SADB_DUMP 401and 402.Dv SADB_SPDDUMP 403operations on 404.Dv PF_KEY 405sockets may fail due to lack of space. 406Increasing the socket buffer 407size may alleviate this problem. 408.Pp 409The 410.Tn IPcomp 411protocol may occasionally error because of 412.Xr zlib 3 413problems. 414.Pp 415This documentation needs more review. 416