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