Clean up some descriptions and remove ambiguities in the language.

Add explanations to the examples.

MFC after:	1 week

2 files changed, 146 insertions, 97 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