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 netipsec/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 returns the length 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. 128The bypass option is only 129available to privileged sockets. 130.It Xo 131.Ar direction 132.Li ipsec 133.Ar request ... 134.Xc 135A direction of 136.Li ipsec 137means that matching packets are processed by IPsec. 138.Li ipsec 139can be followed by one or more 140.Ar request 141string, which is formatted as: 142.Bl -tag -width "discard" 143.It Xo 144.Ar protocol 145.Li / 146.Ar mode 147.Li / 148.Ar src 149.Li - 150.Ar dst 151.Op Ar /level 152.Xc 153The 154.Ar protocol 155is one of: 156.Li ah , 157.Li esp 158or 159.Li ipcomp 160indicating Authentication Header, Encapsulating Security Protocol or 161IP Compression protocol is used. 162.Pp 163The 164.Ar mode 165is either 166.Li transport 167or 168.Li tunnel 169the meanings of both modes are described in 170.Xr ipsec 4 . 171.Pp 172The 173.Ar src 174and 175.Ar dst 176specify the IP address, either v4 or v6, of the source and destination systems. 177The 178.Ar src 179always stands for the 180.Dq sending node 181and 182.Ar dst 183always stands for the 184.Dq receiving node . 185When 186.Ar direction 187is 188.Li in , 189.Ar dst 190is this local node 191and 192.Ar src 193is the remote node or peer. 194If 195.Ar mode 196is 197.Li transport , 198both 199.Ar src 200and 201.Ar dst 202can be omitted. 203.Pp 204The 205.Ar level 206must be set to one of the following: 207.Li default , use , require 208or 209.Li unique . 210.Li default 211means that the kernel should consult the default security policies as 212defined by a set of 213.Xr sysctl 8 , 214variables. 215The relevant 216.Xr sysctl 8 217variables are described in 218.Xr ipsec 4 . 219.Pp 220When 221.Li use 222is selected a relevant security association 223(SA) 224can be used when available but is not necessary. 225If the SA is available then packets will be handled by IPsec, 226i.e., encrypted and/or authenticated but if an SA is not available then 227packets will be transmitted in the clear. 228The 229.Li use 230option is not recommended because it allows for accidental 231mis-configurations where encrypted or authenticated link becomes 232unencrypted or unauthenticated, the 233.Li require 234keyword is recommended instead of 235.Li use 236where possible. 237Using the 238.Li require 239keyword means that a relevant SA is required, 240and that the kernel must perform IPsec processing on all matching 241packets. 242.Pp 243The 244.Li unique 245keyword has the same effect as 246.Li require , 247but adds the restriction that the SA for outbound traffic is used 248only for this policy. 249You may need the identifier in order to relate the policy and the SA 250when you define the SA by manual keying using 251.Xr setkey 8 . 252Put the decimal number as the identifier after the 253.Li unique 254keyword in this way: 255.Li unique : number , 256where 257.Li number 258must be between 1 and 32767. 259.Pp 260If the 261.Ar request 262string is kept unambiguous, 263.Ar level 264and the slash prior to 265.Ar level 266can be omitted but you are encouraged to specify them explicitly 267to avoid unintended behaviors. 268If 269.Ar level 270is omitted, it will be interpreted as 271.Li default . 272.El 273.El 274.Pp 275Note that there is a difference between the specification allowed here 276and in 277.Xr setkey 8 . 278When specifying security policies with 279.Xr setkey 8 , 280neither entrust nor bypass are used. 281Refer to 282.Xr setkey 8 283for details. 284.Sh RETURN VALUES 285The 286.Fn ipsec_set_policy 287function returns a pointer to the allocated buffer containing a the 288policy specification if successful; otherwise a NULL pointer is 289returned. 290.Pp 291The 292.Fn ipsec_get_policylen 293function returns a positive value, 294indicating the buffer size, 295on success, and a negative value on error. 296.Pp 297The 298.Fn ipsec_dump_policy 299function returns a pointer to a dynamically allocated region 300containing a human readable security policy on success, and 301.Dv NULL 302on error. 303.Sh EXAMPLES 304Set a policy that all inbound packets are discarded. 305.Pp 306.Dl "in discard" 307.Pp 308.\" 309All outbound packets are required to be processed by IPsec and 310transported using ESP. 311.Pp 312.Dl "out ipsec esp/transport//require" 313.Pp 314.\" 315All inbound packets are required to be authenticated using the AH protocol. 316.Pp 317.Dl "in ipsec ah/transport//require" 318.Pp 319.\" 320Tunnel packets outbound through the endpoints at 10.1.1.2 and 10.1.1.1. 321.Pp 322.Dl "out ipsec esp/tunnel/10.1.1.2-10.1.1.1/require" 323.Sh SEE ALSO 324.Xr ipsec_strerror 3 , 325.Xr ipsec 4 , 326.Xr setkey 8 327.Sh HISTORY 328These functions first appeared in WIDE/KAME IPv6 protocol stack kit. 329.Pp 330IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack 331was initially integrated into 332.Fx 4.0 . 333