1: .\" $NetBSD: ipsec_set_policy.3,v 1.15 2010/03/05 06:47:58 tteras Exp $
2: .\"
3: .\" $KAME: ipsec_set_policy.3,v 1.16 2003/01/06 21:59:03 sumikawa Exp $
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 human-readable policy 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
53: generates an IPsec policy specification structure, namely
54: .Li struct sadb_x_policy
55: and/or
56: .Li struct sadb_x_ipsecrequest
57: from a human-readable policy specification.
58: The policy specification must be given as a C string
59: .Fa policy
60: and its length
61: .Fa len .
62: .Fn ipsec_set_policy
63: will return a buffer with the corresponding IPsec policy specification structure.
64: The buffer is dynamically allocated, and must be
65: .Xr free 3 Ap d
66: by the caller.
67: .Pp
68: You can get the length of the generated buffer with
69: .Fn ipsec_get_policylen
70: (i.e. for calling
71: .Xr setsockopt 2 ) .
72: .Pp
73: .Fn ipsec_dump_policy
74: converts an IPsec policy structure into human-readable form.
75: Therefore,
76: .Fn ipsec_dump_policy
77: can be regarded as the inverse function to
78: .Fn ipsec_set_policy .
79: .Fa buf
80: points to an IPsec policy structure,
81: .Li struct sadb_x_policy .
82: .Fa delim
83: is a delimiter string, which is usually a blank character.
84: If you set
85: .Fa delim
86: to
87: .Dv NULL ,
88: a single whitespace is assumed.
89: .Fn ipsec_dump_policy
90: returns a pointer to a dynamically allocated string.
91: It is the caller's responsibility to
92: .Xr free 3
93: it.
94: .Pp
95: .Fa policy
96: is formatted as either of the following:
97: .Bl -tag -width "discard"
98: .It Ar direction [priority specification] Li discard
99: .Ar direction
100: must be
101: .Li in ,
102: .Li out ,
103: or
104: .Li fwd .
105: .Ar direction
106: specifies in which direction the policy needs to be applied.
107: The non-standard direction
108: .Li fwd
109: is substituted with
110: .Li in
111: on platforms which do not support forward policies.
112: .Pp
113: .Ar priority specification
114: is used to control the placement of the policy within the SPD.
115: The policy position is determined by
116: a signed integer where higher priorities indicate the policy is placed
117: closer to the beginning of the list and lower priorities indicate the
118: policy is placed closer to the end of the list.
119: Policies with equal
120: priorities are added at the end of the group of such policies.
121: .Pp
122: Priority can only
123: be specified when libipsec has been compiled against kernel headers that
124: support policy priorities (Linux \*[Gt]= 2.6.6).
125: It takes one of the following formats:
126: .Bl -tag -width "discard"
127: .It Ar {priority,prio} offset
128: .Ar offset
129: is an integer in the range \-2147483647..214783648.
130: .It Ar {priority,prio} base {+,-} offset
131: .Ar base
132: is either
133: .Li low (-1073741824) ,
134: .Li def (0) ,
135: or
136: .Li high (1073741824) .
137: .Pp
138: .Ar offset
139: is an unsigned integer.
140: It can be up to 1073741824 for
141: positive offsets, and up to 1073741823 for negative offsets.
142: .El
143: .Pp
144: The interpretation of policy priority in these functions and the
145: kernel DOES differ.
146: The relationship between the two can be described as
147: p(kernel) = 0x80000000 - p(func)
148: .Pp
149: With
150: .Li discard
151: policy, packets will be dropped if they match the policy.
152: .It Ar direction [priority specification] Li entrust
153: .Li entrust
154: means to consult the SPD defined by
155: .Xr setkey 8 .
156: .It Ar direction [priority specification] Li bypass
157: .Li bypass
158: means to bypass the IPsec processing.
159: .Pq the packet will be transmitted in clear .
160: This is for privileged sockets.
161: .It Ar direction Bo Ar priority specification Bc Li ipsec Ar request ...
162: .Li ipsec
163: means that the matching packets are subject to IPsec processing.
164: .Li ipsec
165: can be followed by one or more
166: .Ar request
167: strings, which are formatted as below:
168: .Bl -tag -width "discard"
169: .It Ar protocol Li / Ar mode Li / Ar src Li - Ar dst Op Ar /level
170: .Ar protocol
171: is either
172: .Li ah ,
173: .Li esp ,
174: or
175: .Li ipcomp .
176: .Pp
177: .Ar mode
178: is either
179: .Li transport
180: or
181: .Li tunnel .
182: .Pp
183: .Ar src
184: and
185: .Ar dst
186: specifies the IPsec endpoint.
187: .Ar src
188: always means the
189: .Dq sending node
190: and
191: .Ar dst
192: always means the
193: .Dq receiving node .
194: Therefore, when
195: .Ar direction
196: is
197: .Li in ,
198: .Ar dst
199: is this node
200: and
201: .Ar src
202: is the other node
203: .Pq peer .
204: If
205: .Ar mode
206: is
207: .Li transport ,
208: Both
209: .Ar src
210: and
211: .Ar dst
212: can be omitted.
213: .Pp
214: .Ar level
215: must be set to one of the following:
216: .Li default , use , require ,
217: or
218: .Li unique .
219: .Li default
220: means that the kernel should consult the system default policy
221: defined by
222: .Xr sysctl 8 ,
223: such as
224: .Li net.inet.ipsec.esp_trans_deflev .
225: See
226: .Xr ipsec 4
227: regarding the system default.
228: .Li use
229: means that a relevant SA can be used when available,
230: since the kernel may perform IPsec operation against packets when possible.
231: In this case, packets can be transmitted in clear
232: .Pq when SA is not available ,
233: or encrypted
234: .Pq when SA is available .
235: .Li require
236: means that a relevant SA is required,
237: since the kernel must perform IPsec operation against packets.
238: .Li unique
239: is the same as
240: .Li require ,
241: but adds the restriction that the SA for outbound traffic is used
242: only for this policy.
243: You may need the identifier in order to relate the policy and the SA
244: when you define the SA by manual keying.
245: You can put the decimal number as the identifier after
246: .Li unique
247: like
248: .Li unique : number .
249: .Li number
250: must be between 1 and 32767 .
251: If the
252: .Ar request
253: string is kept unambiguous,
254: .Ar level
255: and slash prior to
256: .Ar level
257: can be omitted.
258: However, it is encouraged to specify them explicitly
259: to avoid unintended behavior.
260: If
261: .Ar level
262: is omitted, it will be interpreted as
263: .Li default .
264: .El
265: .Pp
266: Note that there are slight differences to the specification of
267: .Xr setkey 8 .
268: In the specification of
269: .Xr setkey 8 ,
270: both
271: .Li entrust
272: and
273: .Li bypass
274: are not used.
275: Refer to
276: .Xr setkey 8
277: for details.
278: .Pp
279: Here are several examples
280: .Pq long lines are wrapped for readability :
281: .Bd -literal -offset indent
282: in discard
283: out ipsec esp/transport//require
284: in ipsec ah/transport//require
285: out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use
286: in ipsec ipcomp/transport//use
287: esp/transport//use
288: .Ed
289: .El
290: .Sh RETURN VALUES
291: .Fn ipsec_set_policy
292: returns a pointer to the allocated buffer with the policy specification
293: if successful; otherwise a
294: .Dv NULL
295: pointer is returned.
296: .Fn ipsec_get_policylen
297: returns a positive value
298: .Pq meaning the buffer size
299: on success, and a negative value on errors.
300: .Fn ipsec_dump_policy
301: returns a pointer to a dynamically allocated region on success,
302: and
303: .Dv NULL
304: on errors.
305: .Sh SEE ALSO
306: .Xr ipsec_strerror 3 ,
307: .Xr ipsec 4 ,
308: .Xr setkey 8
309: .Sh HISTORY
310: The functions first appeared in the WIDE/KAME IPv6 protocol stack kit.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to ipsec_set_policy.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / ipsec-tools / src / libipsec