1.\" $KAME: ipsec_set_policy.3,v 1.15 2001/08/17 07:21:36 itojun Exp $ 2.\" 3.\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 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. 17.\" 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 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd February 14, 2006 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 create an IPsec policy structure from a human 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 52The 53.Fn ipsec_set_policy 54function generates an IPsec policy specification structure, 55.Li struct sadb_x_policy 56and/or 57.Li struct sadb_x_ipsecrequest 58from a human-readable policy specification. 59The policy specification must be given as a C string, 60passed in the 61.Fa policy 62argument and the length of the string, given as 63.Fa len . 64The 65.Fn ipsec_set_policy 66function returns pointer to a buffer which contains a properly formed 67IPsec policy specification structure. 68The buffer is dynamically allocated, and must be freed by using the 69.Xr free 3 70library function. 71.Pp 72The 73.Fn ipsec_get_policylen 74function will returns the of the buffer which is needed when passing 75the specification structure to the 76.Xr setsockopt 2 77system call. 78.Pp 79The 80.Fn ipsec_dump_policy 81function converts an IPsec policy structure into a human readable form. 82The 83.Fa buf 84argument points to an IPsec policy structure, 85.Li struct sadb_x_policy . 86.Fa delim 87is a delimiter string, which is usually a blank character. 88If you set 89.Fa delim 90to 91.Dv NULL , 92a single white space is assumed. 93The 94.Fn ipsec_dump_policy 95function returns a pointer to dynamically allocated string. 96It is the caller's responsibility to free the returned pointer using the 97.Xr free 3 98library call. 99.Pp 100A 101.Fa policy 102is given in the following way: 103.Bl -tag -width "discard" 104.It Ar direction Li discard 105The 106.Ar direction 107must be 108.Li in 109or 110.Li out 111and 112specifies which direction the policy needs to be applied, either on 113inbound or outbound packets. 114When the 115.Li discard 116policy is selected, packets will be dropped if they match the policy. 117.It Ar direction Li entrust 118.Li entrust 119means to consult the security policy database 120(SPD) 121in the kernel, as controlled by 122.Xr setkey 8 . 123.It Ar direction Li bypass 124A direction of 125.Li bypass 126indicates that IPsec processing should not occur and that the 127packet will be transmitted in clear. The bypass option is only 128available to privileged sockets. 129.It Xo 130.Ar direction 131.Li ipsec 132.Ar request ... 133.Xc 134A direction of 135.Li ipsec 136means that matching packets are processed by IPsec. 137.Li ipsec 138can be followed by one or more 139.Ar request 140string, which is formatted as: 141.Bl -tag -width "discard" 142.It Xo 143.Ar protocol 144.Li / 145.Ar mode 146.Li / 147.Ar src 148.Li - 149.Ar dst 150.Op Ar /level 151.Xc 152The 153.Ar protocol 154is one of: 155.Li ah , 156.Li esp 157or 158.Li ipcomp 159indicating Authentication Header, Encapsulating Security Protocol or 160IP Compression protocol is used. 161.Pp 162The 163.Ar mode 164is either 165.Li transport 166or 167.Li tunnel 168the meanings of both modes are described in 169.Xr ipsec 4 . 170.Pp 171The 172.Ar src 173and 174.Ar dst 175specify the IP address, either v4 or v6, of the source and destination systems. 176The 177.Ar src 178always stands for the 179.Dq sending node 180and 181.Ar dst 182always stands for the 183.Dq receiving node . 184When 185.Ar direction 186is 187.Li in , 188.Ar dst 189is this local node 190and 191.Ar src 192is the remote node or peer. 193If 194.Ar mode 195is 196.Li transport , 197both 198.Ar src 199and 200.Ar dst 201can be omitted. 202.Pp 203The 204.Ar level 205must be set to one of the following: 206.Li default , use , require 207or 208.Li unique . 209.Li default 210means that the kernel should consult the default security policies as 211defined by a set of 212.Xr sysctl 8 , 213variables. The relevant 214.Xr sysctl 8 215variables are described in 216.Xr ipsec 4 . 217.Pp 218When 219.Li use 220is selected a relevant security association 221(SA) 222can be used when available but is not necessary. 223If the SA is available then packets will be handled by IPsec, 224i.e. encrypted and/or authenticated but if an SA is not available then 225packets will be transmitted in the clear. The 226.Li use 227option is not recommended because it allows for accidental 228mis-configurations where encrypted or authenticated link becomes 229unencrypted or unauthenticated, the 230.Li require 231keyword is recommended instead of 232.Li use 233where possible. 234Using the 235.Li require 236keyword means that a relevant SA is required, 237and that the kernel must perform IPsec processing on all matching 238packets. 239.Pp 240The 241.Li unique 242keyword has the same effect as 243.Li require , 244but adds the restriction that the SA for outbound traffic is used 245only for this policy. 246You may need the identifier in order to relate the policy and the SA 247when you define the SA by manual keying using 248.Xr setkey 8 . 249Put the decimal number as the identifier after the 250.Li unique 251keyword in this way: 252.Li unique : number , 253where 254.Li number 255must be between 1 and 32767. 256.Pp 257If the 258.Ar request 259string is kept unambiguous, 260.Ar level 261and the slash prior to 262.Ar level 263can be omitted but you are encouraged to specify them explicitly 264to avoid unintended behaviors. 265If 266.Ar level 267is omitted, it will be interpreted as 268.Li default . 269.El 270.El 271.Pp 272Note that there is a difference between the specification allowed here 273and in 274.Xr setkey 8 . 275When specifying security policies with 276.Xr setkey 8 , 277neither entrust nor bypass are used. 278Refer to 279.Xr setkey 8 280for details. 281.Sh EXAMPLES 282Set a policy that all inbound packets are discarded. 283.Bd -literal -offset indent 284in discard 285 286.Ed 287.\" 288All outbound packets are required to be processed by IPsec and 289transported using ESP. 290.Bd -literal -offset indent 291out ipsec esp/transport//require 292 293.Ed 294.\" 295All inbound packets are required to be authenticated using the AH protocol. 296.Bd -literal -offset indent 297in ipsec ah/transport//require 298 299.Ed 300.\" 301Tunnel packets outbound through the endpoints at 10.1.1.2 and 10.1.1.1. 302.Bd -literal -offset indent 303out ipsec esp/tunnel/10.1.1.2-10.1.1.1/require 304 305.Ed 306.\" 307.Sh RETURN VALUES 308The 309.Fn ipsec_set_policy 310function returns a pointer to the allocated buffer containing a the 311policy specification if successful; otherwise a NULL pointer is 312returned. 313.Pp 314The 315.Fn ipsec_get_policylen 316function returns a positive value, 317indicating the buffer size, 318on success, and a negative value on error. 319.Pp 320The 321.Fn ipsec_dump_policy 322function returns a pointer to a dynamically allocated region 323containing a human readable security policy on success, and 324.Dv NULL 325on error. 326.Sh SEE ALSO 327.Xr ipsec_strerror 3 , 328.Xr ipsec 4 , 329.Xr setkey 8 330.Sh HISTORY 331These functions first appeared in WIDE/KAME IPv6 protocol stack kit. 332.Pp 333IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack 334was initially integrated into 335.Fx 4.0 336