share/man/man4/ipsec.4

   1 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the project nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     $Id: ipsec.4,v 1.2 1999/10/07 03:55:08 itojun Exp $
  29 .\"     $FreeBSD$
  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
  43 is a security protocol in Internet Protocol layer.
  44 .Nm
  45 is defined for both IPv4 and IPv6
  46 .Po
  47 .Xr inet 4
  48 and
  49 .Xr inet6 4
  50 .Pc .
  51 .Nm
  52 consists of two sub-protocols, namely
  53 ESP
  54 .Pq encapsulated security payload
  55 and AH
  56 .Pq authentication header .
  57 ESP protects IP payload from wire-tapping by encrypting it by
  58 secret key cryptography algorithms.
  59 AH guarantees integrity of IP packet
  60 and protects it from intermediate alteration or impersonation,
  61 by attaching cryptographic checksum computed by one-way hash functions.
  62 .Nm
  63 has two operation modes: transport mode and tunnel mode.
  64 Transport mode is for protecting peer-to-peer commuication between end nodes.
  65 Tunnel mode includes IP-in-IP encapsulation operation
  66 and is designed for security gateways, like VPN configurations.
  67 .\"
  68 .Sh KERNEL INTERFACE
  69 .Nm
  70 is controlled by key management engine, and policy engine in the
  71 operating system kernel.
  72 .Pp
  73 Key management engine can be accessed from the userland by using
  74 .Dv PF_KEY
  75 sockets.
  76 The
  77 .Dv PF_KEY
  78 socket API is defined in RFC2367.
  79 .Pp
  80 Policy engine can be controlled by extended part of
  81 .Dv PF_KEY
  82 API,
  83 .Xr setsockopt 2
  84 operations, and
  85 .Xr sysctl 3
  86 interface.
  87 The kernel implements
  88 extended version of
  89 .Dv PF_KEY
  90 interface, and allows you to define IPsec policy like per-packet filters.
  91 .Xr setsockopt 2
  92 interface is used to define per-socket behavior, and
  93 .Xr sysctl 3
  94 interface is used to define host-wide default behavior.
  95 .Pp
  96 The kernel code does not implement dynamic encryption key exchange protocol
  97 like IKE
  98 .Pq Internet Key Exchange .
  99 That should be implemented as userland programs
 100 .Pq usually as daemons ,
 101 by using the above described APIs.
 102 .\"
 103 .Sh POLICY MANAGEMENT
 104 The kernel implements experimental policy management code.
 105 You can manage the IPsec policy in two ways.
 106 One is to configure per-socket policy using
 107 .Xr setsockopt 3 .
 108 The other is to configure kernel packet filter-based policy using
 109 .Dv PF_KEY
 110 interface, via
 111 .Xr setkey 8 .
 112 In both cases, IPsec policy must be specified with syntax described in
 113 .Xr ipsec_set_policy 3 .
 114 .Pp
 115 With
 116 .Xr setsockopt 3 ,
 117 you can define IPsec policy in per-socket basis.
 118 You can enforce particular IPsec policy onto packets that go through
 119 particular socket.
 120 .Pp
 121 With
 122 .Xr setkey 8
 123 you can define IPsec policy against packets,
 124 using sort of packet filtering rule.
 125 Refer to
 126 .Xr setkey 8
 127 on how to use it.
 128 .Pp
 129 In the latter case,
 130 .Dq Li default
 131 policy is allowed for use with
 132 .Xr setkey 8 .
 133 By configuring policy to
 134 .Li default ,
 135 you can refer system-wide
 136 .Xr sysctl 8
 137 variable for default settings.
 138 The following variables are available.
 139 .Li 1
 140 means
 141 .Dq Li use ,
 142 and
 143 .Li 2
 144 means
 145 .Dq Li require
 146 in 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
 159 If kernel finds no matching policy system wide default value is applied.
 160 System wide default is specified by the following
 161 .Xr sysctl 8
 162 variables.
 163 .Li 0
 164 means
 165 .Dq Li discard
 166 which asks the kernel to drop the packet.
 167 .Li 1
 168 means
 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 .Sh PROTOCOLS
 177 The
 178 .Nm
 179 protocol works like plug-in to
 180 .Xr inet 4
 181 and
 182 .Xr inet6 4
 183 protocols.
 184 Therefore,
 185 .Nm
 186 supports most of the protocols defined upon those IP-layer protocols.
 187 Some of the protocols, like
 188 .Xr icmp 4
 189 or
 190 .Xr icmp6 4 ,
 191 may behave differently with
 192 .Nm ipsec .
 193 This is because
 194 .Nm
 195 can prevent
 196 .Xr icmp 4
 197 or
 198 .Xr icmp6 4
 199 routines from looking into IP payload.
 200 .\"
 201 .Sh SEE ALSO
 202 .Xr ioctl 2 ,
 203 .Xr socket 2 ,
 204 .Xr ipsec_set_policy 3 ,
 205 .Xr icmp6 4 ,
 206 .Xr intro 4 ,
 207 .Xr ip6 4 ,
 208 .Xr setkey 8 ,
 209 .Xr sysctl 8 ,
 210 .Xr racoon 8 .
 211 .Pp
 212 .Rs
 213 .%T RFC2367
 214 .Re
 215 .Rs
 216 .%A "D. L. McDonald"
 217 .%T "A Simple IP Security API Extension to BSD Sockets"
 218 .%N "draft-mcdonald-simple-ipsec-api-03.txt"
 219 .%O "internet draft"
 220 .Re
 221 .Sh CAVEAT
 222 The IPsec support is subject to change as the IPsec protocols develop.
 223 .Pp
 224 There is no single standard for policy engine API,
 225 so the policy engine API described herein is just for KAME implementation.
 226 .\"
 227 .Sh HISTORY
 228 The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack.