lib/libipsec/ipsec_set_policy.3

   1 .\"     $KAME: ipsec_set_policy.3,v 1.15 2001/08/17 07:21:36 itojun Exp $
   2 .\"     $FreeBSD: src/lib/libipsec/ipsec_set_policy.3,v 1.3.2.10 2002/12/29 16:35:36 schweikh Exp $
   3 .\"
   4 .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project.
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the project nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .Dd May 5, 1998
  32 .Dt IPSEC_SET_POLICY 3
  33 .Os
  34 .Sh NAME
  35 .Nm ipsec_set_policy ,
  36 .Nm ipsec_get_policylen ,
  37 .Nm ipsec_dump_policy
  38 .Nd manipulate IPsec policy specification structure from readable string
  39 .\"
  40 .Sh LIBRARY
  41 .Lb libipsec
  42 .Sh SYNOPSIS
  43 .In netinet6/ipsec.h
  44 .Ft "char *"
  45 .Fn ipsec_set_policy "char *policy" "int len"
  46 .Ft int
  47 .Fn ipsec_get_policylen "char *buf"
  48 .Ft "char *"
  49 .Fn ipsec_dump_policy "char *buf" "char *delim"
  50 .Sh DESCRIPTION
  51 .Fn ipsec_set_policy
  52 generates IPsec policy specification structure, namely
  53 .Li struct sadb_x_policy
  54 and/or
  55 .Li struct sadb_x_ipsecrequest
  56 from human-readable policy specification.
  57 Policy specification must be given as C string
  58 .Fa policy
  59 and length
  60 .Fa len
  61 of
  62 .Fa policy .
  63 .Fn ipsec_set_policy
  64 will return the buffer of IPsec policy specification structure.
  65 The buffer is dynamically allocated, and must be freed by the caller by calling
  66 .Xr free 3 .
  67 .Pp
  68 You may want the length of the generated buffer such when calling
  69 .Xr setsockopt 2 .
  70 .Fn ipsec_get_policylen
  71 will return the length.
  72 .Pp
  73 .Fn ipsec_dump_policy
  74 converts IPsec policy structure into readable form.
  75 Therefore,
  76 .Fn ipsec_dump_policy
  77 can be regarded as inverse conversion of
  78 .Fn ipsec_set_policy .
  79 .Fa buf
  80 points to a 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 single whitespace is assumed.
  89 .Fn ipsec_dump_policy
  90 returns pointer to dynamically allocated string.
  91 It is caller's responsibility to reclaim the region, by using
  92 .Xr free 3 .
  93 .Pp
  94 .Fa policy
  95 is formatted as either of the following:
  96 .Bl -tag  -width "discard"
  97 .It Ar direction Li discard
  98 .Ar direction
  99 must be
 100 .Li in
 101 or
 102 .Li out .
 103 .Ar direction
 104 specifies which direction the policy needs to be applied.
 105 With
 106 .Li discard
 107 policy, packets will be dropped if they match the policy.
 108 .It Ar direction Li entrust
 109 .Li entrust
 110 means to consult to SPD defined by
 111 .Xr setkey 8 .
 112 .It Ar direction Li bypass
 113 .Li bypass
 114 means to be bypassed the IPsec processing.
 115 (packet will be transmitted in clear).
 116 This is for privileged socket.
 117 .It Xo
 118 .Ar direction
 119 .Li ipsec
 120 .Ar request ...
 121 .Xc
 122 .Li ipsec
 123 means that the matching packets are subject to IPsec processing.
 124 .Li ipsec
 125 can be followed by one or more
 126 .Ar request
 127 string, which is formatted as below:
 128 .Bl -tag  -width "discard"
 129 .It Xo
 130 .Ar protocol
 131 .Li /
 132 .Ar mode
 133 .Li /
 134 .Ar src
 135 .Li -
 136 .Ar dst
 137 .Op Ar /level
 138 .Xc
 139 .Ar protocol
 140 is either
 141 .Li ah ,
 142 .Li esp
 143 or
 144 .Li ipcomp .
 145 .Pp
 146 .Ar mode
 147 is either
 148 .Li transport
 149 or
 150 .Li tunnel .
 151 .Pp
 152 .Ar src
 153 and
 154 .Ar dst
 155 specifies IPsec endpoint.
 156 .Ar src
 157 always means
 158 .Dq sending node
 159 and
 160 .Ar dst
 161 always means
 162 .Dq receiving node .
 163 Therefore, when
 164 .Ar direction
 165 is
 166 .Li in ,
 167 .Ar dst
 168 is this node
 169 and
 170 .Ar src
 171 is the other node
 172 (peer).
 173 If
 174 .Ar mode
 175 is
 176 .Li transport ,
 177 Both
 178 .Ar src
 179 and
 180 .Ar dst
 181 can be omitted.
 182 .Pp
 183 .Ar level
 184 must be set to one of the following:
 185 .Li default , use , require
 186 or
 187 .Li unique .
 188 .Li default
 189 means that the kernel should consult the system default policy
 190 defined by
 191 .Xr sysctl 8 ,
 192 such as
 193 .Li net.inet.ipsec.esp_trans_deflev .
 194 See
 195 .Xr ipsec 4
 196 regarding the system default.
 197 .Li use
 198 means that a relevant SA can be used when available,
 199 since the kernel may perform IPsec operation against packets when possible.
 200 In this case, packets can be transmitted in clear
 201 (when SA is not available),
 202 or encrypted
 203 (when SA is available).
 204 .Li require
 205 means that a relevant SA is required,
 206 since the kernel must perform IPsec operation against packets.
 207 .Li unique
 208 is the same as
 209 .Li require ,
 210 but adds the restriction that the SA for outbound traffic is used
 211 only for this policy.
 212 You may need the identifier in order to relate the policy and the SA
 213 when you define the SA by manual keying.
 214 You can put the decimal number as the identifier after
 215 .Li unique
 216 like
 217 .Li unique : number .
 218 .Li number
 219 must be between 1 and 32767 .
 220 If the
 221 .Ar request
 222 string is kept unambiguous,
 223 .Ar level
 224 and slash prior to
 225 .Ar level
 226 can be omitted.
 227 However, it is encouraged to specify them explicitly
 228 to avoid unintended behaviors.
 229 If
 230 .Ar level
 231 is omitted, it will be interpreted as
 232 .Li default .
 233 .El
 234 .El
 235 .Pp
 236 Note that there is a bit difference of specification from
 237 .Xr setkey 8 .
 238 In specification by
 239 .Xr setkey 8 ,
 240 both entrust and bypass are not used.
 241 Refer to
 242 .Xr setkey 8
 243 for detail.
 244 .Pp
 245 Here are several examples
 246 (long lines are wrapped for readability):
 247 .Bd -literal -offset indent
 248 in discard
 249 out ipsec esp/transport//require
 250 in ipsec ah/transport//require
 251 out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use
 252 in ipsec ipcomp/transport//use
 253         esp/transport//use
 254 .Ed
 255 .Sh RETURN VALUES
 256 .Fn ipsec_set_policy
 257 returns a pointer to the allocated buffer of policy specification if successful; otherwise a NULL pointer is returned.
 258 .Fn ipsec_get_policylen
 259 returns with positive value
 260 (meaning the buffer size)
 261 on success, and negative value on errors.
 262 .Fn ipsec_dump_policy
 263 returns a pointer to dynamically allocated region on success,
 264 and
 265 .Dv NULL
 266 on errors.
 267 .Sh SEE ALSO
 268 .Xr ipsec_strerror 3 ,
 269 .Xr ipsec 4 ,
 270 .Xr setkey 8
 271 .Sh HISTORY
 272 The functions first appeared in WIDE/KAME IPv6 protocol stack kit.
 273 .Pp
 274 IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack
 275 was initially integrated into
 276 .Fx 4.0