share/man/man4/ipsec.4

   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 August 24, 2006
  33 .Dt IPSEC 4
  34 .Os
  35 .Sh NAME
  36 .Nm ipsec
  37 .Nd IP security protocol
  38 .Sh SYNOPSIS
  39 .Cd "options IPSEC"
  40 .Cd "options IPSEC_DEBUG"
  41 .Cd "options IPSEC_ESP"
  42 .Cd "options IPSEC_FILTERGIF"
  43 .Pp
  44 .In sys/types.h
  45 .In netinet/in.h
  46 .In netinet6/ipsec.h
  47 .Sh DESCRIPTION
  48 .Nm
  49 is a security protocol implemented within the Internet Protocol layer
  50 of the TCP/IP stack.
  51 .Nm
  52 is defined for both IPv4 and IPv6
  53 .Xr ( inet 4
  54 and
  55 .Xr inet6 4 ) .
  56 .Nm
  57 contains two protocols,
  58 ESP, the encapsulated security payload protocol and
  59 AH, the authentication header protocol.
  60 ESP prevents unauthorized parties from reading the payload of an IP packet
  61 by encrypting it using
  62 secret key cryptography algorithms.
  63 AH both authenticates guarantees the integrity of an IP packet
  64 by attaching a cryptographic checksum computed using one-way hash functions.
  65 .Nm
  66 has operates in one of two modes: transport mode or tunnel mode.
  67 Transport mode is used to protect peer-to-peer communication between end nodes.
  68 Tunnel mode encapsulates IP packets within other IP packets
  69 and is designed for security gateways such as VPN endpoints.
  70 .\"
  71 .Ss Kernel interface
  72 .Nm
  73 is controlled by a key management and policy engine,
  74 that reside in the operating system kernel.
  75 Key management
  76 is the process of associating keys with security associations, also
  77 know as SAs.
  78 Policy management dictates when new security
  79 associations created or destroyed.
  80 .Pp
  81 The key management engine can be accessed from userland by using
  82 .Dv PF_KEY
  83 sockets.
  84 The
  85 .Dv PF_KEY
  86 socket API is defined in RFC2367.
  87 .Pp
  88 The policy engine is controlled by an extension to the
  89 .Dv PF_KEY
  90 API,
  91 .Xr setsockopt 2
  92 operations, and
  93 .Xr sysctl 3
  94 interface.
  95 The kernel implements
  96 an extended version of the
  97 .Dv PF_KEY
  98 interface, and allows the programmer to define IPsec policies
  99 which are similar to the per-packet filters.
 100 The
 101 .Xr setsockopt 2
 102 interface is used to define per-socket behavior, and
 103 .Xr sysctl 3
 104 interface is used to define host-wide default behavior.
 105 .Pp
 106 The kernel code does not implement a dynamic encryption key exchange protocol
 107 such as IKE
 108 (Internet Key Exchange).
 109 Key exchange protocols are beyond what is necessary in the kernel and
 110 should be implemented as daemon processes which call the
 111 .Nm APIs.
 112 .\"
 113 .Ss Policy management
 114 IPsec policies can be managed in one of two ways, either by
 115 configuring per-socket policies using the
 116 .Xr setsockopt 2
 117 system calls, or by configuring kernel level packet filter-based
 118 policies using the
 119 .Dv PF_KEY
 120 interface, via the
 121 .Xr setkey 8
 122 command.
 123 In either case, IPsec policies must be specified using the syntax described in
 124 .Xr ipsec_set_policy 3 .
 125 Please refer to the
 126 .Xr setkey 8
 127 man page for instructions on its use.
 128 .Pp
 129 When setting policies using the
 130 .Xr setkey 8
 131 command the
 132 .Dq Li default
 133 option you can have the system use its default policy, explained
 134 below, for processing packets.
 135 The following sysctl variables are available for configuring the
 136 system's IPsec behavior.
 137 The variables can have one of two values.
 138 A
 139 .Li 1
 140 means
 141 .Dq Li use ,
 142 which means that if there is a security association then use it but if
 143 there is not then the packets are not processed by IPsec.
 144 The value
 145 .Li 2
 146 is synonymous with
 147 .Dq Li require ,
 148 which requires that a security association must exist for the packets
 149 to move, and not be dropped.
 150 These terms are defined in
 151 .Xr ipsec_set_policy 8 .
 152 .Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx
 153 .It Sy "Name    Type    Changeable"
 154 .It "net.inet.ipsec.esp_trans_deflev    integer yes"
 155 .It "net.inet.ipsec.esp_net_deflev      integer yes"
 156 .It "net.inet.ipsec.ah_trans_deflev     integer yes"
 157 .It "net.inet.ipsec.ah_net_deflev       integer yes"
 158 .It "net.inet6.ipsec6.esp_trans_deflev  integer yes"
 159 .It "net.inet6.ipsec6.esp_net_deflev    integer yes"
 160 .It "net.inet6.ipsec6.ah_trans_deflev   integer yes"
 161 .It "net.inet6.ipsec6.ah_net_deflev     integer yes"
 162 .El
 163 .Pp
 164 If the kernel does not find a matching, system wide, policy then the
 165 default value is applied.
 166 The system wide default policy is specified
 167 by the following
 168 .Xr sysctl 8
 169 variables.
 170 .Li 0
 171 means
 172 .Dq Li discard
 173 which asks the kernel to drop the packet.
 174 .Li 1
 175 means
 176 .Dq Li none .
 177 .Bl -column net.inet6.ipsec6.def_policy integerxxx
 178 .It Sy "Name    Type    Changeable"
 179 .It "net.inet.ipsec.def_policy  integer yes"
 180 .It "net.inet6.ipsec6.def_policy        integer yes"
 181 .El
 182 .\"
 183 .Ss Miscellaneous sysctl variables
 184 The following variables are accessible via
 185 .Xr sysctl 8 ,
 186 for tweaking the kernel's IPsec behavior:
 187 .Bl -column net.inet6.ipsec6.inbonud_call_ike integerxxx
 188 .It Sy "Name    Type    Changeable"
 189 .It "net.inet.ipsec.ah_cleartos integer yes"
 190 .It "net.inet.ipsec.ah_offsetmask       integer yes"
 191 .It "net.inet.ipsec.dfbit       integer yes"
 192 .It "net.inet.ipsec.ecn integer yes"
 193 .It "net.inet.ipsec.debug       integer yes"
 194 .It "net.inet6.ipsec6.ecn       integer yes"
 195 .It "net.inet6.ipsec6.debug     integer yes"
 196 .El
 197 .Pp
 198 The variables are interpreted as follows:
 199 .Bl -tag -width 6n
 200 .It Li ipsec.ah_cleartos
 201 If set to non-zero, the kernel clears the type-of-service field in the IPv4 header
 202 during AH authentication data computation.
 203 This variable is used to get current systems to inter-operate with devices that
 204 implement RFC1826 AH.
 205 It should be set to non-zero
 206 (clear the type-of-service field)
 207 for RFC2402 conformance.
 208 .It Li ipsec.ah_offsetmask
 209 During AH authentication data computation, the kernel will include a
 210 16bit fragment offset field
 211 (including flag bits)
 212 in the IPv4 header, after computing logical AND with the variable.
 213 The variable is used for inter-operating with devices that
 214 implement RFC1826 AH.
 215 It should be set to zero
 216 (clear the fragment offset field during computation)
 217 for RFC2402 conformance.
 218 .It Li ipsec.dfbit
 219 This variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation.
 220 If set to 0, the DF bit on the outer IPv4 header will be cleared while
 221 1 means that the outer DF bit is set regardless from the inner DF bit and
 222 2 indicates that the DF bit is copied from the inner header to the
 223 outer one.
 224 The variable is supplied to conform to RFC2401 chapter 6.1.
 225 .It Li ipsec.ecn
 226 If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will
 227 be friendly to ECN
 228 (explicit congestion notification),
 229 as documented in
 230 .Li draft-ietf-ipsec-ecn-02.txt .
 231 .Xr gif 4
 232 talks more about the behavior.
 233 .It Li ipsec.debug
 234 If set to non-zero, debug messages will be generated via
 235 .Xr syslog 3 .
 236 .El
 237 .Pp
 238 Variables under the
 239 .Li net.inet6.ipsec6
 240 tree have similar meanings to those described above.
 241 .\"
 242 .Sh PROTOCOLS
 243 The
 244 .Nm
 245 protocol acts as a plug-in to the
 246 .Xr inet 4
 247 and
 248 .Xr inet6 4
 249 protocols and therefore supports most of the protocols defined upon
 250 those IP-layer protocols.
 251 The
 252 .Xr icmp 4
 253 and
 254 .Xr icmp6 4
 255 protocols may behave differently with
 256 .Nm
 257 because
 258 .Nm
 259 can prevent
 260 .Xr icmp 4
 261 or
 262 .Xr icmp6 4
 263 routines from looking into the IP payload.
 264 .\"
 265 .Sh SEE ALSO
 266 .Xr ioctl 2 ,
 267 .Xr socket 2 ,
 268 .Xr ipsec_set_policy 3 ,
 269 .Xr fast_ipsec 4 ,
 270 .Xr icmp6 4 ,
 271 .Xr intro 4 ,
 272 .Xr ip6 4 ,
 273 .Xr setkey 8 ,
 274 .Xr sysctl 8
 275 .\".Xr racoon 8
 276 .Rs
 277 .%A "S. Kent"
 278 .%A "R. Atkinson"
 279 .%T "IP Authentication Header"
 280 .%O "RFC 2404"
 281 .Re
 282 .Rs
 283 .%A "S. Kent"
 284 .%A "R. Atkinson"
 285 .%T "IP Encapsulating Security Payload (ESP)"
 286 .%O "RFC 2406"
 287 .Re
 288 .Sh STANDARDS
 289 .Rs
 290 .%A Daniel L. McDonald
 291 .%A Craig Metz
 292 .%A Bao G. Phan
 293 .%T "PF_KEY Key Management API, Version 2"
 294 .%R RFC
 295 .%N 2367
 296 .Re
 297 .Pp
 298 .Rs
 299 .%A "D. L. McDonald"
 300 .%T "A Simple IP Security API Extension to BSD Sockets"
 301 .%R internet draft
 302 .%N "draft-mcdonald-simple-ipsec-api-03.txt"
 303 .%O work in progress material
 304 .Re
 305 .Sh HISTORY
 306 The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack.
 307 .Sh BUGS
 308 The IPsec support is subject to change as the IPsec protocols develop.
 309 .Pp
 310 There is no single standard for the policy engine API,
 311 so the policy engine API described herein is just for KAME implementation.
 312 .Pp
 313 AH and tunnel mode encapsulation may not work as you might expect.
 314 If you configure inbound
 315 .Dq require
 316 policy with an AH tunnel or any IPsec encapsulating policy with AH
 317 (like
 318 .Dq Li esp/tunnel/A-B/use ah/transport/A-B/require ) ,
 319 tunnelled packets will be rejected.
 320 This is because the policy check is enforced on the inner packet on reception,
 321 and AH authenticates encapsulating
 322 (outer)
 323 packet, not the encapsulated
 324 (inner)
 325 packet
 326 (so for the receiving kernel there is no sign of authenticity).
 327 The issue will be solved when we revamp our policy engine to keep all the
 328 packet decapsulation history.
 329 .Pp
 330 When a large database of security associations or policies is present
 331 in the kernel the
 332 .Dv SADB_DUMP
 333 and
 334 .Dv SADB_SPDDUMP
 335 operations on
 336 .Dv PF_KEY
 337 sockets may fail due to lack of space.
 338 Increasing the socket buffer
 339 size may alleviate this problem.