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