NAME
ipsec_set_policy,
ipsec_get_policylen,
ipsec_dump_policy —
manipulate IPsec
policy specification structure from human-readable policy string
LIBRARY
IPsec Policy Control Library (libipsec, -lipsec)
SYNOPSIS
#include <netipsec/ipsec.h>
char *
ipsec_set_policy(
const
char *policy,
int
len);
int
ipsec_get_policylen(
char
*buf);
char *
ipsec_dump_policy(
char
*buf,
const char
*delim);
DESCRIPTION
ipsec_set_policy() generates an IPsec policy specification
structure, namely
struct sadb_x_policy
and/or
struct sadb_x_ipsecrequest
from a human-readable
policy specification. The policy specification must be given as a C string
policy and its length
len.
ipsec_set_policy() will return a buffer with the
corresponding IPsec policy specification structure. The buffer is dynamically
allocated, and must be
free(3)'d
by the caller.
You can get the length of the generated buffer with
ipsec_get_policylen() (i.e. for calling
setsockopt(2)).
ipsec_dump_policy() converts an IPsec policy structure into
human-readable form. Therefore,
ipsec_dump_policy() can be
regarded as the inverse function to
ipsec_set_policy().
buf points to an IPsec policy structure,
struct sadb_x_policy
.
delim is a
delimiter string, which is usually a blank character. If you set
delim to
NULL
, a single
whitespace is assumed.
ipsec_dump_policy() returns a pointer
to a dynamically allocated string. It is the caller's responsibility to
free(3) it.
policy is formatted as either of the following:
-
-
- direction
[priority specification]
discard
- direction must be
in
, out
, or
fwd
. direction specifies in
which direction the policy needs to be applied. The non-standard direction
fwd
is substituted with in
on platforms which do not support forward policies.
priority specification is used to control the
placement of the policy within the SPD. The policy position is determined
by a signed integer where higher priorities indicate the policy is placed
closer to the beginning of the list and lower priorities indicate the
policy is placed closer to the end of the list. Policies with equal
priorities are added at the end of the group of such policies.
Priority can only be specified when libipsec has been compiled against
kernel headers that support policy priorities (Linux >= 2.6.6). It
takes one of the following formats:
-
-
- {priority,prio}
offset
- offset is an integer in the range
-2147483647..214783648.
-
-
- {priority,prio}
base {+,-} offset
- base is either
low (-1073741824)
, def
(0)
, or high (1073741824)
.
offset is an unsigned integer. It can be up to
1073741824 for positive offsets, and up to 1073741823 for negative
offsets.
The interpretation of policy priority in these functions and the kernel DOES
differ. The relationship between the two can be described as p(kernel) =
0x80000000 - p(func)
With discard
policy, packets will be dropped if they
match the policy.
-
-
- direction
[priority specification]
entrust
entrust
means to consult the SPD
defined by setkey(8).
-
-
- direction
[priority specification]
bypass
bypass
means to bypass the IPsec
processing. (the packet will be transmitted in clear). This is for
privileged sockets.
-
-
- direction
[priority specification]
ipsec
request ...
ipsec
means that the matching
packets are subject to IPsec processing. ipsec
can
be followed by one or more request strings, which
are formatted as below:
-
-
- protocol
/
mode
/
src
-
dst
[/level]
- protocol is either
ah
, esp
, or
ipcomp
.
mode is either transport
or tunnel
.
src and dst specifies the
IPsec endpoint. src always means the
“sending node” and dst always means
the “receiving node”. Therefore, when
direction is in
,
dst is this node and src
is the other node (peer). If mode is
transport
, Both src and
dst can be omitted.
level must be set to one of the following:
default
, use
,
require
, or unique
.
default
means that the kernel should consult
the system default policy defined by
sysctl(8), such as
net.inet.ipsec.esp_trans_deflev
. See
ipsec(4) regarding the
system default. 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). require
means that a relevant
SA is required, since the kernel must perform IPsec operation against
packets. unique
is the same as
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 unique
like
unique
: number
.
number
must be between 1 and 32767 . If the
request string is kept unambiguous,
level and slash prior to
level can be omitted. However, it is encouraged
to specify them explicitly to avoid unintended behavior. If
level is omitted, it will be interpreted as
default
.
Note that there are slight differences to the specification of
setkey(8). In the
specification of setkey(8),
both entrust
and bypass
are not used. Refer to
setkey(8) for details.
Here are several examples (long lines are wrapped for readability):
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
RETURN VALUES
ipsec_set_policy() returns a pointer to the allocated buffer
with the policy specification if successful; otherwise a
NULL
pointer is returned.
ipsec_get_policylen() returns a positive value (meaning the
buffer size) on success, and a negative value on errors.
ipsec_dump_policy() returns a pointer to a dynamically
allocated region on success, and
NULL
on errors.
SEE ALSO
ipsec_strerror(3),
ipsec(4),
setkey(8)
HISTORY
The functions first appeared in the WIDE/KAME IPv6 protocol stack kit.