Index: stable/5/lib/libipsec/ipsec_set_policy.3
===================================================================
--- stable/5/lib/libipsec/ipsec_set_policy.3	(revision 156489)
+++ stable/5/lib/libipsec/ipsec_set_policy.3	(revision 156490)
@@ -1,285 +1,334 @@
 .\"	$KAME: ipsec_set_policy.3,v 1.15 2001/08/17 07:21:36 itojun Exp $
 .\"     $FreeBSD$
 .\"
 .\" 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.
 .\"
-.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
 .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 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.
 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
 .Li /
 .Ar mode
 .Li /
 .Ar src
 .Li -
 .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
 is omitted, it will be interpreted as
 .Li default .
 .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
 .Fx 4.0
Index: stable/5/lib/libipsec/ipsec_strerror.3
===================================================================
--- stable/5/lib/libipsec/ipsec_strerror.3	(revision 156489)
+++ stable/5/lib/libipsec/ipsec_strerror.3	(revision 156490)
@@ -1,89 +1,89 @@
 .\"	$KAME: ipsec_strerror.3,v 1.9 2001/08/17 07:21:36 itojun Exp $
 .\"	$FreeBSD$
 .\"
 .\" 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.
 .\"
-.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
 .Ft "const char *"
 .Fn ipsec_strerror
 .\"
 .Sh DESCRIPTION
 .In netinet6/ipsec.h
 declares
 .Pp
 .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.
 .Pp
 The array pointed to is not to be modified by the program.
 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
 .\"
 .Sh HISTORY
 The
 .Fn ipsec_strerror
 function first appeared in WIDE/KAME IPv6 protocol stack kit.
 .\"
 .Sh BUGS
 The
 .Fn ipsec_strerror
 function will return its result which may be overwritten by subsequent calls.
 .Pp
 .Va ipsec_errcode
 is not thread safe.
Index: stable/5/share/man/man4/ipsec.4
===================================================================
--- stable/5/share/man/man4/ipsec.4	(revision 156489)
+++ stable/5/share/man/man4/ipsec.4	(revision 156490)
@@ -1,337 +1,323 @@
 .\"	$FreeBSD$
 .\"	$KAME: ipsec.4,v 1.17 2001/06/27 15:25:10 itojun Exp $
 .\"
 .\" Copyright (C) 1995, 1996, 1997, and 1998 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.
 .\"
-.Dd January 11, 2005
+.Dd February 14, 2006
 .Dt IPSEC 4
 .Os
 .Sh NAME
 .Nm ipsec
 .Nd IP security protocol
 .Sh SYNOPSIS
 .In sys/types.h
 .In netinet/in.h
 .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
 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 case, 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 instructions on 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 .
-By configuring policy to
-.Li default ,
-you can refer system-wide
-.Xr sysctl 8
-variable for default settings.
-The following variables are available.
+option you can have the system use its default policy, explained
+below, for processing packets.
+The following sysctl variables are available for configuring the
+system's IPsec behavior.  The variables can have one of two values.
+A
 .Li 1
 means
 .Dq Li use ,
-and
+which means that if there is a security association then use it but if
+there is not then the packets are not processed by IPsec.  The value
 .Li 2
-means
-.Dq Li require
-in the syntax.
+is synonymous with
+.Dq Li require ,
+which requires that a security association must exist for the packets
+to move, and not be dropped.  These terms are defined in
+.Xr ipsec_set_policy 8 .
 .Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx
 .It Sy "Name	Type	Changeable"
 .It "net.inet.ipsec.esp_trans_deflev	integer	yes"
 .It "net.inet.ipsec.esp_net_deflev	integer	yes"
 .It "net.inet.ipsec.ah_trans_deflev	integer	yes"
 .It "net.inet.ipsec.ah_net_deflev	integer	yes"
 .It "net.inet6.ipsec6.esp_trans_deflev	integer	yes"
 .It "net.inet6.ipsec6.esp_net_deflev	integer	yes"
 .It "net.inet6.ipsec6.ah_trans_deflev	integer	yes"
 .It "net.inet6.ipsec6.ah_net_deflev	integer	yes"
 .El
 .Pp
-If kernel finds no matching policy system wide default value is applied.
-System wide default is specified by the following
+If the kernel does not find a matching, system wide, policy then the
+default value is applied.  The system wide default policy is specified
+by the following
 .Xr sysctl 8
 variables.
 .Li 0
 means
 .Dq Li discard
 which asks the kernel to drop the packet.
 .Li 1
 means
 .Dq Li none .
 .Bl -column net.inet6.ipsec6.def_policy integerxxx
 .It Sy "Name	Type	Changeable"
 .It "net.inet.ipsec.def_policy	integer	yes"
 .It "net.inet6.ipsec6.def_policy	integer	yes"
 .El
 .\"
 .Ss Miscellaneous sysctl variables
 The following variables are accessible via
 .Xr sysctl 8 ,
-for tweaking kernel IPsec behavior:
+for tweaking the kernel's IPsec behavior:
 .Bl -column net.inet6.ipsec6.inbonud_call_ike integerxxx
 .It Sy "Name	Type	Changeable"
 .It "net.inet.ipsec.ah_cleartos	integer	yes"
 .It "net.inet.ipsec.ah_offsetmask	integer	yes"
 .It "net.inet.ipsec.dfbit	integer	yes"
 .It "net.inet.ipsec.ecn	integer	yes"
 .It "net.inet.ipsec.debug	integer	yes"
 .It "net.inet6.ipsec6.ecn	integer	yes"
 .It "net.inet6.ipsec6.debug	integer	yes"
 .El
 .Pp
 The variables are interpreted as follows:
 .Bl -tag -width 6n
 .It Li ipsec.ah_cleartos
