1.\" $KAME: ipsec_set_policy.3,v 1.16 2003/01/06 21:59:03 sumikawa Exp $ 2.\" $FreeBSD$ 3.\" 4.\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the project nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd May 5, 1998 32.Dt IPSEC_SET_POLICY 3 33.Os 34.Sh NAME 35.Nm ipsec_set_policy , 36.Nm ipsec_get_policylen , 37.Nm ipsec_dump_policy 38.Nd manipulate IPsec policy specification structure from readable string 39.\" 40.Sh LIBRARY 41.Lb libipsec 42.Sh SYNOPSIS 43.In netinet6/ipsec.h 44.Ft "char *" 45.Fn ipsec_set_policy "char *policy" "int len" 46.Ft int 47.Fn ipsec_get_policylen "char *buf" 48.Ft "char *" 49.Fn ipsec_dump_policy "char *buf" "char *delim" 50.Sh DESCRIPTION 51The 52.Fn ipsec_set_policy 53function generates IPsec policy specification structure, namely 54.Li struct sadb_x_policy 55and/or 56.Li struct sadb_x_ipsecrequest 57from human-readable policy specification. 58Policy specification must be given as C string 59.Fa policy 60and length 61.Fa len 62of 63.Fa policy . 64The 65.Fn ipsec_set_policy 66function will return the buffer of IPsec policy specification structure. 67The buffer is dynamically allocated, and must be freed by the caller by calling 68.Xr free 3 . 69.Pp 70You may want the length of the generated buffer such when calling 71.Xr setsockopt 2 . 72The 73.Fn ipsec_get_policylen 74function will return the length. 75.Pp 76The 77.Fn ipsec_dump_policy 78function converts IPsec policy structure into readable form. 79Therefore, 80.Fn ipsec_dump_policy 81can be regarded as inverse conversion of 82.Fn ipsec_set_policy . 83.Fa buf 84points 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 , 92single whitespace is assumed. 93The 94.Fn ipsec_dump_policy 95function returns a pointer to dynamically allocated string. 96It is caller's responsibility to reclaim the region, by using 97.Xr free 3 . 98.Pp 99.Fa policy 100is formatted as either of the following: 101.Bl -tag -width "discard" 102.It Ar direction Li discard 103.Ar direction 104must be 105.Li in 106or 107.Li out . 108.Ar direction 109specifies which direction the policy needs to be applied. 110With 111.Li discard 112policy, packets will be dropped if they match the policy. 113.It Ar direction Li entrust 114.Li entrust 115means to consult to SPD defined by 116.Xr setkey 8 . 117.It Ar direction Li bypass 118.Li bypass 119means to be bypassed the IPsec processing. 120.Pq packet will be transmitted in clear . 121This is for privileged socket. 122.It Xo 123.Ar direction 124.Li ipsec 125.Ar request ... 126.Xc 127.Li ipsec 128means that the matching packets are subject to IPsec processing. 129.Li ipsec 130can be followed by one or more 131.Ar request 132string, which is formatted as below: 133.Bl -tag -width "discard" 134.It Xo 135.Ar protocol 136.Li / 137.Ar mode 138.Li / 139.Ar src 140.Li - 141.Ar dst 142.Op Ar /level 143.Xc 144.Ar protocol 145is either 146.Li ah , 147.Li esp 148or 149.Li ipcomp . 150.Pp 151.Ar mode 152is either 153.Li transport 154or 155.Li tunnel . 156.Pp 157.Ar src 158and 159.Ar dst 160specifies IPsec endpoint. 161.Ar src 162always means 163.Dq sending node 164and 165.Ar dst 166always means 167.Dq receiving node . 168Therefore, when 169.Ar direction 170is 171.Li in , 172.Ar dst 173is this node 174and 175.Ar src 176is the other node 177.Pq peer . 178If 179.Ar mode 180is 181.Li transport , 182Both 183.Ar src 184and 185.Ar dst 186can be omitted. 187.Pp 188.Ar level 189must be set to one of the following: 190.Li default , use , require 191or 192.Li unique . 193.Li default 194means that the kernel should consult the system default policy 195defined by 196.Xr sysctl 8 , 197such as 198.Li net.inet.ipsec.esp_trans_deflev . 199See 200.Xr ipsec 4 201regarding the system default. 202.Li use 203means that a relevant SA can be used when available, 204since the kernel may perform IPsec operation against packets when possible. 205In this case, packets can be transmitted in clear 206.Pq when SA is not available , 207or encrypted 208.Pq when SA is available . 209.Li require 210means that a relevant SA is required, 211since the kernel must perform IPsec operation against packets. 212.Li unique 213is the same as 214.Li require , 215but adds the restriction that the SA for outbound traffic is used 216only for this policy. 217You may need the identifier in order to relate the policy and the SA 218when you define the SA by manual keying. 219You can put the decimal number as the identifier after 220.Li unique 221like 222.Li unique : number . 223.Li number 224must be between 1 and 32767 . 225If the 226.Ar request 227string is kept unambiguous, 228.Ar level 229and slash prior to 230.Ar level 231can be omitted. 232However, it is encouraged to specify them explicitly 233to avoid unintended behaviors. 234If 235.Ar level 236is omitted, it will be interpreted as 237.Li default . 238.El 239.El 240.Pp 241Note that there is a bit difference of specification from 242.Xr setkey 8 . 243In specification by 244.Xr setkey 8 , 245both entrust and bypass are not used. 246Refer to 247.Xr setkey 8 248for detail. 249.Pp 250Here are several examples 251.Pq long lines are wrapped for readability : 252.Bd -literal -offset indent 253in discard 254out ipsec esp/transport//require 255in ipsec ah/transport//require 256out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use 257in ipsec ipcomp/transport//use 258 esp/transport//use 259.Ed 260.Sh RETURN VALUES 261The 262.Fn ipsec_set_policy 263function returns a pointer to the allocated buffer of policy specification if 264successful; otherwise a NULL pointer is returned. 265The 266.Fn ipsec_get_policylen 267function returns with positive value 268.Pq meaning the buffer size 269on success, and negative value on errors. 270The 271.Fn ipsec_dump_policy 272function returns a pointer to dynamically allocated region on success, 273and 274.Dv NULL 275on errors. 276.Sh SEE ALSO 277.Xr ipsec_strerror 3 , 278.Xr ipsec 4 , 279.Xr setkey 8 280.Sh HISTORY 281The functions first appeared in WIDE/KAME IPv6 protocol stack kit. 282.Pp 283IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack 284was initially integrated into 285.Fx 4.0 286