ipsec/ipsec_set_policy.3

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