diff options
Diffstat (limited to 'lib/libipsec/ipsec_set_policy.3')
| -rw-r--r-- | lib/libipsec/ipsec_set_policy.3 | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/lib/libipsec/ipsec_set_policy.3 b/lib/libipsec/ipsec_set_policy.3 new file mode 100644 index 0000000..cc7424e --- /dev/null +++ b/lib/libipsec/ipsec_set_policy.3 @@ -0,0 +1,274 @@ +.\" $KAME: ipsec_set_policy.3,v 1.14 2001/04/06 07:00:46 itojun Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 5, 1998 +.Dt IPSEC_SET_POLICY 3 +.Os +.Sh NAME +.Nm ipsec_set_policy , +.Nm ipsec_get_policylen , +.Nm ipsec_dump_policy +.Nd manipulate IPsec policy specification structure from readable string +.\" +.Sh LIBRARY +.Lb libipsec +.Sh SYNOPSIS +.In netinet6/ipsec.h +.Ft "char *" +.Fn ipsec_set_policy "char *policy" "int len" +.Ft int +.Fn ipsec_get_policylen "char *buf" +.Ft "char *" +.Fn ipsec_dump_policy "char *buf" "char *delim" +.Sh DESCRIPTION +.Fn ipsec_set_policy +generates IPsec policy specification structure, namely +.Li struct sadb_x_policy +and/or +.Li struct sadb_x_ipsecrequest +from human-readable policy specification. +Policy specification must be given as C string +.Fa policy +and length +.Fa len +of +.Fa policy . +.Fn ipsec_set_policy +will return the buffer of IPsec policy specification structure. +.Pp +You may want the length of the generated buffer such when calling +.Xr setsockopt 2 . +.Fn ipsec_get_policylen +will return the length. +.Pp +.Fn ipsec_dump_policy +converts IPsec policy structure into readable form. +Therefore, +.Fn ipsec_dump_policy +can be regarded as inverse conversion of +.Fn ipsec_set_policy . +.Fa buf +points to a IPsec policy structure, +.Li struct sadb_x_policy . +.Fa delim +is a delimiter string, which is usually a blank character. +If you set +.Fa delim +to +.Dv NULL , +single whitespace is assumed. +.Fn ipsec_dump_policy +returns pointer to dynamically allocated string. +It is caller's responsibility to reclaim the region, by using +.Xr free 3 . +.Pp +.Fa policy +is formatted as either of the following: +.Bl -tag -width "discard" +.It Ar direction Li discard +.Ar direction +must be +.Li in +or +.Li out . +.Ar direction +specifies which direction the policy needs to be applied. +With +.Li discard +policy, packets will be dropped if they match the policy. +.It Ar direction Li entrust +.Li entrust +means to consult to SPD defined by +.Xr setkey 8 . +.It Ar direction Li bypass +.Li bypass +means to be bypassed the IPsec processing. +(packet will be transmitted in clear). +This is for privileged socket. +.It Xo +.Ar direction +.Li ipsec +.Ar request ... +.Xc +.Li ipsec +means that the matching packets are subject to IPsec processing. +.Li ipsec +can be followed by one or more +.Ar request +string, which is formatted as below: +.Bl -tag -width "discard" +.It Xo +.Ar protocol +.Li / +.Ar mode +.Li / +.Ar src +.Li - +.Ar dst +.Op Ar /level +.Xc +.Ar protocol +is either +.Li ah , +.Li esp +or +.Li ipcomp . +.Pp +.Ar mode +is either +.Li transport +or +.Li tunnel . +.Pp +.Ar src +and +.Ar dst +specifies IPsec endpoint. +.Ar src +always means +.Dq sending node +and +.Ar dst +always means +.Dq receiving node . +Therefore, when +.Ar direction +is +.Li in , +.Ar dst +is this node +and +.Ar src +is the other node +(peer). +If +.Ar mode +is +.Li transport , +Both +.Ar src +and +.Ar dst +can be omited. +.Pp +.Ar level +must be set to one of the following: +.Li default , use , require +or +.Li unique . +.Li default +means that the kernel should consult the system default policy +defined by +.Xr sysctl 8 , +such as +.Li net.inet.ipsec.esp_trans_deflev . +See +.Xr ipsec 4 +regarding the system default. +.Li use +means that a relevant SA can be used when available, +since the kernel may perform IPsec operation against packets when possible. +In this case, packets can be transmitted in clear +(when SA is not available), +or encrypted +(when SA is available). +.Li require +means that a relevant SA is required, +since the kernel must perform IPsec operation against packets. +.Li unique +is the same as +.Li require , +but adds the restriction that the SA for outbound traffic is used +only for this policy. +You may need the identifier in order to relate the policy and the SA +when you define the SA by manual keying. +You can put the decimal number as the identifier after +.Li unique +like +.Li unique : number . +.Li number +must be between 1 and 32767 . +If the +.Ar request +string is kept unambiguous, +.Ar level +and slash prior to +.Ar level +can be omitted. +However, it is encouraged to specify them explicitly +to avoid unintended behaviors. +If +.Ar level +is omitted, it will be interpreted as +.Li default . +.El +.El +.Pp +Note that there is a bit difference of specification from +.Xr setkey 8 . +In specification by +.Xr setkey 8 , +both entrust and bypass are not used. +Refer to +.Xr setkey 8 +for detail. +.Pp +Here are several examples +(long lines are wrapped for readability): +.Bd -literal -offset indent +in discard +out ipsec esp/transport//require +in ipsec ah/transport//require +out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use +in ipsec ipcomp/transport//use + esp/transport//use +.Ed +.Sh RETURN VALUES +.Fn ipsec_set_policy +returns a pointer to the allocated buffer of policy specification if successful; otherwise a NULL pointer is returned. +.Fn ipsec_get_policylen +returns with positive value +(meaning the buffer size) +on success, and negative value on errors. +.Fn ipsec_dump_policy +returns a pointer to dynamically allocated region on success, +and +.Dv NULL +on errors. +.Sh SEE ALSO +.Xr ipsec_strerror 3 , +.Xr ipsec 4 , +.Xr setkey 8 +.Sh HISTORY +The functions first appeared in WIDE/KAME IPv6 protocol stack kit. +.Pp +IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack +was initially integrated into +.Fx 4.0 |
