a rewrite of enc.4, hopefully a little more useful than what we previously

had; more can go in here, so feel free...

many thanks to ho for feedback, and angelos and cedric who i harangued
endlessly to explain nat/ipsec to me;

the ipsec.conf.5 change just moves some stuff more appropriate to enc.4;

ok hshoexer

2 files changed, 85 insertions, 79 deletions

diff --git a/sbin/ipsecctl/ipsec.conf.5 b/sbin/ipsecctl/ipsec.conf.5
index 2821997eca5..73ce74b8437 100644
--- a/sbin/ipsecctl/ipsec.conf.5
+++ b/sbin/ipsecctl/ipsec.conf.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ipsec.conf.5,v 1.108 2006/12/06 09:54:15 jmc Exp $
+.\"	$OpenBSD: ipsec.conf.5,v 1.109 2006/12/12 21:20:02 jmc Exp $
 .\"
 .\" Copyright (c) 2004 Mathieu Sauve-Frankel  All rights reserved.
 .\"
@@ -428,6 +428,10 @@ on the external interface.
 .It enc0
 Interface for outgoing traffic before it's been encapsulated,
 and incoming traffic after it's been decapsulated.
+State on this interface should be interface bound;
+see
+.Xr enc 4
+for further information.
 .It proto ipencap
 [tunnel mode only]
 IP-in-IP traffic flowing between gateways
@@ -472,22 +476,6 @@ pass out on enc0 from 10.0.1.0/24 to 10.0.2.0/24 \e
 .Ed
 .Pp
 .Xr pf 4
-is a stateful packet filter,
-which means it can track the state of a connection.
-It does this
-.Em automatically .
-States are normally
-.Em floating ,
-which means they can match packets on any interface.
-However this is a potential problem for filtering IPsec traffic:
-states need to be interface bound,
-to avoid permitting unencrypted traffic should
-.Xr isakmpd 8
-exit.
-Therefore all rules on the enc0 interface should explicitly set
-.Dq keep state (if-bound) .
-.Pp
-.Xr pf 4
 has the ability to filter IPsec-related packets
 based on an arbitrary
 .Em tag
diff --git a/share/man/man4/enc.4 b/share/man/man4/enc.4
index f517d6858e1..03d68fe5c3a 100644
--- a/share/man/man4/enc.4
+++ b/share/man/man4/enc.4
@@ -1,87 +1,105 @@
-.\"	$OpenBSD: enc.4,v 1.23 2006/10/19 08:52:25 jmc Exp $
+.\"	$OpenBSD: enc.4,v 1.24 2006/12/12 21:20:02 jmc Exp $
 .\"
-.\" Copyright (c) 1999 Angelos D. Keromytis
-.\" All rights reserved.
+.\" Copyright (c) 2006 Jason McIntyre <jmc@openbsd.org>
 .\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
 .\"
-.\" 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. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"	This product includes software developed by Angelos D. Keromytis.
-.\" 4. The name of the author may not be used to endorse or promote products
-.\"    derived from this software without specific prior written permission.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 October 7, 1999
+.Dd November 26, 2006
 .Dt ENC 4
 .Os
 .Sh NAME
 .Nm enc
-.Nd Encapsulating Interface
+.Nd encapsulating interface
 .Sh SYNOPSIS
-.Cd "pseudo-device enc" Op Ar count
+.Cd "pseudo-device enc 1"
 .Sh DESCRIPTION
 The
 .Nm
-interface is a software loopback mechanism that allows hosts or
-firewalls to filter
+interface is a virtual interface for
 .Xr ipsec 4
-traffic using
-.Xr pf 4 .
+traffic.
+It allows packet filtering using
+.Xr pf 4 ;
+prior to encapsulation and after decapsulation,
+packets may be monitored using
+.Xr tcpdump 8 .
+Only one
+.Nm
+interface, enc0, is supported.
 .Pp
-The
+Packet filtering is documented in greater detail in
+.Xr pf.conf 5 ,
+however some details relevant to filtering on the
 .Nm
-interface allows an administrator
-to see outgoing packets before they have been processed by
-.Xr ipsec 4 ,
-or incoming packets after they have been similarly processed, via
-.Xr tcpdump 8 .
+interface are documented below.
 .Pp
-The
-.Dq enc0
-interface inherits all IPsec traffic.
-Thus all IPsec traffic can be filtered based on
-.Dq enc0 ,
-and all IPsec traffic could be seen by invoking
-.Xr tcpdump 8
-on the
-.Dq enc0
-interface.
-Filter rules on the enc0 interface should explicitly set
+Firstly,
+.Xr pf 4
+is a stateful packet filter,
+which means it can track the state of a connection.
+It does this
+.Em automatically .
+States are normally
+.Em floating ,
+which means they can match packets on any interface.
+However this is a potential problem for filtering IPsec traffic:
+states need to be interface bound,
+to avoid permitting unencrypted traffic
+should the SAs expire and not be replaced.
+Therefore all rules on the
+.Nm
+interface should explicitly set
 .Dq keep state (if-bound) .
-See
-.Xr pf.conf 5
-and
+For example:
+.Bd -literal -offset indent
+pass in on enc0 proto ipencap from 192.168.3.2 to 192.168.3.1 \e
+	keep state (if-bound)
+.Ed
+.Pp
+Secondly, the
+.Nm
+interface does not directly support bandwidth control via
+.Xr pf 4
+queueing.
+Instead, IPsec packets must be tagged and the tagged packets
+are assigned to queues.
 .Xr ipsec.conf 5
-for more information on filtering IPsec traffic.
-.Sh EXAMPLES
-To see all outgoing packets before they have been processed via
-.Xr ipsec 4 ,
-or all incoming packets after they have been similarly processed:
+provides an example of tag-based queueing
+and further information on packet tagging.
+.Pp
+Finally,
+the use of translation rules to map and redirect network traffic
+requires some care.
+Packets destined to be IPsec processed are seen by the
+filer/translation engine twice,
+both before and after being IPsec processed.
+If a packet's translated address
+on the way back fails to match an existing IPsec flow,
+from the translated address to the original source address,
+it will be discarded by the filter.
+It is best to avoid this situation where possible,
+though a flow may be explicitly created to work around it.
+.Pp
+As noted above,
+.Xr tcpdump 8
+may be invoked on the
+.Nm
+interface to see packets prior to encapsulation and after decapsulation.
+For example:
 .Pp
 .Dl # tcpdump -i enc0
 .Sh SEE ALSO
-.Xr bpf 4 ,
-.Xr inet 4 ,
 .Xr ipsec 4 ,
-.Xr netintro 4 ,
 .Xr pf 4 ,
 .Xr ipsec.conf 5 ,
 .Xr pf.conf 5 ,