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