packages/net/ipsec/libipsec/v2_0/doc/manpages/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 .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 a 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 Li discard
  97 .Ar direction
  98 must be
  99 .Li in
 100 or
 101 .Li out .
 102 .Ar direction
 103 specifies which direction the policy needs to be applied.
 104 With
 105 .Li discard
 106 policy, packets will be dropped if they match the policy.
 107 .It Ar direction Li entrust
 108 .Li entrust
 109 means to consult to SPD defined by
 110 .Xr setkey 8 .
 111 .It Ar direction Li bypass
 112 .Li bypass
 113 means to be bypassed the IPsec processing.
 114 .Pq packet will be transmitted in clear .
 115 This is for privileged socket.
 116 .It Xo
 117 .Ar direction
 118 .Li ipsec
 119 .Ar request ...
 120 .Xc
 121 .Li ipsec
 122 means that the matching packets are subject to IPsec processing.
 123 .Li ipsec
 124 can be followed by one or more
 125 .Ar request
 126 string, which is formatted as below:
 127 .Bl -tag  -width "discard"
 128 .It Xo
 129 .Ar protocol
 130 .Li /
 131 .Ar mode
 132 .Li /
 133 .Ar src
 134 .Li -
 135 .Ar dst
 136 .Op Ar /level
 137 .Xc
 138 .Ar protocol
 139 is either
 140 .Li ah ,
 141 .Li esp
 142 or
 143 .Li ipcomp .
 144 .Pp
 145 .Ar mode
 146 is either
 147 .Li transport
 148 or
 149 .Li tunnel .
 150 .Pp
 151 .Ar src
 152 and
 153 .Ar dst
 154 specifies IPsec endpoint.
 155 .Ar src
 156 always means
 157 .Dq sending node
 158 and
 159 .Ar dst
 160 always means
 161 .Dq receiving node .
 162 Therefore, when
 163 .Ar direction
 164 is
 165 .Li in ,
 166 .Ar dst
 167 is this node
 168 and
 169 .Ar src
 170 is the other node
 171 .Pq peer .
 172 If
 173 .Ar mode
 174 is
 175 .Li transport ,
 176 Both
 177 .Ar src
 178 and
 179 .Ar dst
 180 can be omited.
 181 .Pp
 182 .Ar level
 183 must be set to one of the following:
 184 .Li default , use , require
 185 or
 186 .Li unique .
 187 .Li default
 188 means that the kernel should consult the system default policy
 189 defined by
 190 .Xr sysctl 8 ,
 191 such as
 192 .Li net.inet.ipsec.esp_trans_deflev .
 193 See
 194 .Xr ipsec 4
 195 regarding the system default.
 196 .Li use
 197 means that a relevant SA can be used when available,
 198 since the kernel may perform IPsec operation against packets when possible.
 199 In this case, packets can be transmitted in clear
 200 .Pq when SA is not available ,
 201 or encrypted
 202 .Pq when SA is available .
 203 .Li require
 204 means that a relevant SA is required,
 205 since the kernel must perform IPsec operation against packets.
 206 .Li unique
 207 is the same as
 208 .Li require ,
 209 but adds the restriction that the SA for outbound traffic is used
 210 only for this policy.
 211 You may need the identifier in order to relate the policy and the SA
 212 when you define the SA by manual keying.
 213 You can put the decimal number as the identifier after
 214 .Li unique
 215 like
 216 .Li unique : number .
 217 .Li number
 218 must be between 1 and 32767 .
 219 If the
 220 .Ar request
 221 string is kept unambiguous,
 222 .Ar level
 223 and slash prior to
 224 .Ar level
 225 can be omitted.
 226 However, it is encouraged to specify them explicitly
 227 to avoid unintended behaviors.
 228 If
 229 .Ar level
 230 is omitted, it will be interpreted as
 231 .Li default .
 232 .El
 233 .El
 234 .Pp
 235 Note that there is a bit difference of specification from
 236 .Xr setkey 8 .
 237 In specification by
 238 .Xr setkey 8 ,
 239 both entrust and bypass are not used.
 240 Refer to
 241 .Xr setkey 8
 242 for detail.
 243 .Pp
 244 Here are several examples
 245 .Pq long lines are wrapped for readability :
 246 .Bd -literal -offset indent
 247 in discard
 248 out ipsec esp/transport//require
 249 in ipsec ah/transport//require
 250 out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use
 251 in ipsec ipcomp/transport//use
 252         esp/transport//use
 253 .Ed
 254 .Sh RETURN VALUES
 255 .Fn ipsec_set_policy
 256 returns a pointer to the allocated buffer of policy specification if successful; otherwise a NULL pointer is returned.
 257 .Fn ipsec_get_policylen
 258 returns with positive value
 259 .Pq meaning the buffer size
 260 on success, and negative value on errors.
 261 .Fn ipsec_dump_policy
 262 returns a pointer to dynamically allocated region on success,
 263 and
 264 .Dv NULL
 265 on errors.
 266 .Sh SEE ALSO
 267 .Xr ipsec_strerror 3 ,
 268 .Xr ipsec 4 ,
 269 .Xr setkey 8
 270 .Sh HISTORY
 271 The functions first appeared in WIDE/KAME IPv6 protocol stack kit.