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