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