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