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