1 .\" $KAME: ipsec_set_policy.3,v 1.15 2001/08/17 07:21:36 itojun Exp $
3 .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project.
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
33 .Dt IPSEC_SET_POLICY 3
36 .Nm ipsec_set_policy ,
37 .Nm ipsec_get_policylen ,
39 .Nd create an IPsec policy structure from a human readable string
46 .Fn ipsec_set_policy "char *policy" "int len"
48 .Fn ipsec_get_policylen "char *buf"
50 .Fn ipsec_dump_policy "char *buf" "char *delim"
54 function generates an IPsec policy specification structure,
55 .Li struct sadb_x_policy
57 .Li struct sadb_x_ipsecrequest
58 from a human-readable policy specification.
59 The policy specification must be given as a C string,
62 argument and the length of the string, given as
66 function returns pointer to a buffer which contains a properly formed
67 IPsec policy specification structure.
68 The buffer is dynamically allocated, and must be freed by using the
73 .Fn ipsec_get_policylen
74 function will returns the of the buffer which is needed when passing
75 the specification structure to the
81 function converts an IPsec policy structure into a human readable form.
84 argument points to an IPsec policy structure,
85 .Li struct sadb_x_policy .
87 is a delimiter string, which is usually a blank character.
92 a single white space is assumed.
95 function returns a pointer to dynamically allocated string.
96 It is the caller's responsibility to free the returned pointer using the
102 is given in the following way:
103 .Bl -tag -width "discard"
104 .It Ar direction Li discard
112 specifies which direction the policy needs to be applied, either on
113 inbound or outbound packets.
116 policy is selected, packets will be dropped if they match the policy.
117 .It Ar direction Li entrust
119 means to consult the security policy database
121 in the kernel, as controlled by
123 .It Ar direction Li bypass
126 indicates that IPsec processing should not occur and that the
127 packet will be transmitted in clear.
128 The bypass option is only
129 available to privileged sockets.
137 means that matching packets are processed by IPsec.
139 can be followed by one or more
141 string, which is formatted as:
142 .Bl -tag -width "discard"
160 indicating Authentication Header, Encapsulating Security Protocol or
161 IP Compression protocol is used.
169 the meanings of both modes are described in
176 specify the IP address, either v4 or v6, of the source and destination systems.
179 always stands for the
183 always stands for the
193 is the remote node or peer.
206 must be set to one of the following:
207 .Li default , use , require
211 means that the kernel should consult the default security policies as
217 variables are described in
222 is selected a relevant security association
224 can be used when available but is not necessary.
225 If the SA is available then packets will be handled by IPsec,
226 i.e., encrypted and/or authenticated but if an SA is not available then
227 packets will be transmitted in the clear.
230 option is not recommended because it allows for accidental
231 mis-configurations where encrypted or authenticated link becomes
232 unencrypted or unauthenticated, the
234 keyword is recommended instead of
239 keyword means that a relevant SA is required,
240 and that the kernel must perform IPsec processing on all matching
245 keyword has the same effect as
247 but adds the restriction that the SA for outbound traffic is used
248 only for this policy.
249 You may need the identifier in order to relate the policy and the SA
250 when you define the SA by manual keying using
252 Put the decimal number as the identifier after the
255 .Li unique : number ,
258 must be between 1 and 32767.
262 string is kept unambiguous,
264 and the slash prior to
266 can be omitted but you are encouraged to specify them explicitly
267 to avoid unintended behaviors.
270 is omitted, it will be interpreted as
275 Note that there is a difference between the specification allowed here
278 When specifying security policies with
280 neither entrust nor bypass are used.
287 function returns a pointer to the allocated buffer containing a the
288 policy specification if successful; otherwise a NULL pointer is
292 .Fn ipsec_get_policylen
293 function returns a positive value,
294 indicating the buffer size,
295 on success, and a negative value on error.
298 .Fn ipsec_dump_policy
299 function returns a pointer to a dynamically allocated region
300 containing a human readable security policy on success, and
304 Set a policy that all inbound packets are discarded.
309 All outbound packets are required to be processed by IPsec and
310 transported using ESP.
312 .Dl "out ipsec esp/transport//require"
315 All inbound packets are required to be authenticated using the AH protocol.
317 .Dl "in ipsec ah/transport//require"
320 Tunnel packets outbound through the endpoints at 10.1.1.2 and 10.1.1.1.
322 .Dl "out ipsec esp/tunnel/10.1.1.2-10.1.1.1/require"
324 .Xr ipsec_strerror 3 ,
328 These functions first appeared in WIDE/KAME IPv6 protocol stack kit.
330 IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack
331 was initially integrated into