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