1.\" $NetBSD: ipsec.4,v 1.30 2006/10/11 10:14:31 hubertf 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 February 12, 2005 32.Dt IPSEC 4 33.Os 34.Sh NAME 35.Nm ipsec 36.Nd IP security protocol 37.Sh SYNOPSIS 38.In sys/types.h 39.In netinet/in.h 40.In netinet6/ipsec.h 41.Pp 42.Cd options IPSEC 43.Cd options IPSEC_ESP 44.Cd options IPSEC_NAT_T 45.Cd options IPSEC_DEBUG 46.Sh DESCRIPTION 47.Nm 48is a security protocol in Internet Protocol layer. 49.Nm 50is defined for both IPv4 and IPv6 51.Po 52.Xr inet 4 53and 54.Xr inet6 4 55.Pc . 56.Nm 57consists of two sub-protocols, namely 58ESP 59.Pq encapsulated security payload 60and AH 61.Pq authentication header . 62ESP protects IP payload from wire-tapping by encrypting it by 63secret key cryptography algorithms. 64AH guarantees integrity of IP packet 65and protects it from intermediate alteration or impersonation, 66by attaching cryptographic checksum computed by one-way hash functions. 67.Nm 68has two operation modes: transport mode and tunnel mode. 69Transport mode is for protecting peer-to-peer communication between end nodes. 70Tunnel mode includes IP-in-IP encapsulation operation 71and is designed for security gateways, like VPN configurations. 72.Pp 73The following kernel options are available: 74.Bl -ohang 75.It Cd options IPSEC 76Includes support for the 77.Tn IPsec 78protocol. 79.Em IPSEC 80will enable 81secret key management part, 82policy management part, 83.Tn AH 84and 85.Tn IPComp . 86Kernel binary will not be subject to export control in most of countries, 87even if compiled with 88.Em IPSEC . 89For example, it should be okay to export it from within the United States 90to the outside. 91.Em INET6 92and 93.Em IPSEC 94are orthogonal so you can get IPv4-only kernel with IPsec support, 95IPv4/v6 dual support kernel without IPsec, and so forth. 96This option requires 97.Em INET 98at this moment, but it should not. 99.It Cd options IPSEC_DEBUG 100Enables debugging code in 101.Tn IPsec 102stack. 103This option assumes 104.Em IPSEC . 105.It Cd options IPSEC_ESP 106Includes support for 107.Tn IPsec 108.Tn ESP 109protocol. 110.Em IPSEC_ESP 111will enable source code that is subject to export control in some countries 112.Pq including the United States , 113and compiled kernel binary will be subject to certain restriction. 114This option assumes 115.Em IPSEC . 116.It Cd options IPSEC_NAT_T 117Includes support for 118.Tn IPsec 119Network Address Translator traversal (NAT-T), as described in RFCs 3947 120and 3948. 121This feature might be patent-encumbered in some countries. 122This option assumes 123.Em IPSEC 124and 125.Em IPSEC_ESP . 126.El 127.\" 128.Ss Kernel interface 129.Nm 130is controlled by key management engine and policy engine, 131in the operating system kernel. 132.Pp 133Key management engine can be accessed from the userland by using 134.Dv PF_KEY 135sockets. 136The 137.Dv PF_KEY 138socket API is defined in RFC2367. 139.Pp 140Policy engine can be controlled by extended part of 141.Dv PF_KEY 142API, 143.Xr setsockopt 2 144operations, and 145.Xr sysctl 3 146interface. 147The kernel implements 148extended version of 149.Dv PF_KEY 150interface, and allows you to define IPsec policy like per-packet filters. 151.Xr setsockopt 2 152interface is used to define per-socket behavior, and 153.Xr sysctl 3 154interface is used to define host-wide default behavior. 155.Pp 156The kernel code does not implement dynamic encryption key exchange protocol 157like IKE 158.Pq Internet Key Exchange . 159That should be implemented as userland programs 160.Pq usually as daemons , 161by using the above described APIs. 162.\" 163.Ss Policy management 164The kernel implements experimental policy management code. 165You can manage the IPsec policy in two ways. 166One is to configure per-socket policy using 167.Xr setsockopt 2 . 168The other is to configure kernel packet filter-based policy using 169.Dv PF_KEY 170interface, via 171.Xr setkey 8 . 172In both cases, IPsec policy must be specified with syntax described in 173.Xr ipsec_set_policy 3 . 174.Pp 175With 176.Xr setsockopt 2 , 177you can define IPsec policy in per-socket basis. 178You can enforce particular IPsec policy onto packets that go through 179particular socket. 180.Pp 181With 182.Xr setkey 8 183you can define IPsec policy against packets, 184using sort of packet filtering rule. 185Refer to 186.Xr setkey 8 187on how to use it. 188.Pp 189In the latter case, 190.Dq Li default 191policy is allowed for use with 192.Xr setkey 8 . 193By configuring policy to 194.Li default , 195you can refer system-wide 196.Xr sysctl 8 197variable for default settings. 198The following variables are available. 199.Li 1 200means 201.Dq Li use , 202and 203.Li 2 204means 205.Dq Li require 206in the syntax. 207.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx 208.It Sy Name Type Changeable 209.It net.inet.ipsec.esp_trans_deflev integer yes 210.It net.inet.ipsec.esp_net_deflev integer yes 211.It net.inet.ipsec.ah_trans_deflev integer yes 212.It net.inet.ipsec.ah_net_deflev integer yes 213.It net.inet6.ipsec6.esp_trans_deflev integer yes 214.It net.inet6.ipsec6.esp_net_deflev integer yes 215.It net.inet6.ipsec6.ah_trans_deflev integer yes 216.It net.inet6.ipsec6.ah_net_deflev integer yes 217.El 218.Pp 219If kernel finds no matching policy system wide default value is applied. 220System wide default is specified by the following 221.Xr sysctl 8 222variables. 223.Li 0 224means 225.Dq Li discard 226which asks the kernel to drop the packet. 227.Li 1 228means 229.Dq Li none . 230.Bl -column net.inet6.ipsec6.def_policy integerxxx 231.It Sy Name Type Changeable 232.It net.inet.ipsec.def_policy integer yes 233.It net.inet6.ipsec6.def_policy integer yes 234.El 235.\" 236.Ss Miscellaneous sysctl variables 237The following variables are accessible via 238.Xr sysctl 8 , 239for tweaking kernel IPsec behavior: 240.Bl -column net.inet6.ipsec6.inbound_call_ike integerxxx 241.It Sy Name Type Changeable 242.It net.inet.ipsec.ah_cleartos integer yes 243.It net.inet.ipsec.ah_offsetmask integer yes 244.It net.inet.ipsec.dfbit integer yes 245.It net.inet.ipsec.ecn integer yes 246.It net.inet.ipsec.debug integer yes 247.It net.inet6.ipsec6.ecn integer yes 248.It net.inet6.ipsec6.debug integer yes 249.El 250.Pp 251The variables are interpreted as follows: 252.Bl -tag -width "123456" 253.It Li ipsec.ah_cleartos 254If set to non-zero, the kernel clears type-of-service field in the IPv4 header 255during AH authentication data computation. 256The variable is for tweaking AH behavior to interoperate with devices that 257implement RFC1826 AH. 258It should be set to non-zero 259.Pq clear the type-of-service field 260for RFC2402 conformance. 261.It Li ipsec.ah_offsetmask 262During AH authentication data computation, the kernel will include 26316bit fragment offset field 264.Pq including flag bits 265in IPv4 header, after computing logical AND with the variable. 266The variable is for tweaking AH behavior to interoperate with devices that 267implement RFC1826 AH. 268It should be set to zero 269.Pq clear the fragment offset field during computation 270for RFC2402 conformance. 271.It Li ipsec.dfbit 272The variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation. 273If set to 0, DF bit on the outer IPv4 header will be cleared. 2741 means that the outer DF bit is set regardless from the inner DF bit. 2752 means that the DF bit is copied from the inner header to the outer. 276The variable is supplied to conform to RFC2401 chapter 6.1. 277.It Li ipsec.ecn 278If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will 279be friendly to ECN 280.Pq explicit congestion notification , 281as documented in 282.Li draft-ietf-ipsec-ecn-02.txt . 283.Xr gif 4 284talks more about the behavior. 285.It Li ipsec.debug 286If set to non-zero, debug messages will be generated via 287.Xr syslog 3 . 288.El 289.Pp 290Variables under 291.Li net.inet6.ipsec6 292tree has similar meaning as the 293.Li net.inet.ipsec 294counterpart. 295.\" 296.Sh PROTOCOLS 297The 298.Nm 299protocol works like plug-in to 300.Xr inet 4 301and 302.Xr inet6 4 303protocols. 304Therefore, 305.Nm 306supports most of the protocols defined upon those IP-layer protocols. 307Some of the protocols, like 308.Xr icmp 4 309or 310.Xr icmp6 4 , 311may behave differently with 312.Nm ipsec . 313This is because 314.Nm 315can prevent 316.Xr icmp 4 317or 318.Xr icmp6 4 319routines from looking into IP payload. 320.\" 321.Sh SEE ALSO 322.Xr ioctl 2 , 323.Xr socket 2 , 324.Xr ipsec_set_policy 3 , 325.Xr fast_ipsec 4 , 326.Xr icmp6 4 , 327.Xr intro 4 , 328.Xr ip6 4 , 329.Xr racoon 8 , 330.Xr setkey 8 , 331.Xr sysctl 8 332.Sh STANDARDS 333.Rs 334.%A Daniel L. McDonald 335.%A Craig Metz 336.%A Bao G. Phan 337.%T "PF_KEY Key Management API, Version 2" 338.%R RFC 339.%N 2367 340.Re 341.Sh HISTORY 342The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack. 343.Sh BUGS 344The IPsec support is subject to change as the IPsec protocols develop. 345.Pp 346There is no single standard for policy engine API, 347so the policy engine API described herein is just for KAME implementation. 348.Pp 349AH and tunnel mode encapsulation may not work as you might expect. 350If you configure inbound 351.Dq require 352policy against AH tunnel or any IPsec encapsulating policy with AH 353.Po 354like 355.Dq Li esp/tunnel/A-B/use ah/transport/A-B/require 356.Pc , 357tunneled packets will be rejected. 358This is because we enforce policy check on inner packet on reception, 359and AH authenticates encapsulating 360.Pq outer 361packet, not the encapsulated 362.Pq inner 363packet 364.Po 365so for the receiving kernel there's no sign of authenticity 366.Pc . 367The issue will be solved when we revamp our policy engine to keep all the 368packet decapsulation history. 369.Pp 370Under certain condition, 371truncated result may be raised from the kernel 372against 373.Dv SADB_DUMP 374and 375.Dv SADB_SPDDUMP 376operation on 377.Dv PF_KEY 378socket. 379This occurs if there are too many database entries in the kernel 380and socket buffer for the 381.Dv PF_KEY 382socket is insufficient. 383If you manipulate many IPsec key/policy database entries, 384increase the size of socket buffer or use 385.Xr sysctl 8 386interface. 387