-If set to non-zero, the kernel clears type-of-service field in the IPv4 header
+If set to non-zero, the kernel clears the type-of-service field in the IPv4 header
 during AH authentication data computation.
-The variable is for tweaking AH behavior to interoperate with devices that
+This variable is used to get current systems to inter-operate with devices that
 implement RFC1826 AH.
 It should be set to non-zero
 (clear the type-of-service field)
 for RFC2402 conformance.
 .It Li ipsec.ah_offsetmask
-During AH authentication data computation, the kernel will include
+During AH authentication data computation, the kernel will include a
 16bit fragment offset field
 (including flag bits)
-in IPv4 header, after computing logical AND with the variable.
-The variable is for tweaking AH behavior to interoperate with devices that
+in the IPv4 header, after computing logical AND with the variable.
+The variable is used for inter-operating with devices that
 implement RFC1826 AH.
 It should be set to zero
 (clear the fragment offset field during computation)
 for RFC2402 conformance.
 .It Li ipsec.dfbit
-The variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation.
-If set to 0, DF bit on the outer IPv4 header will be cleared.
-1 means that the outer DF bit is set regardless from the inner DF bit.
-2 means that the DF bit is copied from the inner header to the outer.
+This variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation.
+If set to 0, the DF bit on the outer IPv4 header will be cleared while
+1 means that the outer DF bit is set regardless from the inner DF bit and
+2 indicates that the DF bit is copied from the inner header to the
+outer one.
 The variable is supplied to conform to RFC2401 chapter 6.1.
 .It Li ipsec.ecn
 If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will
 be friendly to ECN
 (explicit congestion notification),
 as documented in
 .Li draft-ietf-ipsec-ecn-02.txt .
 .Xr gif 4
 talks more about the behavior.
 .It Li ipsec.debug
 If set to non-zero, debug messages will be generated via
 .Xr syslog 3 .
 .El
 .Pp
-Variables under
+Variables under the
 .Li net.inet6.ipsec6
-tree has similar meaning as the
-.Li net.inet.ipsec
-counterpart.
+tree have similar meanings to those described above.
 .\"
 .Sh PROTOCOLS
 The
 .Nm
-protocol works like plug-in to
+protocol acts as a plug-in to the
 .Xr inet 4
 and
 .Xr inet6 4
-protocols.
-Therefore,
-.Nm
-supports most of the protocols defined upon those IP-layer protocols.
-Some of the protocols, like
+protocols and therefore supports most of the protocols defined upon
+those IP-layer protocols.  The
 .Xr icmp 4
-or
-.Xr icmp6 4 ,
-may behave differently with
-.Nm .
-This is because
+and
+.Xr icmp6 4 
+protocols may behave differently with
+.Nm 
+because
 .Nm
 can prevent
 .Xr icmp 4
 or
 .Xr icmp6 4
-routines from looking into IP payload.
+routines from looking into the IP payload.
 .\"
 .Sh SEE ALSO
 .Xr ioctl 2 ,
 .Xr socket 2 ,
 .Xr ipsec_set_policy 3 ,
 .Xr icmp6 4 ,
 .Xr intro 4 ,
 .Xr ip6 4 ,
 .Xr setkey 8 ,
 .Xr sysctl 8
 .\".Xr racoon 8
 .Rs
 .%A "S. Kent"
 .%A "R. Atkinson"
 .%T "IP Authentication Header"
 .%O "RFC 2404"
 .Re
 .Rs
 .%A "S. Kent"
 .%A "R. Atkinson"
 .%T "IP Encapsulating Security Payload (ESP)"
 .%O "RFC 2406"
 .Re
 .Sh STANDARDS
 .Rs
 .%A Daniel L. McDonald
 .%A Craig Metz
 .%A Bao G. Phan
 .%T "PF_KEY Key Management API, Version 2"
 .%R RFC
 .%N 2367
 .Re
 .Pp
 .Rs
 .%A "D. L. McDonald"
 .%T "A Simple IP Security API Extension to BSD Sockets"
 .%R internet draft
 .%N "draft-mcdonald-simple-ipsec-api-03.txt"
 .%O work in progress material
 .Re
 .Sh HISTORY
 The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack.
 .Sh BUGS
 The IPsec support is subject to change as the IPsec protocols develop.
 .Pp
-There is no single standard for policy engine API,
+There is no single standard for the policy engine API,
 so the policy engine API described herein is just for KAME implementation.
 .Pp
 AH and tunnel mode encapsulation may not work as you might expect.
 If you configure inbound
 .Dq require
-policy against AH tunnel or any IPsec encapsulating policy with AH
+policy with an AH tunnel or any IPsec encapsulating policy with AH
 (like
 .Dq Li esp/tunnel/A-B/use ah/transport/A-B/require ) ,
 tunnelled packets will be rejected.
-This is because we enforce policy check on inner packet on reception,
+This is because the policy check is enforced on the inner packet on reception,
 and AH authenticates encapsulating
 (outer)
 packet, not the encapsulated
 (inner)
 packet
 (so for the receiving kernel there's no sign of authenticity).
 The issue will be solved when we revamp our policy engine to keep all the
 packet decapsulation history.
 .Pp
-Under certain condition,
-truncated result may be raised from the kernel
-against
+When a large database of security associations or policies is present
+in the kernel the
 .Dv SADB_DUMP
 and
 .Dv SADB_SPDDUMP
-operation on
+operations on
 .Dv PF_KEY
-socket.
-This occurs if there are too many database entries in the kernel
-and socket buffer for the
-.Dv PF_KEY
-socket is insufficient.
-If you manipulate many IPsec key/policy database entries,
-increase the size of socket buffer.
+sockets may fail due to lack of space.  Increasing the socket buffer
+size may alleviate this problem.