freebsd-skq/lib/libipsec/ipsec_set_policy.3

.\"	$KAME: ipsec_set_policy.3,v 1.15 2001/08/17 07:21:36 itojun Exp $
.\"
.\" 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.
.\"
.\" $FreeBSD$
.\"
.Dd February 14, 2006
.Dt IPSEC_SET_POLICY 3
.Os
.Sh NAME
.Nm ipsec_set_policy ,
.Nm ipsec_get_policylen ,
.Nm ipsec_dump_policy
.Nd create an IPsec policy structure from a human 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
The
.Fn ipsec_set_policy
function generates an IPsec policy specification structure, 
.Li struct sadb_x_policy
and/or
.Li struct sadb_x_ipsecrequest
from a human-readable policy specification.
The policy specification must be given as a C string, 
passed in the 
.Fa policy
argument and the length of the string, given as
.Fa len .
The
.Fn ipsec_set_policy
function returns pointer to a buffer which contains a properly formed
IPsec policy specification structure.
The buffer is dynamically allocated, and must be freed by using the
.Xr free 3 
library function.
.Pp
The
.Fn ipsec_get_policylen
function will returns the of the buffer which is needed when passing
the specification structure to the
.Xr setsockopt 2
system call.
.Pp
The
.Fn ipsec_dump_policy
function converts an IPsec policy structure into a human readable form.
The
.Fa buf
argument points to an 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 ,
a single white space is assumed.
The
.Fn ipsec_dump_policy
function returns a pointer to dynamically allocated string.
It is the caller's responsibility to free the returned pointer using the
.Xr free 3 
library call.
.Pp
A 
.Fa policy
is given in the following way:
.Bl -tag  -width "discard"
.It Ar direction Li discard
The
.Ar direction
must be
.Li in
or
.Li out
and 
specifies which direction the policy needs to be applied, either on
inbound or outbound packets.
When the
.Li discard
policy is selected, packets will be dropped if they match the policy.
.It Ar direction Li entrust
.Li entrust
means to consult the security policy database
(SPD)
in the kernel, as controlled by
.Xr setkey 8 .
.It Ar direction Li bypass
A direction of 
.Li bypass
indicates that IPsec processing should not occur and that the
packet will be transmitted in clear.  The bypass option is only
available to privileged sockets.
.It Xo
.Ar direction
.Li ipsec
.Ar request ...
.Xc
A direction of
.Li ipsec
means that matching packets are processed by IPsec.
.Li ipsec
can be followed by one or more
.Ar request
string, which is formatted as:
.Bl -tag  -width "discard"
.It Xo
.Ar protocol
.Li /
.Ar mode
.Li /
.Ar src
.Li -
.Ar dst
.Op Ar /level
.Xc
The
.Ar protocol
is one of:
.Li ah ,
.Li esp
or
.Li ipcomp
indicating Authentication Header, Encapsulating Security Protocol or
IP Compression protocol is used.
.Pp
The
.Ar mode
is either
.Li transport
or
.Li tunnel 
the meanings of both modes are described in 
.Xr ipsec 4 .
.Pp
The
.Ar src
and
.Ar dst
specify the IP address, either v4 or v6, of the source and destination systems.
The
.Ar src
always stands for the
.Dq sending node
and
.Ar dst
always stands for the
.Dq receiving node .
When
.Ar direction
is
.Li in ,
.Ar dst
is this local node
and
.Ar src
is the remote node or peer.
If
.Ar mode
is
.Li transport ,
both
.Ar src
and
.Ar dst
can be omitted.
.Pp
The
.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 default security policies as
defined by a set of
.Xr sysctl 8 ,
variables.  The relevant
.Xr sysctl 8 
variables are described in 
.Xr ipsec 4 .
.Pp
When
.Li use
is selected a relevant security association
(SA)
can be used when available but is not necessary.
If the SA is available then packets will be handled by IPsec,
i.e. encrypted and/or authenticated but if an SA is not available then
packets will be transmitted in the clear.  The
.Li use
option is not recommended because it allows for accidental
mis-configurations where encrypted or authenticated link becomes
unencrypted or unauthenticated, the
.Li require
keyword is recommended instead of
.Li use 
where possible.
Using the
.Li require
keyword means that a relevant SA is required,
and that the kernel must perform IPsec processing on all matching
packets.
.Pp
The
.Li unique
keyword has the same effect 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 using
.Xr setkey 8 .
Put the decimal number as the identifier after the
.Li unique
keyword in this way:
.Li unique : number ,
where 
.Li number
must be between 1 and 32767.
.Pp
If the
.Ar request
string is kept unambiguous,
.Ar level
and the slash prior to
.Ar level
can be omitted but you are 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 difference between the specification allowed here
and in 
.Xr setkey 8 .
When specifying security policies with
.Xr setkey 8 ,
neither entrust nor bypass are used.
Refer to
.Xr setkey 8
for details.
.Sh EXAMPLES
Set a policy that all inbound packets are discarded.
.Bd -literal -offset indent
in discard

.Ed
.\"
All outbound packets are required to be processed by IPsec and
transported using ESP.
.Bd -literal -offset indent
out ipsec esp/transport//require

.Ed
.\"
All inbound packets are required to be authenticated using the AH protocol.
.Bd -literal -offset indent
in ipsec ah/transport//require

.Ed
.\"
Tunnel packets outbound through the endpoints at 10.1.1.2 and 10.1.1.1.
.Bd -literal -offset indent
out ipsec esp/tunnel/10.1.1.2-10.1.1.1/require

.Ed
.\"
.Sh RETURN VALUES
The
.Fn ipsec_set_policy
function returns a pointer to the allocated buffer containing a the
policy specification if successful; otherwise a NULL pointer is
returned.  
.Pp
The
.Fn ipsec_get_policylen
function returns a positive value, 
indicating the buffer size,
on success, and a negative value on error.
.Pp
The
.Fn ipsec_dump_policy
function returns a pointer to a dynamically allocated region
containing a human readable security policy on success, and
.Dv NULL
on error.
.Sh SEE ALSO
.Xr ipsec_strerror 3 ,
.Xr ipsec 4 ,
.Xr setkey 8
.Sh HISTORY
These 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