ipsec-tools/libipsec/ipsec_set_policy.3

   1 .\"     $KAME: ipsec_set_policy.3,v 1.16 2003/01/06 21:59:03 sumikawa 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 .Dd May 5, 1998
  31 .Dt IPSEC_SET_POLICY 3
  32 .Os
  33 .Sh NAME
  34 .Nm ipsec_dump_policy ,
  35 .Nm ipsec_get_policylen ,
  36 .Nm ipsec_set_policy
  37 .Nd manipulate IPsec policy specification structure from human-readable policy string
  38 .\"
  39 .Sh LIBRARY
  40 .Lb libipsec
  41 .Sh SYNOPSIS
  42 .In netinet6/ipsec.h
  43 .Ft "char *"
  44 .Fo ipsec_dump_policy
  45 .Fa "caddr_t buf"
  46 .Fa "char *delim"
  47 .Fc
  48 .Ft int
  49 .Fo ipsec_get_policylen
  50 .Fa "caddr_t buf"
  51 .Fc
  52 .Ft "char *"
  53 .Fo ipsec_set_policy
  54 .Fa "char *policy"
  55 .Fa "int len"
  56 .Fc
  57 .Sh DESCRIPTION
  58 .Fn ipsec_set_policy
  59 generates an IPsec policy specification structure, namely
  60 .Li struct sadb_x_policy
  61 and/or
  62 .Li struct sadb_x_ipsecrequest
  63 from a human-readable policy specification.
  64 The policy specification must be given as a C string
  65 .Fa policy
  66 and its length
  67 .Fa len .
  68 .Fn ipsec_set_policy
  69 will return a buffer with the corresponding IPsec policy specification structure.
  70 The buffer is dynamically allocated, and must be
  71 .Xr free 3 Ap d
  72 by the caller.
  73 .Pp
  74 You can get the length of the generated buffer with
  75 .Fn ipsec_get_policylen
  76 (i.e. for calling
  77 .Xr setsockopt 2 ) .
  78 .Pp
  79 .Fn ipsec_dump_policy
  80 converts an IPsec policy structure into human-readable form.
  81 Therefore,
  82 .Fn ipsec_dump_policy
  83 can be regarded as the inverse function to
  84 .Fn ipsec_set_policy .
  85 .Fa buf
  86 points to an IPsec policy structure,
  87 .Li struct sadb_x_policy .
  88 .Fa delim
  89 is a delimiter string, which is usually a blank character.
  90 If you set
  91 .Fa delim
  92 to
  93 .Dv NULL ,
  94 a single whitespace is assumed.
  95 .Fn ipsec_dump_policy
  96 returns a pointer to a dynamically allocated string.
  97 It is the caller's responsibility to
  98 .Xr free 3
  99 it.
 100 .Pp
 101 .Fa policy
 102 is formatted as either of the following:
 103 .Bl -tag  -width "discard"
 104 .It Ar direction [priority specification] Li discard
 105 .Ar direction
 106 must be
 107 .Li in ,
 108 .Li out ,
 109 or
 110 .Li fwd .
 111 .Ar direction
 112 specifies in which direction the policy needs to be applied.
 113 The non-standard direction
 114 .Li fwd
 115 is substituted with
 116 .Li in
 117 on platforms which do not support forward policies.
 118 .Pp
 119 .Ar priority specification
 120 is used to control the placement of the policy within the SPD.
 121 The policy position is determined by
 122 a signed integer where higher priorities indicate the policy is placed
 123 closer to the beginning of the list and lower priorities indicate the
 124 policy is placed closer to the end of the list.
 125 Policies with equal
 126 priorities are added at the end of the group of such policies.
 127 .Pp
 128 Priority can only
 129 be specified when libipsec has been compiled against kernel headers that
 130 support policy priorities (Linux \*[Gt]= 2.6.6).
 131 It takes one of the following formats:
 132 .Bl -tag  -width "discard"
 133 .It Xo
 134 .Ar {priority,prio} offset
 135 .Xc
 136 .Ar offset
 137 is an integer in the range -2147483647..214783648.
 138 .It Xo
 139 .Ar {priority,prio} base {+,-} offset
 140 .Xc
 141 .Ar base
 142 is either
 143 .Li low (-1073741824) ,
 144 .Li def (0) ,
 145 or
 146 .Li high (1073741824) .
 147 .Pp
 148 .Ar offset
 149 is an unsigned integer.
 150 It can be up to 1073741824 for
 151 positive offsets, and up to 1073741823 for negative offsets.
 152 .El
 153 .Pp
 154 The interpretation of policy priority in these functions and the
 155 kernel DOES differ.
 156 The relationship between the two can be described as
 157 p(kernel) = 0x80000000 - p(func)
 158 .Pp
 159 With
 160 .Li discard
 161 policy, packets will be dropped if they match the policy.
 162 .It Ar direction [priority specification] Li entrust
 163 .Li entrust
 164 means to consult the SPD defined by
 165 .Xr setkey 8 .
 166 .It Ar direction [priority specification] Li bypass
 167 .Li bypass
 168 means to bypass the IPsec processing.
 169 .Pq the packet will be transmitted in clear .
 170 This is for privileged sockets.
 171 .It Xo
 172 .Ar direction
 173 .Bq Ar priority specification
 174 .Li ipsec
 175 .Ar request ...
 176 .Xc
 177 .Li ipsec
 178 means that the matching packets are subject to IPsec processing.
 179 .Li ipsec
 180 can be followed by one or more
 181 .Ar request
 182 strings, which are formatted as below:
 183 .Bl -tag  -width "discard"
 184 .It Xo
 185 .Ar protocol
 186 .Li /
 187 .Ar mode
 188 .Li /
 189 .Ar src
 190 .Li -
 191 .Ar dst
 192 .Op Ar /level
 193 .Xc
 194 .Ar protocol
 195 is either
 196 .Li ah ,
 197 .Li esp ,
 198 or
 199 .Li ipcomp .
 200 .Pp
 201 .Ar mode
 202 is either
 203 .Li transport
 204 or
 205 .Li tunnel .
 206 .Pp
 207 .Ar src
 208 and
 209 .Ar dst
 210 specifies the IPsec endpoint.
 211 .Ar src
 212 always means the
 213 .Dq sending node
 214 and
 215 .Ar dst
 216 always means the
 217 .Dq receiving node .
 218 Therefore, when
 219 .Ar direction
 220 is
 221 .Li in ,
 222 .Ar dst
 223 is this node
 224 and
 225 .Ar src
 226 is the other node
 227 .Pq peer .
 228 If
 229 .Ar mode
 230 is
 231 .Li transport ,
 232 Both
 233 .Ar src
 234 and
 235 .Ar dst
 236 can be omitted.
 237 .Pp
 238 .Ar level
 239 must be set to one of the following:
 240 .Li default , use , require ,
 241 or
 242 .Li unique .
 243 .Li default
 244 means that the kernel should consult the system default policy
 245 defined by
 246 .Xr sysctl 8 ,
 247 such as
 248 .Li net.inet.ipsec.esp_trans_deflev .
 249 See
 250 .Xr ipsec 4
 251 regarding the system default.
 252 .Li use
 253 means that a relevant SA can be used when available,
 254 since the kernel may perform IPsec operation against packets when possible.
 255 In this case, packets can be transmitted in clear
 256 .Pq when SA is not available ,
 257 or encrypted
 258 .Pq when SA is available .
 259 .Li require
 260 means that a relevant SA is required,
 261 since the kernel must perform IPsec operation against packets.
 262 .Li unique
 263 is the same as
 264 .Li require ,
 265 but adds the restriction that the SA for outbound traffic is used
 266 only for this policy.
 267 You may need the identifier in order to relate the policy and the SA
 268 when you define the SA by manual keying.
 269 You can put the decimal number as the identifier after
 270 .Li unique
 271 like
 272 .Li unique : number .
 273 .Li number
 274 must be between 1 and 32767 .
 275 If the
 276 .Ar request
 277 string is kept unambiguous,
 278 .Ar level
 279 and slash prior to
 280 .Ar level
 281 can be omitted.
 282 However, it is encouraged to specify them explicitly
 283 to avoid unintended behavior.
 284 If
 285 .Ar level
 286 is omitted, it will be interpreted as
 287 .Li default .
 288 .El
 289 .Pp
 290 Note that there are slight differences to the specification of
 291 .Xr setkey 8 .
 292 In the specification of
 293 .Xr setkey 8 ,
 294 both
 295 .Li entrust
 296 and
 297 .Li bypass
 298 are not used.
 299 Refer to
 300 .Xr setkey 8
 301 for details.
 302 .Pp
 303 Here are several examples
 304 .Pq long lines are wrapped for readability :
 305 .Bd -literal -offset indent
 306 in discard
 307 out ipsec esp/transport//require
 308 in ipsec ah/transport//require
 309 out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use
 310 in ipsec ipcomp/transport//use
 311         esp/transport//use
 312 .Ed
 313 .El
 314 .Sh RETURN VALUES
 315 .Fn ipsec_set_policy
 316 returns a pointer to the allocated buffer with the policy specification
 317 if successful; otherwise a
 318 .Dv NULL
 319 pointer is returned.
 320 .Fn ipsec_get_policylen
 321 returns a positive value
 322 .Pq meaning the buffer size
 323 on success, and a negative value on errors.
 324 .Fn ipsec_dump_policy
 325 returns a pointer to a dynamically allocated region on success,
 326 and
 327 .Dv NULL
 328 on errors.
 329 .Sh SEE ALSO
 330 .Xr ipsec_strerror 3 ,
 331 .Xr ipsec 4 ,
 332 .Xr setkey 8
 333 .Sh HISTORY
 334 The functions first appeared in the WIDE/KAME IPv6 protocol stack kit.