source: rtems-libbsd/ipsec-tools/src/libipsec/ipsec_set_policy.3 @ ff36f5e

5-freebsd-12
Last change on this file since ff36f5e was ff36f5e, checked in by Christian Mauderer <christian.mauderer@…>, on May 30, 2018 at 12:27:35 PM

Import ipsec-tools 0.8.2.

Import unchanged ipsec-tools sources in the release version 0.8.2. The
homepage of ipsec-tools is http://ipsec-tools.sourceforge.net/. The
sources can be obtained from there.

  • Property mode set to 100644
File size: 8.1 KB
Line 
1.\"     $NetBSD: ipsec_set_policy.3,v 1.15 2010/03/05 06:47:58 tteras Exp $
2.\"
3.\"     $KAME: ipsec_set_policy.3,v 1.16 2003/01/06 21:59:03 sumikawa 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 human-readable policy 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
53generates an IPsec policy specification structure, namely
54.Li struct sadb_x_policy
55and/or
56.Li struct sadb_x_ipsecrequest
57from a human-readable policy specification.
58The policy specification must be given as a C string
59.Fa policy
60and its length
61.Fa len .
62.Fn ipsec_set_policy
63will return a buffer with the corresponding IPsec policy specification structure.
64The buffer is dynamically allocated, and must be
65.Xr free 3 Ap d
66by the caller.
67.Pp
68You can get the length of the generated buffer with
69.Fn ipsec_get_policylen
70(i.e. for calling
71.Xr setsockopt 2 ) .
72.Pp
73.Fn ipsec_dump_policy
74converts an IPsec policy structure into human-readable form.
75Therefore,
76.Fn ipsec_dump_policy
77can be regarded as the inverse function to
78.Fn ipsec_set_policy .
79.Fa buf
80points to an IPsec policy structure,
81.Li struct sadb_x_policy .
82.Fa delim
83is a delimiter string, which is usually a blank character.
84If you set
85.Fa delim
86to
87.Dv NULL ,
88a single whitespace is assumed.
89.Fn ipsec_dump_policy
90returns a pointer to a dynamically allocated string.
91It is the caller's responsibility to
92.Xr free 3
93it.
94.Pp
95.Fa policy
96is formatted as either of the following:
97.Bl -tag  -width "discard"
98.It Ar direction [priority specification] Li discard
99.Ar direction
100must be
101.Li in ,
102.Li out ,
103or
104.Li fwd .
105.Ar direction
106specifies in which direction the policy needs to be applied.
107The non-standard direction
108.Li fwd
109is substituted with
110.Li in
111on platforms which do not support forward policies.
112.Pp
113.Ar priority specification
114is used to control the placement of the policy within the SPD.
115The policy position is determined by
116a signed integer where higher priorities indicate the policy is placed
117closer to the beginning of the list and lower priorities indicate the
118policy is placed closer to the end of the list.
119Policies with equal
120priorities are added at the end of the group of such policies.
121.Pp
122Priority can only
123be specified when libipsec has been compiled against kernel headers that
124support policy priorities (Linux \*[Gt]= 2.6.6).
125It takes one of the following formats:
126.Bl -tag  -width "discard"
127.It Ar {priority,prio} offset
128.Ar offset
129is an integer in the range \-2147483647..214783648.
130.It Ar {priority,prio} base {+,-} offset
131.Ar base
132is either
133.Li low (-1073741824) ,
134.Li def (0) ,
135or
136.Li high (1073741824) .
137.Pp
138.Ar offset
139is an unsigned integer.
140It can be up to 1073741824 for
141positive offsets, and up to 1073741823 for negative offsets.
142.El
143.Pp
144The interpretation of policy priority in these functions and the
145kernel DOES differ.
146The relationship between the two can be described as
147p(kernel) = 0x80000000 - p(func)
148.Pp
149With
150.Li discard
151policy, packets will be dropped if they match the policy.
152.It Ar direction [priority specification] Li entrust
153.Li entrust
154means to consult the SPD defined by
155.Xr setkey 8 .
156.It Ar direction [priority specification] Li bypass
157.Li bypass
158means to bypass the IPsec processing.
159.Pq the packet will be transmitted in clear .
160This is for privileged sockets.
161.It Ar direction Bo Ar priority specification Bc Li ipsec Ar request ...
162.Li ipsec
163means that the matching packets are subject to IPsec processing.
164.Li ipsec
165can be followed by one or more
166.Ar request
167strings, which are formatted as below:
168.Bl -tag  -width "discard"
169.It Ar protocol Li / Ar mode Li / Ar src Li - Ar dst Op Ar /level
170.Ar protocol
171is either
172.Li ah ,
173.Li esp ,
174or
175.Li ipcomp .
176.Pp
177.Ar mode
178is either
179.Li transport
180or
181.Li tunnel .
182.Pp
183.Ar src
184and
185.Ar dst
186specifies the IPsec endpoint.
187.Ar src
188always means the
189.Dq sending node
190and
191.Ar dst
192always means the
193.Dq receiving node .
194Therefore, when
195.Ar direction
196is
197.Li in ,
198.Ar dst
199is this node
200and
201.Ar src
202is the other node
203.Pq peer .
204If
205.Ar mode
206is
207.Li transport ,
208Both
209.Ar src
210and
211.Ar dst
212can be omitted.
213.Pp
214.Ar level
215must be set to one of the following:
216.Li default , use , require ,
217or
218.Li unique .
219.Li default
220means that the kernel should consult the system default policy
221defined by
222.Xr sysctl 8 ,
223such as
224.Li net.inet.ipsec.esp_trans_deflev .
225See
226.Xr ipsec 4
227regarding the system default.
228.Li use
229means that a relevant SA can be used when available,
230since the kernel may perform IPsec operation against packets when possible.
231In this case, packets can be transmitted in clear
232.Pq when SA is not available ,
233or encrypted
234.Pq when SA is available .
235.Li require
236means that a relevant SA is required,
237since the kernel must perform IPsec operation against packets.
238.Li unique
239is the same as
240.Li require ,
241but adds the restriction that the SA for outbound traffic is used
242only for this policy.
243You may need the identifier in order to relate the policy and the SA
244when you define the SA by manual keying.
245You can put the decimal number as the identifier after
246.Li unique
247like
248.Li unique : number .
249.Li number
250must be between 1 and 32767 .
251If the
252.Ar request
253string is kept unambiguous,
254.Ar level
255and slash prior to
256.Ar level
257can be omitted.
258However, it is encouraged to specify them explicitly
259to avoid unintended behavior.
260If
261.Ar level
262is omitted, it will be interpreted as
263.Li default .
264.El
265.Pp
266Note that there are slight differences to the specification of
267.Xr setkey 8 .
268In the specification of
269.Xr setkey 8 ,
270both
271.Li entrust
272and
273.Li bypass
274are not used.
275Refer to
276.Xr setkey 8
277for details.
278.Pp
279Here are several examples
280.Pq long lines are wrapped for readability :
281.Bd -literal -offset indent
282in discard
283out ipsec esp/transport//require
284in ipsec ah/transport//require
285out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use
286in ipsec ipcomp/transport//use
287        esp/transport//use
288.Ed
289.El
290.Sh RETURN VALUES
291.Fn ipsec_set_policy
292returns a pointer to the allocated buffer with the policy specification
293if successful; otherwise a
294.Dv NULL
295pointer is returned.
296.Fn ipsec_get_policylen
297returns a positive value
298.Pq meaning the buffer size
299on success, and a negative value on errors.
300.Fn ipsec_dump_policy
301returns a pointer to a dynamically allocated region on success,
302and
303.Dv NULL
304on errors.
305.Sh SEE ALSO
306.Xr ipsec_strerror 3 ,
307.Xr ipsec 4 ,
308.Xr setkey 8
309.Sh HISTORY
310The functions first appeared in the WIDE/KAME IPv6 protocol stack kit.
Note: See TracBrowser for help on using the repository browser.