share/man/man4/ipsec.4

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