3c62e87aa3
behavior change: policy syntax was changed. you may need to update your setkey(8) configuration files.
258 lines
6.5 KiB
Groff
258 lines
6.5 KiB
Groff
.\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project.
|
|
.\" $FreeBSD$
|
|
.\" $KAME: ipsec_set_policy.3,v 1.10 2000/05/07 05:25:03 itojun Exp $
|
|
.\"
|
|
.\" 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
|
|
.Fd #include <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 entrust
|
|
.Ar direction
|
|
must be
|
|
.Li in
|
|
or
|
|
.Li out .
|
|
.Ar direction
|
|
specifies which direction the policy needs to be applied.
|
|
.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.
|
|
.Pq 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
|
|
.Pq peer .
|
|
.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
|
|
.Pq when SA is not available ,
|
|
or encrypted
|
|
.Pq 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
|
|
.Pq long lines are wrapped for readability :
|
|
.Bd -literal -offset indent
|
|
in discard
|
|
out ipsec esp/transport/10.1.1.1-10.1.1.2/require
|
|
in ipsec ah/transport/10.1.1.2-10.1.1.1/require
|
|
out ipsec esp/transport/10.1.1.2-10.1.1.1/use
|
|
ah/tunnel/10.1.1.2-10.1.1.1/unique:1000
|
|
in ipsec ipcomp/transport/10.1.1.2-10.1.1.1/use
|
|
esp/transport/10.1.1.2-10.1.1.1/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
|
|
.Pq 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 ispec 4 ,
|
|
.Xr setkey 8
|
|
.Sh HISTORY
|
|
The functions first appeared in WIDE/KAME IPv6 protocol stack kit.
|