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