git: 5ed470bdb9da - main - pf: Update documentation regarding matching, scrubbing and reassembly
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Thu, 19 Oct 2023 08:52:20 UTC
The branch main has been updated by kp:
URL: https://cgit.FreeBSD.org/src/commit/?id=5ed470bdb9da6442d6030cf0a7a8493f759fbb43
commit 5ed470bdb9da6442d6030cf0a7a8493f759fbb43
Author: Kajetan Staszkiewicz <vegeta@tuxpowered.net>
AuthorDate: 2023-10-19 08:41:32 +0000
Commit: Kristof Provost <kp@FreeBSD.org>
CommitDate: 2023-10-19 08:41:32 +0000
pf: Update documentation regarding matching, scrubbing and reassembly
Update pf documentation:
- default behaviour of fragment reassembly
- introduction of scrub option for filter rules
- disadvantages of using the old scrub ruleset
- options supported for match rules
- fix missing list block end
- remove duplicate description of match filter rule
- update example to modern syntax
Reviewed by: kp
Fragments obtained from: OpenBSD
Sponsored by: InnoGames GmbH
Differential Revision: https://reviews.freebsd.org/D42270
---
share/man/man5/pf.conf.5 | 149 ++++++++++++++++++++++++++++++++---------------
1 file changed, 103 insertions(+), 46 deletions(-)
diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index 2bc57d4f7f5b..349e6c9ee4eb 100644
--- a/share/man/man5/pf.conf.5
+++ b/share/man/man5/pf.conf.5
@@ -27,7 +27,7 @@
.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd June 21, 2023
+.Dd October 17, 2023
.Dt PF.CONF 5
.Os
.Sh NAME
@@ -386,7 +386,9 @@ set limit frags 20000
.Ed
.Pp
sets the maximum number of entries in the memory pool used for fragment
-reassembly (generated by
+reassembly (generated by the
+.Ar set reassemble
+option or
.Ar scrub
rules) to 20000.
Using
@@ -480,6 +482,29 @@ For example:
.Bd -literal -offset indent
set optimization aggressive
.Ed
+.It Ar set reassemble yes | no Op Cm no-df
+The
+.Cm reassemble
+option is used to enable or disable the reassembly of fragmented packets,
+and can be set to
+.Cm yes
+or
+.Cm no .
+If
+.Cm no-df
+is also specified, fragments with the
+.Dq dont-fragment
+bit set are reassembled too,
+instead of being dropped;
+the reassembled packet will have the
+.Dq dont-fragment
+bit cleared.
+The default value is
+.Cm no .
+.Pp
+This option is ignored if there are pre-FreeBSD 14
+.Cm scrub
+rules present.
.It Ar set block-policy
The
.Ar block-policy
@@ -753,19 +778,21 @@ Used to specify that packets must already be tagged with the given tag in order
to match the rule.
Inverse tag matching can also be done by specifying the ! operator before the
tagged keyword.
+.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 the
-.Ar scrub
-directive.
-.Pp
-.Ar scrub
-has the following options:
+Traffic normalization is a broad umbrella term
+for aspects of the packet filter which deal with
+verifying packets, packet fragments, spoofed traffic,
+and other irregularities.
+.Ss Scrub
+Scrub involves sanitising packet content in such a way
+that there are no ambiguities in packet interpretation on the receiving side.
+It is invoked with the
+.Cm scrub
+option, added to filter rules.
+.Pp
+Parameters are specified enclosed in parentheses.
+At least one of the following parameters must be specified:
.Bl -tag -width xxxx
.It Ar no-df
Clears the
@@ -824,22 +851,8 @@ 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
-Using
-.Ar scrub
-rules, fragments can be reassembled by normalization.
-In this case, 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.
-This is the default behaviour unless no fragment reassemble is specified.
-.It Ar no fragment reassemble
-Do not reassemble fragments.
.It Ar reassemble tcp
Statefully normalizes TCP connections.
-.Ar scrub reassemble tcp
-rules may not have the direction (in/out) specified.
.Ar reassemble tcp
performs the following normalizations:
.Pp
@@ -891,6 +904,41 @@ blind attacker would have to guess the timestamp as well.
.Pp
For example,
.Bd -literal -offset indent
+match in all scrub (no-df random-id max-mss 1440)
+.Ed
+.Ss Scrub ruleset (pre-FreeBSD 14)
+In order to maintain compatibility with older releases of FreeBSD
+.Ar scrub
+rules can also be specified in their own ruleset.
+In such case they are invoked with the
+.Ar scrub
+directive.
+If there are such rules present they determine packet reassembly behaviour.
+When no such rules are present the option
+.Ar set reassembly
+takes precedence.
+The
+.Ar scrub
+rules can take all parameters specified above for a
+.Ar scrub
+option of filter rules and 2 more parameters controlling fragment reassembly:
+.Bl -tag -width xxxx
+.It Ar fragment reassemble
+Using
+.Ar scrub
+rules, fragments can be reassembled by normalization.
+In this case, 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.
+This is the default behaviour unless no fragment reassemble is specified.
+.It Ar no fragment reassemble
+Do not reassemble fragments.
+.El
+.Pp
+For example,
+.Bd -literal -offset indent
scrub in on $ext_if all fragment reassemble
.Ed
.Pp
@@ -902,6 +950,14 @@ much in the same way as
works in the packet filter (see below).
This mechanism should be used when it is necessary to exclude specific packets
from broader scrub rules.
+.Pp
+.Ar scrub
+rules in the
+.Ar scrub
+ruleset are evaluated for every packet before stateful filtering.
+This means excessive usage of them will cause performance penalty.
+.Ar scrub reassemble tcp
+rules must not have the direction (in/out) specified.
.Sh QUEUEING with ALTQ
The ALTQ system is currently not available in the GENERIC kernel nor as
loadable modules.
@@ -1479,28 +1535,21 @@ rules differ from
.Ar block
and
.Ar pass
-rules in that parameters are set every time a packet matches the rule, not only
+rules in that parameters are set for every rule a packet matches, not only
on the last matching rule.
For the following parameters, this means that the parameter effectively becomes
"sticky" until explicitly overridden:
.Ar queue ,
.Ar dnpipe ,
-.Ar dnqueue
+.Ar dnqueue ,
+.Ar rtable ,
+.Ar scrub
.
.It Ar pass
The packet is passed;
state is created unless the
.Ar no state
option is specified.
-.It Ar match
-Action is unaltered, the previously matched rule's action still matters.
-Match rules apply queue and rtable assignments for every matched packet,
-subsequent matching pass or match rules can overwrite the assignment,
-if they don't specify a queue or an rtable, respectively, the previously
-set value remains.
-Additionally, match rules can contain log statements; the is logging done
-for each and every matching match rule, so it is possible to log a single
-packet multiple times.
.El
.Pp
By default
@@ -2579,6 +2628,8 @@ contain the necessary header information for the subprotocol that allows
to filter on things such as TCP ports or to perform NAT.
.Pp
Besides the use of
+.Ar set reassemble
+option or
.Ar scrub
rules as described in
.Sx TRAFFIC NORMALIZATION
@@ -2587,7 +2638,11 @@ above, there are three options for handling fragments in the packet filter.
One alternative is to filter individual fragments with filter rules.
If no
.Ar scrub
-rule applies to a fragment, it is passed to the filter.
+rule applies to a fragment or
+.Ar set reassemble
+is set to
+.Cm no
+, it is passed to the filter.
Filter rules with matching IP header parameters decide whether the
fragment is passed or blocked, in the same way as complete packets
are filtered.
@@ -2620,11 +2675,13 @@ rules.
.Pp
In most cases, the benefits of reassembly outweigh the additional
memory cost, and it's recommended to use
+.Ar set reassemble
+option or
.Ar scrub
-rules to reassemble
-all fragments via the
+rules with the
.Ar fragment reassemble
-modifier.
+modifier to reassemble
+all fragments.
.Pp
The memory allocated for fragment caching can be limited using
.Xr pfctl 8 .
@@ -2989,12 +3046,12 @@ rdr on $ext_if proto tcp from any to any port 80 \e
# (157.161.48.183, the only routable address)
# and the private network is 10.0.0.0/8, for which we are doing NAT.
+# Reassemble incoming traffic
+set reassemble yes
+
# use a macro for the interface name, so it can be changed easily
ext_if = \&"kue0\&"
-# normalize all incoming traffic
-scrub in on $ext_if all fragment reassemble
-
# block and log everything by default
block return log on $ext_if all