1 files changed, 253 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..559d5fa
--- /dev/null
+++ b/lib/libipsec/ipsec_set_policy.3
@@ -0,0 +1,253 @@
+.\" 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.
+.\"
+.\"     $Id: ipsec_set_policy.3,v 1.5 1999/10/20 00:21:06 sakane Exp $
+.\"     $FreeBSD$
+.\"
+.Dd May 5, 1998
+.Dt IPSEC_SET_POLICY 3
+.Os KAME
+.\"
+.Sh NAME
+.Nm ipsec_set_policy ,
+.Nm ipsec_get_policylen ,
+.Nm ipsec_dump_policy
+.Nd manipulate IPsec policy specification structure from readable string
+.\"
+.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.
+.Po
+packet will be transmitted in clear
+.Pc .
+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
+or
+.Li require .
+.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.
+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
+in ipsec esp/transport/10.1.1.2-10.1.1.1/use
+        ah/tunnel/10.1.1.2-10.1.1.1/require
+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.
+.\"
+.\" .Sh BUGS
+.\" (to be written)