1.\" $FreeBSD$ 2.\" $KAME: ipsec.4,v 1.13 2000/06/15 04:08:54 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 29, 1999 32.Dt IPSEC 4 33.Os 34.Sh NAME 35.Nm ipsec 36.Nd IP security protocol 37.Sh SYNOPSIS 38.Fd #include <sys/types.h> 39.Fd #include <netinet/in.h> 40.Fd #include <netinet6/ipsec.h> 41.Sh DESCRIPTION 42.Nm 43is a security protocol in Internet Protocol 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, namely 53ESP 54.Pq encapsulated security payload 55and AH 56.Pq authentication header . 57ESP protects IP payload from wire-tapping by encrypting it by 58secret key cryptography algorithms. 59AH guarantees integrity of IP packet 60and protects it from intermediate alteration or impersonation, 61by attaching cryptographic checksum computed by one-way hash functions. 62.Nm 63has two operation modes: transport mode and tunnel mode. 64Transport mode is for protecting peer-to-peer commuication between end nodes. 65Tunnel mode includes IP-in-IP encapsulation operation 66and is designed for security gateways, like VPN configurations. 67.\" 68.Ss Kernel interface 69.Nm 70is controlled by key management engine and policy engine, 71in the operating system kernel. 72.Pp 73Key management engine can be accessed from the userland by using 74.Dv PF_KEY 75sockets. 76The 77.Dv PF_KEY 78socket API is defined in RFC2367. 79.Pp 80Policy engine can be controlled by extended part of 81.Dv PF_KEY 82API, 83.Xr setsockopt 2 84operations, and 85.Xr sysctl 3 86interface. 87The kernel implements 88extended version of 89.Dv PF_KEY 90interface, and allows you to define IPsec policy like per-packet filters. 91.Xr setsockopt 2 92interface is used to define per-socket behavior, and 93.Xr sysctl 3 94interface is used to define host-wide default behavior. 95.Pp 96The kernel code does not implement dynamic encryption key exchange protocol 97like IKE 98.Pq Internet Key Exchange . 99That should be implemented as userland programs 100.Pq usually as daemons , 101by using the above described APIs. 102.\" 103.Ss Policy management 104The kernel implements experimental policy management code. 105You can manage the IPsec policy in two ways. 106One is to configure per-socket policy using 107.Xr setsockopt 3 . 108The other is to configure kernel packet filter-based policy using 109.Dv PF_KEY 110interface, via 111.Xr setkey 8 . 112In both cases, IPsec policy must be specified with syntax described in 113.Xr ipsec_set_policy 3 . 114.Pp 115With 116.Xr setsockopt 3 , 117you can define IPsec policy in per-socket basis. 118You can enforce particular IPsec policy onto packets that go through 119particular socket. 120.Pp 121With 122.Xr setkey 8 123you can define IPsec policy against packets, 124using sort of packet filtering rule. 125Refer to 126.Xr setkey 8 127on how to use it. 128.Pp 129In the latter case, 130.Dq Li default 131policy is allowed for use with 132.Xr setkey 8 . 133By configuring policy to 134.Li default , 135you can refer system-wide 136.Xr sysctl 8 137variable for default settings. 138The following variables are available. 139.Li 1 140means 141.Dq Li use , 142and 143.Li 2 144means 145.Dq Li require 146in the syntax. 147.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx 148.It Sy Name Type Changeable 149.It net.inet.ipsec.esp_trans_deflev integer yes 150.It net.inet.ipsec.esp_net_deflev integer yes 151.It net.inet.ipsec.ah_trans_deflev integer yes 152.It net.inet.ipsec.ah_net_deflev integer yes 153.It net.inet6.ipsec6.esp_trans_deflev integer yes 154.It net.inet6.ipsec6.esp_net_deflev integer yes 155.It net.inet6.ipsec6.ah_trans_deflev integer yes 156.It net.inet6.ipsec6.ah_net_deflev integer yes 157.El 158.Pp 159If kernel finds no matching policy system wide default value is applied. 160System wide default is specified by the following 161.Xr sysctl 8 162variables. 163.Li 0 164means 165.Dq Li discard 166which asks the kernel to drop the packet. 167.Li 1 168means 169.Dq Li none . 170.Bl -column net.inet6.ipsec6.def_policy integerxxx 171.It Sy Name Type Changeable 172.It net.inet.ipsec.def_policy integer yes 173.It net.inet6.ipsec6.def_policy integer yes 174.El 175.\" 176.Ss Miscellaneous sysctl variables 177The following variables are accessible via 178.Xr sysctl 8 , 179for tweaking kernel IPsec behavior: 180.Bl -column net.inet6.ipsec6.inbonud_call_ike integerxxx 181.It Sy Name Type Changeable 182.It net.inet.ipsec.ah_cleartos integer yes 183.It net.inet.ipsec.ah_offsetmask integer yes 184.It net.inet.ipsec.dfbit integer yes 185.It net.inet.ipsec.ecn integer yes 186.It net.inet.ipsec.debug integer yes 187.It net.inet6.ipsec6.ecn integer yes 188.It net.inet6.ipsec6.debug integer yes 189.El 190.Pp 191The variables are interpreted as follows: 192.Bl -tag -width "123456" 193.It Li ipsec.ah_cleartos 194If set to non-zero, the kernel clears type-of-service field in the IPv4 header 195during AH authentication data computation. 196The variable is for tweaking AH behavior to interoperate with devices that 197implement RFC1826 AH. 198It should be set to non-zero 199.Pq clear the type-of-service field 200for RFC2402 conformance. 201.It Li ipsec.ah_offsetmask 202During AH authentication data computation, the kernel will include 20316bit fragment offset field 204.Pq including flag bits 205in IPv4 header, after computing logical AND with the variable. 206The variable is for tweaking AH behavior to interoperate with devices that 207implement RFC1826 AH. 208It should be set to zero 209.Pq clear the fragment offset field during computation 210for RFC2402 conformance. 211.It Li ipsec.dfbit 212The variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation. 213If set to 0, DF bit on the outer IPv4 header will be cleared. 2141 means that the outer DF bit is set regardless from the inner DF bit. 2152 means that the DF bit is copied from the inner header to the outer. 216The variable is supplied to conform to RFC2403 chapter 6.1. 217.It Li ipsec.ecn 218If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will 219be friendly to ECN 220.Pq explicit congestion notification , 221as documented in 222.Li draft-ietf-ipsec-ecn-02.txt . 223.Xr gif 4 224talks more about the behavior. 225.It Li ipsec.debug 226If set to non-zero, debug messages will be generated via 227.Xr syslog 3 . 228.El 229.Pp 230Variables under 231.Li net.inet6.ipsec6 232tree has similar meaning as the 233.Li net.inet.ipsec 234counterpart. 235.\" 236.Sh PROTOCOLS 237The 238.Nm 239protocol works like plug-in to 240.Xr inet 4 241and 242.Xr inet6 4 243protocols. 244Therefore, 245.Nm 246supports most of the protocols defined upon those IP-layer protocols. 247Some of the protocols, like 248.Xr icmp 4 249or 250.Xr icmp6 4 , 251may behave differently with 252.Nm ipsec . 253This is because 254.Nm 255can prevent 256.Xr icmp 4 257or 258.Xr icmp6 4 259routines from looking into IP payload. 260.\" 261.Sh SEE ALSO 262.Xr ioctl 2 , 263.Xr socket 2 , 264.Xr ipsec_set_policy 3 , 265.Xr icmp6 4 , 266.Xr intro 4 , 267.Xr ip6 4 , 268.Xr setkey 8 , 269.Xr sysctl 8 270.\".Xr racoon 8 271.Pp 272.Sh STANDARDS 273.Rs 274.%A Daniel L. McDonald 275.%A Craig Metz 276.%A Bao G. Phan 277.%T "PF_KEY Key Management API, Version 2" 278.%R RFC 279.%N 2367 280.Re 281.Pp 282.Rs 283.%A "D. L. McDonald" 284.%T "A Simple IP Security API Extension to BSD Sockets" 285.%R internet draft 286.%N "draft-mcdonald-simple-ipsec-api-03.txt" 287.%O work in progress material 288.Re 289.Sh HISTORY 290The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack. 291.Sh BUGS 292The IPsec support is subject to change as the IPsec protocols develop. 293.Pp 294There is no single standard for policy engine API, 295so the policy engine API described herein is just for KAME implementation. 296.Pp 297AH tunnel may not work as you might expect. 298If you configure 299.Dq require 300policy against AH tunnel for inbound, tunnelled packets will be rejected. 301This is because AH authenticates encapsulating 302.Pq outer 303packet, not the encapsulated 304.Pq inner 305packet. 306.Pp 307Under certain condition, 308truncated result may be raised from the kernel 309against 310.Dv SADB_DUMP 311and 312.Dv SADB_SPDDUMP 313operation on 314.Dv PF_KEY 315socket. 316This occurs if there are too many database entries in the kernel 317and socket buffer for the 318.Dv PF_KEY 319socket is insufficient. 320If you manipulate many IPsec key/policy database entries, 321increase the size of socket buffer. 322