Clean up some descriptions and remove ambiguities in the language.

Add explanations to the examples.

MFC after:	1 week

3 files changed, 188 insertions, 144 deletions

diff --git a/lib/libipsec/ipsec_set_policy.3 b/lib/libipsec/ipsec_set_policy.3
index 048aa7f..8be32f5 100644
--- a/lib/libipsec/ipsec_set_policy.3
+++ b/lib/libipsec/ipsec_set_policy.3
@@ -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
+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
-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).
+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
+
+.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
-out ipsec esp/tunnel/10.1.1.2-10.1.1.1/use
-in ipsec ipcomp/transport//use
-        esp/transport//use
+
+.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
diff --git a/lib/libipsec/ipsec_strerror.3 b/lib/libipsec/ipsec_strerror.3
index 982d195..d162fa6 100644
--- a/lib/libipsec/ipsec_strerror.3
+++ b/lib/libipsec/ipsec_strerror.3
@@ -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
diff --git a/share/man/man4/ipsec.4 b/share/man/man4/ipsec.4
index 1593a21..5479776 100644
--- a/share/man/man4/ipsec.4
+++ b/share/man/man4/ipsec.4
@@ -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 .