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