catch up with recent changes (scrub, match, ...); still a ways to go

ok henning

1 files changed, 141 insertions, 161 deletions

diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index 72bdd53f4e0..92abbe719c0 100644
--- a/share/man/man5/pf.conf.5
+++ b/share/man/man5/pf.conf.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pf.conf.5,v 1.412 2009/04/07 12:52:57 henning Exp $
+.\"	$OpenBSD: pf.conf.5,v 1.413 2009/04/07 13:27:32 jmc Exp $
 .\"
 .\" Copyright (c) 2002, Daniel Hartmeier
 .\" All rights reserved.
@@ -40,7 +40,7 @@ packet filter modifies, drops or passes packets according to rules or
 definitions specified in
 .Nm pf.conf .
 .Sh STATEMENT ORDER
-There are seven types of statements in
+There are six types of statements in
 .Nm pf.conf :
 .Bl -tag -width xxxx
 .It Cm Macros
@@ -53,9 +53,6 @@ Tables provide a mechanism for increasing the performance and flexibility of
 rules with large numbers of source or destination addresses.
 .It Cm Options
 Options tune the behaviour of the packet filtering engine.
-.It Cm Traffic Normalization Li (reassembly and scrubbing)
-Traffic normalization protects internal machines against inconsistencies
-in Internet protocols and implementations.
 .It Cm Queueing
 Queueing provides rule-based bandwidth control.
 .It Cm Translation Li (various forms of NAT)
@@ -608,137 +605,6 @@ set either.
 Setting this option does not affect non-fragmented packets.
 Fragment reassembly is turned on by default.
 .El
