mirror of
https://github.com/opnsense/src.git
synced 2026-06-05 06:42:56 -04:00
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
This commit is contained in:
Kajetan Staszkiewicz
Kristof Provost
parent
28f6910714
commit
5ed470bdb9
1 changed files with 102 additions and 45 deletions
|
|
@ -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.
|
||||
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
|
||||
.Ar scrub
|
||||
has the following options:
|
||||
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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue