lib/libipsec/ipsec_set_policy.3

   1 .\"     $KAME: ipsec_set_policy.3,v 1.15 2001/08/17 07:21:36 itojun Exp $
   2 .\"
   3 .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 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 February 14, 2006
  33 .Dt IPSEC_SET_POLICY 3
  34 .Os
  35 .Sh NAME
  36 .Nm ipsec_set_policy ,
  37 .Nm ipsec_get_policylen ,
  38 .Nm ipsec_dump_policy
  39 .Nd create an IPsec policy structure from a human readable string
  40 .\"
  41 .Sh LIBRARY
  42 .Lb libipsec
  43 .Sh SYNOPSIS
  44 .In netipsec/ipsec.h
  45 .Ft "char *"
  46 .Fn ipsec_set_policy "char *policy" "int len"
  47 .Ft int
  48 .Fn ipsec_get_policylen "char *buf"
  49 .Ft "char *"
  50 .Fn ipsec_dump_policy "char *buf" "char *delim"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn ipsec_set_policy
  54 function generates an IPsec policy specification structure,
  55 .Li struct sadb_x_policy
  56 and/or
  57 .Li struct sadb_x_ipsecrequest
  58 from a human-readable policy specification.
  59 The policy specification must be given as a C string,
  60 passed in the
  61 .Fa policy
  62 argument and the length of the string, given as
  63 .Fa len .
  64 The
  65 .Fn ipsec_set_policy
  66 function returns pointer to a buffer which contains a properly formed
  67 IPsec policy specification structure.
  68 The buffer is dynamically allocated, and must be freed by using the
  69 .Xr free 3
  70 library function.
  71 .Pp
  72 The
  73 .Fn ipsec_get_policylen
  74 function will returns the of the buffer which is needed when passing
  75 the specification structure to the
  76 .Xr setsockopt 2
  77 system call.
  78 .Pp
  79 The
  80 .Fn ipsec_dump_policy
  81 function converts an IPsec policy structure into a human readable form.
  82 The
  83 .Fa buf
  84 argument points to an IPsec policy structure,
  85 .Li struct sadb_x_policy .
  86 .Fa delim
  87 is a delimiter string, which is usually a blank character.
  88 If you set
  89 .Fa delim
  90 to
  91 .Dv NULL ,
  92 a single white space is assumed.
  93 The
  94 .Fn ipsec_dump_policy
  95 function returns a pointer to dynamically allocated string.
  96 It is the caller's responsibility to free the returned pointer using the
  97 .Xr free 3
  98 library call.
  99 .Pp
 100 A
 101 .Fa policy
 102 is given in the following way:
 103 .Bl -tag -width "discard"
 104 .It Ar direction Li discard
 105 The
 106 .Ar direction
 107 must be
 108 .Li in
 109 or
 110 .Li out
 111 and
 112 specifies which direction the policy needs to be applied, either on
 113 inbound or outbound packets.
 114 When the
 115 .Li discard
 116 policy is selected, packets will be dropped if they match the policy.
 117 .It Ar direction Li entrust
 118 .Li entrust
 119 means to consult the security policy database
 120 (SPD)
 121 in the kernel, as controlled by
 122 .Xr setkey 8 .
 123 .It Ar direction Li bypass
 124 A direction of
 125 .Li bypass
 126 indicates that IPsec processing should not occur and that the
 127 packet will be transmitted in clear.
 128 The bypass option is only
 129 available to privileged sockets.
 130 .It Xo
 131 .Ar direction
 132 .Li ipsec
 133 .Ar request ...
 134 .Xc
 135 A direction of
 136 .Li ipsec
 137 means that matching packets are processed by IPsec.
 138 .Li ipsec
 139 can be followed by one or more
 140 .Ar request
 141 string, which is formatted as:
 142 .Bl -tag -width "discard"
 143 .It Xo
 144 .Ar protocol
 145 .Li /
 146 .Ar mode
 147 .Li /
 148 .Ar src
 149 .Li -
 150 .Ar dst
 151 .Op Ar /level
 152 .Xc
 153 The
 154 .Ar protocol
 155 is one of:
 156 .Li ah ,
 157 .Li esp
 158 or
 159 .Li ipcomp
 160 indicating Authentication Header, Encapsulating Security Protocol or
 161 IP Compression protocol is used.
 162 .Pp
 163 The
 164 .Ar mode
 165 is either
 166 .Li transport
 167 or
 168 .Li tunnel
 169 the meanings of both modes are described in
 170 .Xr ipsec 4 .
 171 .Pp
 172 The
 173 .Ar src
 174 and
 175 .Ar dst
 176 specify the IP address, either v4 or v6, of the source and destination systems.
 177 The
 178 .Ar src
 179 always stands for the
 180 .Dq sending node
 181 and
 182 .Ar dst
 183 always stands for the
 184 .Dq receiving node .
 185 When
 186 .Ar direction
 187 is
 188 .Li in ,
 189 .Ar dst
 190 is this local node
 191 and
 192 .Ar src
 193 is the remote node or peer.
 194 If
 195 .Ar mode
 196 is
 197 .Li transport ,
 198 both
 199 .Ar src
 200 and
 201 .Ar dst
 202 can be omitted.
 203 .Pp
 204 The
 205 .Ar level
 206 must be set to one of the following:
 207 .Li default , use , require
 208 or
 209 .Li unique .
 210 .Li default
 211 means that the kernel should consult the default security policies as
 212 defined by a set of
 213 .Xr sysctl 8 ,
 214 variables.
 215 The relevant
 216 .Xr sysctl 8
 217 variables are described in
 218 .Xr ipsec 4 .
 219 .Pp
 220 When
 221 .Li use
 222 is selected a relevant security association
 223 (SA)
 224 can be used when available but is not necessary.
 225 If the SA is available then packets will be handled by IPsec,
 226 i.e., encrypted and/or authenticated but if an SA is not available then
 227 packets will be transmitted in the clear.
 228 The
 229 .Li use
 230 option is not recommended because it allows for accidental
 231 mis-configurations where encrypted or authenticated link becomes
 232 unencrypted or unauthenticated, the
 233 .Li require
 234 keyword is recommended instead of
 235 .Li use
 236 where possible.
 237 Using the
 238 .Li require
 239 keyword means that a relevant SA is required,
 240 and that the kernel must perform IPsec processing on all matching
 241 packets.
 242 .Pp
 243 The
 244 .Li unique
 245 keyword has the same effect as
 246 .Li require ,
 247 but adds the restriction that the SA for outbound traffic is used
 248 only for this policy.
 249 You may need the identifier in order to relate the policy and the SA
 250 when you define the SA by manual keying using
 251 .Xr setkey 8 .
 252 Put the decimal number as the identifier after the
 253 .Li unique
 254 keyword in this way:
 255 .Li unique : number ,
 256 where
 257 .Li number
 258 must be between 1 and 32767.
 259 .Pp
 260 If the
 261 .Ar request
 262 string is kept unambiguous,
 263 .Ar level
 264 and the slash prior to
 265 .Ar level
 266 can be omitted but you are encouraged to specify them explicitly
 267 to avoid unintended behaviors.
 268 If
 269 .Ar level
 270 is omitted, it will be interpreted as
 271 .Li default .
 272 .El
 273 .El
 274 .Pp
 275 Note that there is a difference between the specification allowed here
 276 and in
 277 .Xr setkey 8 .
 278 When specifying security policies with
 279 .Xr setkey 8 ,
 280 neither entrust nor bypass are used.
 281 Refer to
 282 .Xr setkey 8
 283 for details.
 284 .Sh RETURN VALUES
 285 The
 286 .Fn ipsec_set_policy
 287 function returns a pointer to the allocated buffer containing a the
 288 policy specification if successful; otherwise a NULL pointer is
 289 returned.
 290 .Pp
 291 The
 292 .Fn ipsec_get_policylen
 293 function returns a positive value,
 294 indicating the buffer size,
 295 on success, and a negative value on error.
 296 .Pp
 297 The
 298 .Fn ipsec_dump_policy
 299 function returns a pointer to a dynamically allocated region
 300 containing a human readable security policy on success, and
 301 .Dv NULL
 302 on error.
 303 .Sh EXAMPLES
 304 Set a policy that all inbound packets are discarded.
 305 .Pp
 306 .Dl "in discard"
 307 .Pp
 308 .\"
 309 All outbound packets are required to be processed by IPsec and
 310 transported using ESP.
 311 .Pp
 312 .Dl "out ipsec esp/transport//require"
 313 .Pp
 314 .\"
 315 All inbound packets are required to be authenticated using the AH protocol.
 316 .Pp
 317 .Dl "in ipsec ah/transport//require"
 318 .Pp
 319 .\"
 320 Tunnel packets outbound through the endpoints at 10.1.1.2 and 10.1.1.1.
 321 .Pp
 322 .Dl "out ipsec esp/tunnel/10.1.1.2-10.1.1.1/require"
 323 .Sh SEE ALSO
 324 .Xr ipsec_strerror 3 ,
 325 .Xr ipsec 4 ,
 326 .Xr setkey 8
 327 .Sh HISTORY
 328 These functions first appeared in WIDE/KAME IPv6 protocol stack kit.
 329 .Pp
 330 IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack
 331 was initially integrated into
 332 .Fx 4.0 .