Clean up some descriptions and remove ambiguities in the language.
Add explanations to the examples. MFC after: 1 week
This commit is contained in:
George V. Neville-Neil
parent
42a64e5369
commit
108b9d8319
@ -29,14 +29,14 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd May 5, 1998
|
||||
.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 manipulate IPsec policy specification structure from readable string
|
||||
.Nd create an IPsec policy structure from a human readable string
|
||||
.\"
|
||||
.Sh LIBRARY
|
||||
.Lb libipsec
|
||||
@ -51,38 +51,37 @@
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn ipsec_set_policy
|
||||
function generates IPsec policy specification structure, namely
|
||||
function generates an IPsec policy specification structure,
|
||||
.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
|
||||
from a human-readable policy specification.
|
||||
The policy specification must be given as a C string,
|
||||
passed in the
|
||||
.Fa policy
|
||||
and length
|
||||
.Fa len
|
||||
of
|
||||
.Fa policy .
|
||||
argument and the length of the string, given as
|
||||
.Fa len .
|
||||
The
|
||||
.Fn ipsec_set_policy
|
||||
function will return the buffer of IPsec policy specification structure.
|
||||
The buffer is dynamically allocated, and must be freed by the caller by calling
|
||||
.Xr free 3 .
|
||||
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
|
||||
You may want the length of the generated buffer such when calling
|
||||
.Xr setsockopt 2 .
|
||||
The
|
||||
.Fn ipsec_get_policylen
|
||||
function will return the length.
|
||||
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 IPsec policy structure into readable form.
|
||||
Therefore,
|
||||
.Fn ipsec_dump_policy
|
||||
can be regarded as inverse conversion of
|
||||
.Fn ipsec_set_policy .
|
||||
function converts an IPsec policy structure into a human readable form.
|
||||
The
|
||||
.Fa buf
|
||||
points to an IPsec policy structure,
|
||||
argument points to an IPsec policy structure,
|
||||
.Li struct sadb_x_policy .
|
||||
.Fa delim
|
||||
is a delimiter string, which is usually a blank character.
|
||||
@ -90,47 +89,55 @@ If you set
|
||||
.Fa delim
|
||||
to
|
||||
.Dv NULL ,
|
||||
single whitespace is assumed.
|
||||
a single white space is assumed.
|
||||
The
|
||||
.Fn ipsec_dump_policy
|
||||
function returns a pointer to dynamically allocated string.
|
||||
It is caller's responsibility to reclaim the region, by using
|
||||
.Xr free 3 .
|
||||
It is the caller's responsibility to free the returned pointer using the
|
||||
.Xr free 3
|
||||
library call.
|
||||
.Pp
|
||||
A
|
||||
.Fa policy
|
||||
is formatted as either of the following:
|
||||
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 .
|
||||
.Ar direction
|
||||
specifies which direction the policy needs to be applied.
|
||||
With
|
||||
.Li out
|
||||
and
|
||||
specifies which direction the policy needs to be applied, either on
|
||||
inbound or outbound packets.
|
||||
When the
|
||||
.Li discard
|
||||
policy, packets will be dropped if they match the policy.
|
||||
policy is selected, packets will be dropped if they match the policy.
|
||||
.It Ar direction Li entrust
|
||||
.Li entrust
|
||||
means to consult to SPD defined by
|
||||
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
|
||||
means to be bypassed the IPsec processing.
|
||||
(packet will be transmitted in clear).
|
||||
This is for privileged socket.
|
||||
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 the matching packets are subject to IPsec processing.
|
||||
means that matching packets are processed by IPsec.
|
||||
.Li ipsec
|
||||
can be followed by one or more
|
||||
.Ar request
|
||||
string, which is formatted as below:
|
||||
string, which is formatted as:
|
||||
.Bl -tag -width "discard"
|
||||
.It Xo
|
||||
.Ar protocol
|
||||
@ -142,95 +149,118 @@ string, which is formatted as below:
|
||||
.Ar dst
|
||||
.Op Ar /level
|
||||
.Xc
|
||||
The
|
||||
.Ar protocol
|
||||
is either
|
||||
is one of:
|
||||
.Li ah ,
|
||||
.Li esp
|
||||
or
|
||||
.Li ipcomp .
|
||||
.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 .
|
||||
.Li tunnel
|
||||
the meanings of both modes are described in
|
||||
.Xr ipsec 4 .
|
||||
.Pp
|
||||
The
|
||||
.Ar src
|
||||
and
|
||||
.Ar dst
|
||||
specifies IPsec endpoint.
|
||||
specify the IP address, either v4 or v6, of the source and destination systems.
|
||||
The
|
||||
.Ar src
|
||||
always means
|
||||
always stands for the
|
||||
.Dq sending node
|
||||
and
|
||||
.Ar dst
|
||||
always means
|
||||
always stands for the
|
||||
.Dq receiving node .
|
||||
Therefore, when
|
||||
When
|
||||
.Ar direction
|
||||
is
|
||||
.Li in ,
|
||||
.Ar dst
|
||||
is this node
|
||||
is this local node
|
||||
and
|
||||
.Ar src
|
||||
is the other node
|
||||
(peer).
|
||||
is the remote node or peer.
|
||||
If
|
||||
.Ar mode
|
||||
is
|
||||
.Li transport ,
|
||||
Both
|
||||
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 system default policy
|
||||
defined by
|
||||
means that the kernel should consult the default security policies as
|
||||
defined by a set of
|
||||
.Xr sysctl 8 ,
|
||||
such as
|
||||
.Li net.inet.ipsec.esp_trans_deflev .
|
||||
See
|
||||
.Xr ipsec 4
|
||||
regarding the system default.
|
||||
variables. The relevant
|
||||
.Xr sysctl 8
|
||||
variables are described in
|
||||
.Xr ipsec 4 .
|
||||
.Pp
|
||||
When
|
||||
.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).
|
||||
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
|
||||
means that a relevant SA is required,
|
||||
since the kernel must perform IPsec operation against packets.
|
||||
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
|
||||
is the same as
|
||||
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.
|
||||
You can put the decimal number as the identifier after
|
||||
when you define the SA by manual keying using
|
||||
.Xr setkey 8 .
|
||||
Put the decimal number as the identifier after the
|
||||
.Li unique
|
||||
like
|
||||
.Li unique : number .
|
||||
keyword in this way:
|
||||
.Li unique : number ,
|
||||
where
|
||||
.Li number
|
||||
must be between 1 and 32767 .
|
||||
must be between 1 and 32767.
|
||||
.Pp
|
||||
If the
|
||||
.Ar request
|
||||
string is kept unambiguous,
|
||||
.Ar level
|
||||
and slash prior to
|
||||
and the slash prior to
|
||||
.Ar level
|
||||
can be omitted.
|
||||
However, it is encouraged to specify them explicitly
|
||||
can be omitted but you are encouraged to specify them explicitly
|
||||
to avoid unintended behaviors.
|
||||
If
|
||||
.Ar level
|
||||
@ -239,47 +269,66 @@ is omitted, it will be interpreted as
|
||||
.El
|
||||
.El
|
||||
.Pp
|
||||
Note that there is a bit difference of specification from
|
||||
Note that there is a difference between the specification allowed here
|
||||
and in
|
||||
.Xr setkey 8 .
|
||||
In specification by
|
||||
When specifying security policies with
|
||||
.Xr setkey 8 ,
|
||||
both entrust and bypass are not used.
|
||||
neither entrust nor bypass are used.
|
||||
Refer to
|
||||
.Xr setkey 8
|
||||
for detail.
|
||||
.Pp
|
||||
Here are several examples
|
||||
(long lines are wrapped for readability):
|
||||
for details.
|
||||
.Sh EXAMPLES
|
||||
Set a policy that all inbound packets are discarded.
|
||||
.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
|
||||
.\"
|
||||
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 of policy specification if
|
||||
successful; otherwise a NULL pointer is returned.
|
||||
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 with positive value
|
||||
(meaning the buffer size)
|
||||
on success, and negative value on errors.
|
||||
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 dynamically allocated region on success,
|
||||
and
|
||||
function returns a pointer to a dynamically allocated region
|
||||
containing a human readable security policy on success, and
|
||||
.Dv NULL
|
||||
on errors.
|
||||
on error.
|
||||
.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.
|
||||
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
|
||||
|
||||
@ -29,13 +29,13 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd May 6, 1998
|
||||
.Dd February 14, 2006
|
||||
.Dt IPSEC_STRERROR 3
|
||||
.Os
|
||||
.\"
|
||||
.Sh NAME
|
||||
.Nm ipsec_strerror
|
||||
.Nd error message for IPsec policy manipulation library
|
||||
.Nd error messages for the IPsec policy manipulation library
|
||||
.\"
|
||||
.Sh SYNOPSIS
|
||||
.In netinet6/ipsec.h
|
||||
@ -49,7 +49,7 @@ declares
|
||||
.Dl extern int ipsec_errcode;
|
||||
.Pp
|
||||
which is used to pass an error code from IPsec policy manipulation library
|
||||
to an user program.
|
||||
to a user program.
|
||||
The
|
||||
.Fn ipsec_strerror
|
||||
function can be used to obtain the error message string for the error code.
|
||||
@ -59,19 +59,19 @@ Since
|
||||
.Fn ipsec_strerror
|
||||
uses
|
||||
.Xr strerror 3
|
||||
as underlying function, calling
|
||||
as an underlying function, calling
|
||||
.Xr strerror 3
|
||||
after
|
||||
.Fn ipsec_strerror
|
||||
would make the return value from
|
||||
would overwrite the the return value from
|
||||
.Fn ipsec_strerror
|
||||
invalid, or overwritten.
|
||||
and make it invalid.
|
||||
.\"
|
||||
.Sh RETURN VALUES
|
||||
The
|
||||
.Fn ipsec_strerror
|
||||
function always returns a pointer to C string.
|
||||
The C string must not be overwritten by user programs.
|
||||
The C string must not be overwritten by the caller.
|
||||
.\"
|
||||
.Sh SEE ALSO
|
||||
.Xr ipsec_set_policy 3
|
||||
|
||||
@ -41,42 +41,44 @@
|
||||
.In netinet6/ipsec.h
|
||||
.Sh DESCRIPTION
|
||||
.Nm
|
||||
is a security protocol in Internet Protocol layer.
|
||||
is a security protocol implemented within the Internet Protocol layer
|
||||
of the TCP/IP stack.
|
||||
.Nm
|
||||
is defined for both IPv4 and IPv6
|
||||
.Xr ( inet 4
|
||||
and
|
||||
.Xr inet6 4 ) .
|
||||
.Nm
|
||||
consists of two sub-protocols, namely
|
||||
ESP
|
||||
(encapsulated security payload)
|
||||
and AH
|
||||
(authentication header).
|
||||
ESP protects IP payload from wire-tapping by encrypting it by
|
||||
contains two protocols,
|
||||
ESP, the encapsulated security payload protocol and
|
||||
AH, the authentication header protocol.
|
||||
ESP prevents unauthorized parties from reading the payload of an IP packet
|
||||
by encrypting it using
|
||||
secret key cryptography algorithms.
|
||||
AH guarantees integrity of IP packet
|
||||
and protects it from intermediate alteration or impersonation,
|
||||
by attaching cryptographic checksum computed by one-way hash functions.
|
||||
AH both authenticates guarantees the integrity of an IP packet
|
||||
by attaching a cryptographic checksum computed using one-way hash functions.
|
||||
.Nm
|
||||
has two operation modes: transport mode and tunnel mode.
|
||||
Transport mode is for protecting peer-to-peer communication between end nodes.
|
||||
Tunnel mode includes IP-in-IP encapsulation operation
|
||||
and is designed for security gateways, like VPN configurations.
|
||||
has operates in one of two modes: transport mode or tunnel mode.
|
||||
Transport mode is used to protect peer-to-peer communication between end nodes.
|
||||
Tunnel mode encapsulates IP packets within other IP packets
|
||||
and is designed for security gateways such as VPN endpoints.
|
||||
.\"
|
||||
.Ss Kernel interface
|
||||
.Nm
|
||||
is controlled by key management engine and policy engine,
|
||||
in the operating system kernel.
|
||||
is controlled by a key management and policy engine,
|
||||
that reside in the operating system kernel. Key management
|
||||
is the process of associating keys with security associations, also
|
||||
know as SAs. Policy management dictates when new security
|
||||
associations created or destroyed.
|
||||
.Pp
|
||||
Key management engine can be accessed from the userland by using
|
||||
The key management engine can be accessed from userland by using
|
||||
.Dv PF_KEY
|
||||
sockets.
|
||||
The
|
||||
.Dv PF_KEY
|
||||
socket API is defined in RFC2367.
|
||||
.Pp
|
||||
Policy engine can be controlled by extended part of
|
||||
The policy engine is controlled by an extension to the
|
||||
.Dv PF_KEY
|
||||
API,
|
||||
.Xr setsockopt 2
|
||||
@ -84,48 +86,41 @@ operations, and
|
||||
.Xr sysctl 3
|
||||
interface.
|
||||
The kernel implements
|
||||
extended version of
|
||||
an extended version of the
|
||||
.Dv PF_KEY
|
||||
interface, and allows you to define IPsec policy like per-packet filters.
|
||||
interface, and allows the programmer to define IPsec policies
|
||||
which are similar to the per-packet filters. The
|
||||
.Xr setsockopt 2
|
||||
interface is used to define per-socket behavior, and
|
||||
.Xr sysctl 3
|
||||
interface is used to define host-wide default behavior.
|
||||
.Pp
|
||||
The kernel code does not implement dynamic encryption key exchange protocol
|
||||
like IKE
|
||||
The kernel code does not implement a dynamic encryption key exchange protocol
|
||||
such as IKE
|
||||
(Internet Key Exchange).
|
||||
That should be implemented as userland programs
|
||||
(usually as daemons),
|
||||
by using the above described APIs.
|
||||
Key exchange protocols are beyond what is necessary in the kernel and
|
||||
should be implemented as daemon processes which call the
|
||||
.Nm APIs.
|
||||
.\"
|
||||
.Ss Policy management
|
||||
The kernel implements experimental policy management code.
|
||||
You can manage the IPsec policy in two ways.
|
||||
One is to configure per-socket policy using
|
||||
.Xr setsockopt 2 .
|
||||
The other is to configure kernel packet filter-based policy using
|
||||
IPSec policies can be managed in one of two ways, either by
|
||||
configuring per-socket policies using the
|
||||
.Xr setsockopt 2
|
||||
system calls, or by configuring kernel level packet filter-based
|
||||
policies using the
|
||||
.Dv PF_KEY
|
||||
interface, via
|
||||
.Xr setkey 8 .
|
||||
In both cases, IPsec policy must be specified with syntax described in
|
||||
interface, via the
|
||||
.Xr setkey 8
|
||||
command.
|
||||
In either cases, IPsec policies must be specified using the syntax described in
|
||||
.Xr ipsec_set_policy 3 .
|
||||
.Pp
|
||||
With
|
||||
.Xr setsockopt 2 ,
|
||||
you can define IPsec policy in per-socket basis.
|
||||
You can enforce particular IPsec policy onto packets that go through
|
||||
particular socket.
|
||||
.Pp
|
||||
With
|
||||
Please refer to the
|
||||
.Xr setkey 8
|
||||
you can define IPsec policy against packets,
|
||||
using sort of packet filtering rule.
|
||||
Refer to
|
||||
.Xr setkey 8
|
||||
on how to use it.
|
||||
man page for instructionson its use.
|
||||
.Pp
|
||||
In the latter case,
|
||||
When setting policies using the
|
||||
.Xr setkey 8
|
||||
command the
|
||||
.Dq Li default
|
||||
policy is allowed for use with
|
||||
.Xr setkey 8 .
|
||||
|
||||
Loading…
Reference in New Issue
Block a user