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 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 readable 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 The
  53 .Fn ipsec_set_policy
  54 function generates IPsec policy specification structure, namely
  55 .Li struct sadb_x_policy
  56 and/or
  57 .Li struct sadb_x_ipsecrequest
  58 from human-readable policy specification.
  59 Policy specification must be given as C string
  60 .Fa policy
  61 and length
  62 .Fa len
  63 of
  64 .Fa policy .
  65 The
  66 .Fn ipsec_set_policy
  67 function will return the buffer of IPsec policy specification structure.
  68 The buffer is dynamically allocated, and must be freed by the caller by calling
  69 .Xr free 3 .
  70 .Pp
  71 You may want the length of the generated buffer such when calling
  72 .Xr setsockopt 2 .
  73 The
  74 .Fn ipsec_get_policylen
  75 function will return the length.
  76 .Pp
  77 The
  78 .Fn ipsec_dump_policy
  79 function converts IPsec policy structure into readable form.
  80 Therefore,
  81 .Fn ipsec_dump_policy
  82 can be regarded as inverse conversion of
  83 .Fn ipsec_set_policy .
  84 .Fa buf
  85 points to an IPsec policy structure,
  86 .Li struct sadb_x_policy .
  87 .Fa delim
  88 is a delimiter string, which is usually a blank character.
  89 If you set
  90 .Fa delim
  91 to
  92 .Dv NULL ,
  93 single whitespace is assumed.
  94 The
  95 .Fn ipsec_dump_policy
  96 function returns a pointer to dynamically allocated string.
  97 It is caller's responsibility to reclaim the region, by using
  98 .Xr free 3 .
  99 .Pp
 100 .Fa policy
 101 is formatted as either of the following:
 102 .Bl -tag  -width "discard"
 103 .It Ar direction Li discard
 104 .Ar direction
 105 must be
 106 .Li in
 107 or
 108 .Li out .
 109 .Ar direction
 110 specifies which direction the policy needs to be applied.
 111 With
 112 .Li discard
 113 policy, packets will be dropped if they match the policy.
 114 .It Ar direction Li entrust
 115 .Li entrust
 116 means to consult to SPD defined by
 117 .Xr setkey 8 .
 118 .It Ar direction Li bypass
 119 .Li bypass
 120 means to be bypassed the IPsec processing.
 121 (packet will be transmitted in clear).
 122 This is for privileged socket.
 123 .It Xo
 124 .Ar direction
 125 .Li ipsec
 126 .Ar request ...
 127 .Xc
 128 .Li ipsec
 129 means that the matching packets are subject to IPsec processing.
 130 .Li ipsec
 131 can be followed by one or more
 132 .Ar request
 133 string, which is formatted as below:
 134 .Bl -tag  -width "discard"
 135 .It Xo
 136 .Ar protocol
 137 .Li /
 138 .Ar mode
 139 .Li /
 140 .Ar src
 141 .Li -
 142 .Ar dst
 143 .Op Ar /level
 144 .Xc
 145 .Ar protocol
 146 is either
 147 .Li ah ,
 148 .Li esp
 149 or
 150 .Li ipcomp .
 151 .Pp
 152 .Ar mode
 153 is either
 154 .Li transport
 155 or
 156 .Li tunnel .
 157 .Pp
 158 .Ar src
 159 and
 160 .Ar dst
 161 specifies IPsec endpoint.
 162 .Ar src
 163 always means
 164 .Dq sending node
 165 and
 166 .Ar dst
 167 always means
 168 .Dq receiving node .
 169 Therefore, when
 170 .Ar direction
 171 is
 172 .Li in ,
 173 .Ar dst
 174 is this node
 175 and
 176 .Ar src
 177 is the other node
 178 (peer).
 179 If
 180 .Ar mode
 181 is
 182 .Li transport ,
 183 Both
 184 .Ar src
 185 and
 186 .Ar dst
 187 can be omitted.
 188 .Pp
 189 .Ar level
 190 must be set to one of the following:
 191 .Li default , use , require
 192 or
 193 .Li unique .
 194 .Li default
 195 means that the kernel should consult the system default policy
 196 defined by
 197 .Xr sysctl 8 ,
 198 such as
 199 .Li net.inet.ipsec.esp_trans_deflev .
 200 See
 201 .Xr ipsec 4
 202 regarding the system default.
 203 .Li use
 204 means that a relevant SA can be used when available,
 205 since the kernel may perform IPsec operation against packets when possible.
 206 In this case, packets can be transmitted in clear
 207 (when SA is not available),
 208 or encrypted
 209 (when SA is available).
 210 .Li require
 211 means that a relevant SA is required,
 212 since the kernel must perform IPsec operation against packets.
 213 .Li unique
 214 is the same as
 215 .Li require ,
 216 but adds the restriction that the SA for outbound traffic is used
 217 only for this policy.
 218 You may need the identifier in order to relate the policy and the SA
 219 when you define the SA by manual keying.
 220 You can put the decimal number as the identifier after
 221 .Li unique
 222 like
 223 .Li unique : number .
 224 .Li number
 225 must be between 1 and 32767 .
 226 If the
 227 .Ar request
 228 string is kept unambiguous,
 229 .Ar level
 230 and slash prior to
 231 .Ar level
 232 can be omitted.
 233 However, it is encouraged to specify them explicitly
 234 to avoid unintended behaviors.
 235 If
 236 .Ar level
 237 is omitted, it will be interpreted as
 238 .Li default .
 239 .El
 240 .El
 241 .Pp
 242 Note that there is a bit difference of specification from
 243 .Xr setkey 8 .
 244 In specification by
 245 .Xr setkey 8 ,
 246 both entrust and bypass are not used.
 247 Refer to
 248 .Xr setkey 8
 249 for detail.
 250 .Pp
 251 Here are several examples
 252 (long lines are wrapped for readability):
 253 .Bd -literal -offset indent
 254 in discard
 255 out ipsec esp/transport//require
 256 in ipsec ah/transport//require
 257 out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use
 258 in ipsec ipcomp/transport//use
 259         esp/transport//use
 260 .Ed
 261 .Sh RETURN VALUES
 262 The
 263 .Fn ipsec_set_policy
 264 function returns a pointer to the allocated buffer of policy specification if
 265 successful; otherwise a NULL pointer is returned.
 266 The
 267 .Fn ipsec_get_policylen
 268 function returns with positive value
 269 (meaning the buffer size)
 270 on success, and negative value on errors.
 271 The
 272 .Fn ipsec_dump_policy
 273 function returns a pointer to dynamically allocated region on success,
 274 and
 275 .Dv NULL
 276 on errors.
 277 .Sh SEE ALSO
 278 .Xr ipsec_strerror 3 ,
 279 .Xr ipsec 4 ,
 280 .Xr setkey 8
 281 .Sh HISTORY
 282 The functions first appeared in WIDE/KAME IPv6 protocol stack kit.
 283 .Pp
 284 IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack
 285 was initially integrated into
 286 .Fx 4.0