-.Sh TRAFFIC NORMALIZATION
-Traffic normalization is used to sanitize packet content in such
-a way that there are no ambiguities in packet interpretation on
-the receiving side.
-The normalizer does IP fragment reassembly to prevent attacks
-that confuse intrusion detection systems by sending overlapping
-IP fragments.
-Packet normalization is invoked with either the
-.Ar scrub
-option, added to regular rules, or by means of the
-.Ar reassemble
-option.
-.Pp
-.Ar scrub
-has the following parameters:
-.Bl -tag -width xxxx
-.It Ar no-df
-Clears the
-.Ar dont-fragment
-bit from a matching IP packet.
-Some operating systems are known to generate fragmented packets with the
-.Ar dont-fragment
-bit set.
-This is particularly true with NFS.
-.Ar scrub
-will drop such fragmented
-.Ar dont-fragment
-packets unless
-.Ar no-df
-is specified.
-.Pp
-Unfortunately some operating systems also generate their
-.Ar dont-fragment
-packets with a zero IP identification field.
-Clearing the
-.Ar dont-fragment
-bit on packets with a zero IP ID may cause deleterious results if an
-upstream router later fragments the packet.
-Using the
-.Ar random-id
-modifier (see below) is recommended in combination with the
-.Ar no-df
-modifier to ensure unique IP identifiers.
-.It Ar min-ttl Aq Ar number
-Enforces a minimum TTL for matching IP packets.
-.It Ar max-mss Aq Ar number
-Enforces a maximum MSS for matching TCP packets.
-.It Xo Ar set-tos Aq Ar string
-.No \*(Ba Aq Ar number
-.Xc
-Enforces a
-.Em TOS
-for matching IP packets.
-.Em TOS
-may be
-given as one of
-.Ar lowdelay ,
-.Ar throughput ,
-.Ar reliability ,
-or as either hex or decimal.
-.It Ar random-id
-Replaces the IP identification field with random values to compensate
-for predictable values generated by many hosts.
-This option only applies to packets that are not fragmented
-after the optional fragment reassembly.
-.It Ar fragment reassemble
-If fragment reassembly is turned on, fragments are buffered until they form
-a complete packet and only the completed packet is passed on to the filter.
-The advantage is that filter rules have to deal only with complete
-packets, and can ignore fragments.
-The drawback of caching fragments is the additional memory cost.
-But the full reassembly method is the only method that currently works
-with NAT.
-This is the default behavior of a
-.Ar scrub
-option if no fragmentation modifier is supplied.
-.It Ar reassemble tcp
-Statefully normalizes TCP connections.
-.Ar reassemble tcp
-performs the following normalizations:
-.Pp
-.Bl -tag -width timeout -compact
-.It ttl
-Neither side of the connection is allowed to reduce their IP TTL.
-An attacker may send a packet such that it reaches the firewall, affects
-the firewall state, and expires before reaching the destination host.
-.Ar reassemble tcp
-will raise the TTL of all packets back up to the highest value seen on
-the connection.
-.It timestamp modulation
-Modern TCP stacks will send a timestamp on every TCP packet and echo
-the other endpoint's timestamp back to them.
-Many operating systems will merely start the timestamp at zero when
-first booted, and increment it several times a second.
-The uptime of the host can be deduced by reading the timestamp and multiplying
-by a constant.
-Also observing several different timestamps can be used to count hosts
-behind a NAT device.
-And spoofing TCP packets into a connection requires knowing or guessing
-valid timestamps.
-Timestamps merely need to be monotonically increasing and not derived off a
-guessable base time.
-.Ar reassemble tcp
-will cause
-.Ar scrub
-to modulate the TCP timestamps with a random number.
-.It extended PAWS checks
-There is a problem with TCP on long fat pipes, in that a packet might get
-delayed for longer than it takes the connection to wrap its 32-bit sequence
-space.
-In such an occurrence, the old packet would be indistinguishable from a
-new packet and would be accepted as such.
-The solution to this is called PAWS: Protection Against Wrapped Sequence
-numbers.
-It protects against it by making sure the timestamp on each packet does
-not go backwards.
-.Ar reassemble tcp
-also makes sure the timestamp on the packet does not go forward more
-than the RFC allows.
-By doing this,
-.Xr pf 4
-artificially extends the security of TCP sequence numbers by 10 to 18
-bits when the host uses appropriately randomized timestamps, since a
-blind attacker would have to guess the timestamp as well.
-.El
-.El
-.Pp
-For example,
-.Bd -literal -offset indent
-scrub in on $ext_if all fragment reassemble
-.Ed
 .Sh QUEUEING
 Packets can be assigned to queues for the purpose of bandwidth
 control.
@@ -1194,9 +1060,10 @@ below.
 .Sh PACKET FILTERING
 .Xr pf 4
 has the ability to
-.Ar block
+.Ar block ,
+.Ar pass ,
 and
-.Ar pass
+.Ar match
 packets based on attributes of their layer 3 (see
 .Xr ip 4
 and
@@ -1207,14 +1074,20 @@ and layer 4 (see
 .Xr tcp 4 ,
 .Xr udp 4 )
 headers.
-In addition, packets may also be
-assigned to queues for the purpose of bandwidth control.
 .Pp
 For each packet processed by the packet filter, the filter rules are
 evaluated in sequential order, from first to last.
-The last matching rule decides what action is taken.
-If no rule matches the packet, the default action is to pass
+For
+.Ar block
+and
+.Ar pass ,
+the last matching rule decides what action is taken;
+if no rule matches the packet, the default action is to pass
 the packet.
+For
+.Ar match ,
+actions are taken every time a rule matches;
+the pass/block state of a packet remains unchanged.
 .Pp
 The following actions can be used in the filter:
 .Bl -tag -width xxxx
@@ -1274,9 +1147,9 @@ and
 parameters can be overwritten when supplied to the
 .Ar match
 rule.
-Note that these changes may happen on any
+These changes happen every time a
 .Ar match
-rule, not only on the last matching one.
+rule matches, not only on the last matching one.
 When
 .Ar logging
 is specified, every matching rule causes the packet to be logged.
@@ -1870,7 +1743,127 @@ For example, the following rule will drop 20% of incoming ICMP packets:
 .Bd -literal -offset indent
 block in proto icmp probability 20%
 .Ed
+.It Ar scrub Aq Ar parameter
+Perform traffic normalization on matching packets.
+See
+.Sx TRAFFIC NORMALIZATION
+for further information.
 .El
+.Sh TRAFFIC NORMALIZATION
+Traffic normalization is used to sanitize packet content in such
+a way that there are no ambiguities in packet interpretation on
+the receiving side.
+Packet normalization is invoked with the
+.Ar scrub
+option, added to regular rules.
+.Pp
+.Ar scrub
+has the following parameters:
+.Bl -tag -width xxxx
+.It Ar no-df
+Clears the
+.Ar dont-fragment
+bit from a matching IP packet.
+Some operating systems are known to generate fragmented packets with the
+.Ar dont-fragment
+bit set.
+This is particularly true with NFS.
+.Xr pf 4
+will drop such fragmented
+.Ar dont-fragment
+packets unless
+.Ar no-df
+is specified.
+.Pp
+Unfortunately some operating systems also generate their
+.Ar dont-fragment
+packets with a zero IP identification field.
+Clearing the
+.Ar dont-fragment
+bit on packets with a zero IP ID may cause deleterious results if an
+upstream router later fragments the packet.
+Using the
+.Ar random-id
+modifier (see below) is recommended in combination with the
+.Ar no-df
+modifier to ensure unique IP identifiers.
+.It Ar min-ttl Aq Ar number
+Enforces a minimum TTL for matching IP packets.
+.It Ar max-mss Aq Ar number
+Enforces a maximum MSS for matching TCP packets.
+.It Xo Ar set-tos Aq Ar string
+.No \*(Ba Aq Ar number
+.Xc
+Enforces a
+.Em TOS
+for matching IP packets.
+.Em TOS
+may be
+given as one of
+.Ar lowdelay ,
+.Ar throughput ,
+.Ar reliability ,
+or as either hex or decimal.
+.It Ar random-id
+Replaces the IP identification field with random values to compensate
+for predictable values generated by many hosts.
+This option only applies to packets that are not fragmented
+after the optional fragment reassembly.
+.It Ar reassemble tcp
+Statefully normalizes TCP connections.
+.Ar reassemble tcp
+performs the following normalizations:
+.Pp
+.Bl -tag -width timeout -compact
+.It ttl
+Neither side of the connection is allowed to reduce their IP TTL.
+An attacker may send a packet such that it reaches the firewall, affects
+the firewall state, and expires before reaching the destination host.
+.Ar reassemble tcp
+will raise the TTL of all packets back up to the highest value seen on
+the connection.
+.It timestamp modulation
+Modern TCP stacks will send a timestamp on every TCP packet and echo
+the other endpoint's timestamp back to them.
+Many operating systems will merely start the timestamp at zero when
+first booted, and increment it several times a second.
+The uptime of the host can be deduced by reading the timestamp and multiplying
+by a constant.
+Also observing several different timestamps can be used to count hosts
+behind a NAT device.
+And spoofing TCP packets into a connection requires knowing or guessing
+valid timestamps.
+Timestamps merely need to be monotonically increasing and not derived off a
+guessable base time.
+.Ar reassemble tcp
+will cause
+.Ar scrub
+to modulate the TCP timestamps with a random number.
+.It extended PAWS checks
+There is a problem with TCP on long fat pipes, in that a packet might get
+delayed for longer than it takes the connection to wrap its 32-bit sequence
+space.
+In such an occurrence, the old packet would be indistinguishable from a
+new packet and would be accepted as such.
+The solution to this is called PAWS: Protection Against Wrapped Sequence
+numbers.
+It protects against it by making sure the timestamp on each packet does
+not go backwards.
+.Ar reassemble tcp
+also makes sure the timestamp on the packet does not go forward more
+than the RFC allows.
+By doing this,
+.Xr pf 4
+artificially extends the security of TCP sequence numbers by 10 to 18
+bits when the host uses appropriately randomized timestamps, since a
+blind attacker would have to guess the timestamp as well.
+.El
+.El
+.Pp
+For example,
+.Bd -literal -offset indent
+match in all scrub (no-df max-mss 1440)
+.Ed
 .Sh ROUTING
 If a packet matches a rule with a route option set, the packet filter will
 route the packet according to the type of route option.
@@ -2325,12 +2318,6 @@ contain the necessary header information for the subprotocol that allows
 .Xr pf 4
 to filter on things such as TCP ports or to perform NAT.
 .Pp
-Besides the use of
-.Ar scrub
-as described in
-.Sx TRAFFIC NORMALIZATION
-above, there are three options for handling fragments in the packet filter.
-.Pp
 One alternative is to filter individual fragments with filter rules.
 If packet reassembly is turned off, it is passed to the filter.
 Filter rules with matching IP header parameters decide whether the
@@ -2358,18 +2345,11 @@ This also means that fragments cannot create new or match existing
 state table entries, which makes stateful filtering and address
 translation (NAT, redirection) for fragments impossible.
 .Pp
-It's also possible to reassemble only certain fragments by specifying
-source or destination addresses or protocols as parameters in
-.Ar scrub
-options.
-.Pp
 In most cases, the benefits of reassembly outweigh the additional
 memory cost, and it's recommended to use
-.Ar scrub
-options to reassemble
-all fragments via the
-.Ar fragment reassemble
-modifier.
+.Ar set reassemble
+to reassemble
+all fragments.
 .Pp
 The memory allocated for fragment caching can be limited using
 .Xr pfctl 8 .
@@ -2724,7 +2704,7 @@ rdr on $ext_if proto tcp from any to any port 80 \e
 ext_if = \&"kue0\&"
 
 # normalize all incoming traffic
-scrub in on $ext_if all fragment reassemble
+match in all scrub (no-df max-mss 1440)
 
 # block and log everything by default
 block return log on $ext_if all