crypto/dist/ipsec-tools/src/libipsec/ipsec_set_policy.3

   1 .\"     $NetBSD: ipsec_set_policy.3,v 1.13 2006/09/09 16:22:09 manu Exp $
   2 .\"
   3 .\"     $KAME: ipsec_set_policy.3,v 1.16 2003/01/06 21:59:03 sumikawa Exp $
   4 .\"
   5 .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the project nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd May 5, 1998
  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 manipulate IPsec policy specification structure from human-readable policy string
  40 .\"
  41 .Sh LIBRARY
  42 .Lb libipsec
  43 .Sh SYNOPSIS
  44 .In netinet6/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 .Fn ipsec_set_policy
  53 generates an IPsec policy specification structure, namely
  54 .Li struct sadb_x_policy
  55 and/or
  56 .Li struct sadb_x_ipsecrequest
  57 from a human-readable policy specification.
  58 The policy specification must be given as a C string
  59 .Fa policy
  60 and its length
  61 .Fa len .
  62 .Fn ipsec_set_policy
  63 will return a buffer with the corresponding IPsec policy specification structure.
  64 The buffer is dynamically allocated, and must be
  65 .Xr free 3 Ap d
  66 by the caller.
  67 .Pp
  68 You can get the length of the generated buffer with
  69 .Fn ipsec_get_policylen
  70 (i.e. for calling
  71 .Xr setsockopt 2 ) .
  72 .Pp
  73 .Fn ipsec_dump_policy
  74 converts an IPsec policy structure into human-readable form.
  75 Therefore,
  76 .Fn ipsec_dump_policy
  77 can be regarded as the inverse function to
  78 .Fn ipsec_set_policy .
  79 .Fa buf
  80 points to an IPsec policy structure,
  81 .Li struct sadb_x_policy .
  82 .Fa delim
  83 is a delimiter string, which is usually a blank character.
  84 If you set
  85 .Fa delim
  86 to
  87 .Dv NULL ,
  88 a single whitespace is assumed.
  89 .Fn ipsec_dump_policy
  90 returns a pointer to a dynamically allocated string.
  91 It is the caller's responsibility to
  92 .Xr free 3
  93 it.
  94 .Pp
  95 .Fa policy
  96 is formatted as either of the following:
  97 .Bl -tag  -width "discard"
  98 .It Ar direction [priority specification] Li discard
  99 .Ar direction
 100 must be
 101 .Li in ,
 102 .Li out ,
 103 or
 104 .Li fwd .
 105 .Ar direction
 106 specifies in which direction the policy needs to be applied.
 107 The non-standard direction
 108 .Li fwd
 109 is substituted with
 110 .Li in
 111 on platforms which do not support forward policies.
 112 .Pp
 113 .Ar priority specification
 114 is used to control the placement of the policy within the SPD.
 115 The policy position is determined by
 116 a signed integer where higher priorities indicate the policy is placed
 117 closer to the beginning of the list and lower priorities indicate the
 118 policy is placed closer to the end of the list.
 119 Policies with equal
 120 priorities are added at the end of the group of such policies.
 121 .Pp
 122 Priority can only
 123 be specified when libipsec has been compiled against kernel headers that
 124 support policy priorities (Linux \*[Gt]= 2.6.6).
 125 It takes one of the following formats:
 126 .Bl -tag  -width "discard"
 127 .It Ar {priority,prio} offset
 128 .Ar offset
 129 is an integer in the range -2147483647..214783648.
 130 .It Ar {priority,prio} base {+,-} offset
 131 .Ar base
 132 is either
 133 .Li low (-1073741824) ,
 134 .Li def (0) ,
 135 or
 136 .Li high (1073741824) .
 137 .Pp
 138 .Ar offset
 139 is an unsigned integer.
 140 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
 145 kernel DOES differ.
 146 The relationship between the two can be described as
 147 p(kernel) = 0x80000000 - p(func)
 148 .Pp
 149 With
 150 .Li discard
 151 policy, packets will be dropped if they match the policy.
 152 .It Ar direction [priority specification] Li entrust
 153 .Li entrust
 154 means to consult the SPD defined by
 155 .Xr setkey 8 .
 156 .It Ar direction [priority specification] Li bypass
 157 .Li bypass
 158 means to bypass the IPsec processing.
 159 .Pq the packet will be transmitted in clear .
 160 This is for privileged sockets.
 161 .It Ar direction Bo Ar priority specification Bc Li ipsec Ar request ...
 162 .Li ipsec
 163 means that the matching packets are subject to IPsec processing.
 164 .Li ipsec
 165 can be followed by one or more
 166 .Ar request
 167 strings, which are formatted as below:
 168 .Bl -tag  -width "discard"
 169 .It Ar protocol Li / Ar mode Li / Ar src Li - Ar dst Op Ar /level
 170 .Ar protocol
 171 is either
 172 .Li ah ,
 173 .Li esp ,
 174 or
 175 .Li ipcomp .
 176 .Pp
 177 .Ar mode
 178 is either
 179 .Li transport
 180 or
 181 .Li tunnel .
 182 .Pp
 183 .Ar src
 184 and
 185 .Ar dst
 186 specifies the IPsec endpoint.
 187 .Ar src
 188 always means the
 189 .Dq sending node
 190 and
 191 .Ar dst
 192 always means the
 193 .Dq receiving node .
 194 Therefore, when
 195 .Ar direction
 196 is
 197 .Li in ,
 198 .Ar dst
 199 is this node
 200 and
 201 .Ar src
 202 is the other node
 203 .Pq peer .
 204 If
 205 .Ar mode
 206 is
 207 .Li transport ,
 208 Both
 209 .Ar src
 210 and
 211 .Ar dst
 212 can be omitted.
 213 .Pp
 214 .Ar level
 215 must be set to one of the following:
 216 .Li default , use , require ,
 217 or
 218 .Li unique .
 219 .Li default
 220 means that the kernel should consult the system default policy
 221 defined by
 222 .Xr sysctl 8 ,
 223 such as
 224 .Li net.inet.ipsec.esp_trans_deflev .
 225 See
 226 .Xr ipsec 4
 227 regarding the system default.
 228 .Li use
 229 means that a relevant SA can be used when available,
 230 since the kernel may perform IPsec operation against packets when possible.
 231 In this case, packets can be transmitted in clear
 232 .Pq when SA is not available ,
 233 or encrypted
 234 .Pq when SA is available .
 235 .Li require
 236 means that a relevant SA is required,
 237 since the kernel must perform IPsec operation against packets.
 238 .Li unique
 239 is the same as
 240 .Li require ,
 241 but adds the restriction that the SA for outbound traffic is used
 242 only for this policy.
 243 You may need the identifier in order to relate the policy and the SA
 244 when you define the SA by manual keying.
 245 You can put the decimal number as the identifier after
 246 .Li unique
 247 like
 248 .Li unique : number .
 249 .Li number
 250 must be between 1 and 32767 .
 251 If the
 252 .Ar request
 253 string is kept unambiguous,
 254 .Ar level
 255 and slash prior to
 256 .Ar level
 257 can be omitted.
 258 However, it is encouraged to specify them explicitly
 259 to avoid unintended behavior.
 260 If
 261 .Ar level
 262 is omitted, it will be interpreted as
 263 .Li default .
 264 .El
 265 .Pp
 266 Note that there are slight differences to the specification of
 267 .Xr setkey 8 .
 268 In the specification of
 269 .Xr setkey 8 ,
 270 both
 271 .Li entrust
 272 and
 273 .Li bypass
 274 are not used.
 275 Refer to
 276 .Xr setkey 8
 277 for details.
 278 .Pp
 279 Here are several examples
 280 .Pq long lines are wrapped for readability :
 281 .Bd -literal -offset indent
 282 in discard
 283 out ipsec esp/transport//require
 284 in ipsec ah/transport//require
 285 out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use
 286 in ipsec ipcomp/transport//use
 287         esp/transport//use
 288 .Ed
 289 .El
 290 .Sh RETURN VALUES
 291 .Fn ipsec_set_policy
 292 returns a pointer to the allocated buffer with the policy specification
 293 if successful; otherwise a
 294 .Dv NULL
 295 pointer is returned.
 296 .Fn ipsec_get_policylen
 297 returns a positive value
 298 .Pq meaning the buffer size
 299 on success, and a negative value on errors.
 300 .Fn ipsec_dump_policy
 301 returns a pointer to a dynamically allocated region on success,
 302 and
 303 .Dv NULL
 304 on errors.
 305 .Sh SEE ALSO
 306 .Xr ipsec_strerror 3 ,
 307 .Xr ipsec 4 ,
 308 .Xr setkey 8
 309 .Sh HISTORY
 310 The functions first appeared in the WIDE/KAME IPv6 protocol stack kit.