1.\"	$NetBSD: ipsec_set_policy.3,v 1.13 2006/09/09 16:22:09 manu 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 Xo
128.Ar {priority,prio} offset
129.Xc
130.Ar offset
131is an integer in the range -2147483647..214783648.
132.It Xo
133.Ar {priority,prio} base {+,-} offset
134.Xc
135.Ar base
136is either
137.Li low (-1073741824) ,
138.Li def (0) ,
139or
140.Li high (1073741824) .
141.Pp
142.Ar offset
143is an unsigned integer.
144It can be up to 1073741824 for
145positive offsets, and up to 1073741823 for negative offsets.
146.El
147.Pp
148The interpretation of policy priority in these functions and the
149kernel DOES differ.
150The relationship between the two can be described as
151p(kernel) = 0x80000000 - p(func)
152.Pp
153With
154.Li discard
155policy, packets will be dropped if they match the policy.
156.It Ar direction [priority specification] Li entrust
157.Li entrust
158means to consult the SPD defined by
159.Xr setkey 8 .
160.It Ar direction [priority specification] Li bypass
161.Li bypass
162means to bypass the IPsec processing.
163.Pq the packet will be transmitted in clear .
164This is for privileged sockets.
165.It Xo
166.Ar direction
167.Bq Ar priority specification
168.Li ipsec
169.Ar request ...
170.Xc
171.Li ipsec
172means that the matching packets are subject to IPsec processing.
173.Li ipsec
174can be followed by one or more
175.Ar request
176strings, which are formatted as below:
177.Bl -tag  -width "discard"
178.It Xo
179.Ar protocol
180.Li /
181.Ar mode
182.Li /
183.Ar src
184.Li -
185.Ar dst
186.Op Ar /level
187.Xc
188.Ar protocol
189is either
190.Li ah ,
191.Li esp ,
192or
193.Li ipcomp .
194.Pp
195.Ar mode
196is either
197.Li transport
198or
199.Li tunnel .
200.Pp
201.Ar src
202and
203.Ar dst
204specifies the IPsec endpoint.
205.Ar src
206always means the
207.Dq sending node
208and
209.Ar dst
210always means the
211.Dq receiving node .
212Therefore, when
213.Ar direction
214is
215.Li in ,
216.Ar dst
217is this node
218and
219.Ar src
220is the other node
221.Pq peer .
222If
223.Ar mode
224is
225.Li transport ,
226Both
227.Ar src
228and
229.Ar dst
230can be omitted.
231.Pp
232.Ar level
233must be set to one of the following:
234.Li default , use , require ,
235or
236.Li unique .
237.Li default
238means that the kernel should consult the system default policy
239defined by
240.Xr sysctl 8 ,
241such as
242.Li net.inet.ipsec.esp_trans_deflev .
243See
244.Xr ipsec 4
245regarding the system default.
246.Li use
247means that a relevant SA can be used when available,
248since the kernel may perform IPsec operation against packets when possible.
249In this case, packets can be transmitted in clear
250.Pq when SA is not available ,
251or encrypted
252.Pq when SA is available .
253.Li require
254means that a relevant SA is required,
255since the kernel must perform IPsec operation against packets.
256.Li unique
257is the same as
258.Li require ,
259but adds the restriction that the SA for outbound traffic is used
260only for this policy.
261You may need the identifier in order to relate the policy and the SA
262when you define the SA by manual keying.
263You can put the decimal number as the identifier after
264.Li unique
265like
266.Li unique : number .
267.Li number
268must be between 1 and 32767 .
269If the
270.Ar request
271string is kept unambiguous,
272.Ar level
273and slash prior to
274.Ar level
275can be omitted.
276However, it is encouraged to specify them explicitly
277to avoid unintended behavior.
278If
279.Ar level
280is omitted, it will be interpreted as
281.Li default .
282.El
283.Pp
284Note that there are slight differences to the specification of
285.Xr setkey 8 .
286In the specification of
287.Xr setkey 8 ,
288both
289.Li entrust
290and
291.Li bypass
292are not used.
293Refer to
294.Xr setkey 8
295for details.
296.Pp
297Here are several examples
298.Pq long lines are wrapped for readability :
299.Bd -literal -offset indent
300in discard
301out ipsec esp/transport//require
302in ipsec ah/transport//require
303out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use
304in ipsec ipcomp/transport//use
305        esp/transport//use
306.Ed
307.El
308.Sh RETURN VALUES
309.Fn ipsec_set_policy
310returns a pointer to the allocated buffer with the policy specification
311if successful; otherwise a
312.Dv NULL
313pointer is returned.
314.Fn ipsec_get_policylen
315returns a positive value
316.Pq meaning the buffer size
317on success, and a negative value on errors.
318.Fn ipsec_dump_policy
319returns a pointer to a dynamically allocated region on success,
320and
321.Dv NULL
322on errors.
323.Sh SEE ALSO
324.Xr ipsec_strerror 3 ,
325.Xr ipsec 4 ,
326.Xr setkey 8
327.Sh HISTORY
328The functions first appeared in the WIDE/KAME IPv6 protocol stack kit.
329