Annotation of embedaddon/ipsec-tools/src/libipsec/ipsec_set_policy.3, revision 1.1
1.1 ! misho 1: .\" $NetBSD: ipsec_set_policy.3,v 1.15 2010/03/05 06:47:58 tteras Exp $
! 2: .\"
! 3: .\" $KAME: ipsec_set_policy.3,v 1.16 2003/01/06 21:59:03 sumikawa Exp $
! 4: .\"
! 5: .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project.
! 6: .\" All rights reserved.
! 7: .\"
! 8: .\" Redistribution and use in source and binary forms, with or without
! 9: .\" modification, are permitted provided that the following conditions
! 10: .\" are met:
! 11: .\" 1. Redistributions of source code must retain the above copyright
! 12: .\" notice, this list of conditions and the following disclaimer.
! 13: .\" 2. Redistributions in binary form must reproduce the above copyright
! 14: .\" notice, this list of conditions and the following disclaimer in the
! 15: .\" documentation and/or other materials provided with the distribution.
! 16: .\" 3. Neither the name of the project nor the names of its contributors
! 17: .\" may be used to endorse or promote products derived from this software
! 18: .\" without specific prior written permission.
! 19: .\"
! 20: .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
! 21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! 22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 23: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
! 24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 30: .\" SUCH DAMAGE.
! 31: .\"
! 32: .Dd May 5, 1998
! 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 manipulate IPsec policy specification structure from human-readable policy 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
! 52: .Fn ipsec_set_policy
! 53: generates an IPsec policy specification structure, namely
! 54: .Li struct sadb_x_policy
! 55: and/or
! 56: .Li struct sadb_x_ipsecrequest
! 57: from a human-readable policy specification.
! 58: The policy specification must be given as a C string
! 59: .Fa policy
! 60: and its length
! 61: .Fa len .
! 62: .Fn ipsec_set_policy
! 63: will return a buffer with the corresponding IPsec policy specification structure.
! 64: The buffer is dynamically allocated, and must be
! 65: .Xr free 3 Ap d
! 66: by the caller.
! 67: .Pp
! 68: You can get the length of the generated buffer with
! 69: .Fn ipsec_get_policylen
! 70: (i.e. for calling
! 71: .Xr setsockopt 2 ) .
! 72: .Pp
! 73: .Fn ipsec_dump_policy
! 74: converts an IPsec policy structure into human-readable form.
! 75: Therefore,
! 76: .Fn ipsec_dump_policy
! 77: can be regarded as the inverse function to
! 78: .Fn ipsec_set_policy .
! 79: .Fa buf
! 80: points to an IPsec policy structure,
! 81: .Li struct sadb_x_policy .
! 82: .Fa delim
! 83: is a delimiter string, which is usually a blank character.
! 84: If you set
! 85: .Fa delim
! 86: to
! 87: .Dv NULL ,
! 88: a single whitespace is assumed.
! 89: .Fn ipsec_dump_policy
! 90: returns a pointer to a dynamically allocated string.
! 91: It is the caller's responsibility to
! 92: .Xr free 3
! 93: it.
! 94: .Pp
! 95: .Fa policy
! 96: is formatted as either of the following:
! 97: .Bl -tag -width "discard"
! 98: .It Ar direction [priority specification] Li discard
! 99: .Ar direction
! 100: must be
! 101: .Li in ,
! 102: .Li out ,
! 103: or
! 104: .Li fwd .
! 105: .Ar direction
! 106: specifies in which direction the policy needs to be applied.
! 107: The non-standard direction
! 108: .Li fwd
! 109: is substituted with
! 110: .Li in
! 111: on platforms which do not support forward policies.
! 112: .Pp
! 113: .Ar priority specification
! 114: is used to control the placement of the policy within the SPD.
! 115: The policy position is determined by
! 116: a signed integer where higher priorities indicate the policy is placed
! 117: closer to the beginning of the list and lower priorities indicate the
! 118: policy is placed closer to the end of the list.
! 119: Policies with equal
! 120: priorities are added at the end of the group of such policies.
! 121: .Pp
! 122: Priority can only
! 123: be specified when libipsec has been compiled against kernel headers that
! 124: support policy priorities (Linux \*[Gt]= 2.6.6).
! 125: It takes one of the following formats:
! 126: .Bl -tag -width "discard"
! 127: .It Ar {priority,prio} offset
! 128: .Ar offset
! 129: is an integer in the range \-2147483647..214783648.
! 130: .It Ar {priority,prio} base {+,-} offset
! 131: .Ar base
! 132: is either
! 133: .Li low (-1073741824) ,
! 134: .Li def (0) ,
! 135: or
! 136: .Li high (1073741824) .
! 137: .Pp
! 138: .Ar offset
! 139: is an unsigned integer.
! 140: It can be up to 1073741824 for
! 141: positive offsets, and up to 1073741823 for negative offsets.
! 142: .El
! 143: .Pp
! 144: The interpretation of policy priority in these functions and the
! 145: kernel DOES differ.
! 146: The relationship between the two can be described as
! 147: p(kernel) = 0x80000000 - p(func)
! 148: .Pp
! 149: With
! 150: .Li discard
! 151: policy, packets will be dropped if they match the policy.
! 152: .It Ar direction [priority specification] Li entrust
! 153: .Li entrust
! 154: means to consult the SPD defined by
! 155: .Xr setkey 8 .
! 156: .It Ar direction [priority specification] Li bypass
! 157: .Li bypass
! 158: means to bypass the IPsec processing.
! 159: .Pq the packet will be transmitted in clear .
! 160: This is for privileged sockets.
! 161: .It Ar direction Bo Ar priority specification Bc Li ipsec Ar request ...
! 162: .Li ipsec
! 163: means that the matching packets are subject to IPsec processing.
! 164: .Li ipsec
! 165: can be followed by one or more
! 166: .Ar request
! 167: strings, which are formatted as below:
! 168: .Bl -tag -width "discard"
! 169: .It Ar protocol Li / Ar mode Li / Ar src Li - Ar dst Op Ar /level
! 170: .Ar protocol
! 171: is either
! 172: .Li ah ,
! 173: .Li esp ,
! 174: or
! 175: .Li ipcomp .
! 176: .Pp
! 177: .Ar mode
! 178: is either
! 179: .Li transport
! 180: or
! 181: .Li tunnel .
! 182: .Pp
! 183: .Ar src
! 184: and
! 185: .Ar dst
! 186: specifies the IPsec endpoint.
! 187: .Ar src
! 188: always means the
! 189: .Dq sending node
! 190: and
! 191: .Ar dst
! 192: always means the
! 193: .Dq receiving node .
! 194: Therefore, when
! 195: .Ar direction
! 196: is
! 197: .Li in ,
! 198: .Ar dst
! 199: is this node
! 200: and
! 201: .Ar src
! 202: is the other node
! 203: .Pq peer .
! 204: If
! 205: .Ar mode
! 206: is
! 207: .Li transport ,
! 208: Both
! 209: .Ar src
! 210: and
! 211: .Ar dst
! 212: can be omitted.
! 213: .Pp
! 214: .Ar level
! 215: must be set to one of the following:
! 216: .Li default , use , require ,
! 217: or
! 218: .Li unique .
! 219: .Li default
! 220: means that the kernel should consult the system default policy
! 221: defined by
! 222: .Xr sysctl 8 ,
! 223: such as
! 224: .Li net.inet.ipsec.esp_trans_deflev .
! 225: See
! 226: .Xr ipsec 4
! 227: regarding the system default.
! 228: .Li use
! 229: means that a relevant SA can be used when available,
! 230: since the kernel may perform IPsec operation against packets when possible.
! 231: In this case, packets can be transmitted in clear
! 232: .Pq when SA is not available ,
! 233: or encrypted
! 234: .Pq when SA is available .
! 235: .Li require
! 236: means that a relevant SA is required,
! 237: since the kernel must perform IPsec operation against packets.
! 238: .Li unique
! 239: is the same as
! 240: .Li require ,
! 241: but adds the restriction that the SA for outbound traffic is used
! 242: only for this policy.
! 243: You may need the identifier in order to relate the policy and the SA
! 244: when you define the SA by manual keying.
! 245: You can put the decimal number as the identifier after
! 246: .Li unique
! 247: like
! 248: .Li unique : number .
! 249: .Li number
! 250: must be between 1 and 32767 .
! 251: If the
! 252: .Ar request
! 253: string is kept unambiguous,
! 254: .Ar level
! 255: and slash prior to
! 256: .Ar level
! 257: can be omitted.
! 258: However, it is encouraged to specify them explicitly
! 259: to avoid unintended behavior.
! 260: If
! 261: .Ar level
! 262: is omitted, it will be interpreted as
! 263: .Li default .
! 264: .El
! 265: .Pp
! 266: Note that there are slight differences to the specification of
! 267: .Xr setkey 8 .
! 268: In the specification of
! 269: .Xr setkey 8 ,
! 270: both
! 271: .Li entrust
! 272: and
! 273: .Li bypass
! 274: are not used.
! 275: Refer to
! 276: .Xr setkey 8
! 277: for details.
! 278: .Pp
! 279: Here are several examples
! 280: .Pq long lines are wrapped for readability :
! 281: .Bd -literal -offset indent
! 282: in discard
! 283: out ipsec esp/transport//require
! 284: in ipsec ah/transport//require
! 285: out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use
! 286: in ipsec ipcomp/transport//use
! 287: esp/transport//use
! 288: .Ed
! 289: .El
! 290: .Sh RETURN VALUES
! 291: .Fn ipsec_set_policy
! 292: returns a pointer to the allocated buffer with the policy specification
! 293: if successful; otherwise a
! 294: .Dv NULL
! 295: pointer is returned.
! 296: .Fn ipsec_get_policylen
! 297: returns a positive value
! 298: .Pq meaning the buffer size
! 299: on success, and a negative value on errors.
! 300: .Fn ipsec_dump_policy
! 301: returns a pointer to a dynamically allocated region on success,
! 302: and
! 303: .Dv NULL
! 304: on errors.
! 305: .Sh SEE ALSO
! 306: .Xr ipsec_strerror 3 ,
! 307: .Xr ipsec 4 ,
! 308: .Xr setkey 8
! 309: .Sh HISTORY
! 310: The functions first appeared in the WIDE/KAME IPv6 protocol stack kit.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to ipsec_set_policy.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / ipsec-tools / src / libipsec