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