Serval DNA Mesh Packet Filtering

Serval Project, May 2014

The Serval DNA daemon can perform filtering on all incoming and outgoing MDP packets, ie, packets that are addressed to the local node and packets that originate from the local node.

Serval DNA cannot filter packets that it is forwarding to other nodes.

The original MDP packet filtering capability was funded by a grant from the New America Foundation's Open Technology Institute.

How to configure packet filtering

Packet filtering is disabled by default, so all packets are allowed.

To enable MDP packet filtering, set the mdp.filter_rules_path config option to the absolute or relative path of a filter rules file. Relative paths are interpreted with respect to the same directory that contains the configuration file.

Example 1

allow <>*:1-7
allow *:1-10 <>*
allow broadcast:70 <DEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEAD
allow >ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB:20100
drop <*:8
allow <>0123012301230123012301230123012301230123012301230123012301230123
allow <>4567456745674567456745674567456745674567456745674567456745674567:12-18
drop all

Grammar

rules := optspace [ rule optspace ( sep optspace rule optspace ){0..} ]
sep := "\n" | ";"
rule := verb space which
verb := "allow" | "drop"
which := "all" | pattern
pattern := [ endpoint optspace ] direction optspace endpoint
direction := ">" | "<" | "<>"
endpoint := sidany [ optspace ":" optspace portrange ]
sidany := "*" | sidhex | "broadcast"
sidhex := hexdigit {64}
portrange := port optspace [ "-" optspace port ]
port := hexport | decport
hexport := "0x" hexdigit {1..8}
decport := decdigit {1..10}
decdigit := "0".."9"
hexdigit := decdigit | "A".."F" | "a".."f"
optspace := " " {0..}
space := " " {1..}

How rules work

For each incoming and outgoing packet, all packet rules are tested in the order that they appear in the rules file. The first rule that matches the packet determines whether the packet is allowed or dropped, and no more rules are tested. If no rules match, the packet is allowed by default.

Rules are separated by a single newline (ASCII 10) or semicolon ;.
Each rule is an action (drop or allow) followed either by the word all or followed by an optional local pattern followed by a direction and a remote pattern.
A rule with the all word matches all packets, which means that any following rules are ignored. So an all rule should be the last rule in the file.
A non-all rule only matches a packet if its local pattern, direction, AND remote pattern all match.
The local pattern, if given, is tested against the packet's local address; if absent, all local addresses match. For incoming packets this means the recipient (destination) address, and for outgoing packets this means the sending (originating) address.
The direction is one of <, > or <>, which causes the rule to match only incoming packets, only outgoing packets, or both.
The remote pattern is tested against the packet's remote address. For incoming packets this means the sending (originating) address, and for outgoing packets this means the recipient (destination) address.
A pattern (local or remote) is a SID optionally followed by a colon : and a range of MDP port numbers.
A pattern only matches an address if its SID matches the address's SID AND its port number lies within the address's port number range. If the pattern has no port number range, then it matches all port numbers.
A pattern's SID can be given either as 64 hexadecimal digits, which matches that SID exactly, or the word broadcast, which matches only the all-bits-set SID (FFFF....FF), or the star symbol * which matches any SID.
A port number range is either a single port number, which matches only that port number exactly, or a pair of port numbers separated by a dash - where the second number is greater than the first. Each port number is either a decimal integer in the range 1 to 4294967295 inclusive or a hexadecimal number prefixed with 0x in the range 0x1 to 0xffffffff.

Interpretation of example 1

The rules file shown in Example 1 above has the following meaning:

allow <>*:1-7

allows all incoming packets originating from remote ports 1 through 7, and allows all outgoing packets (which will probably be replies) to the same range of remote ports
allow *:1-10 <>*

allows all incoming packets to local ports between 1 and 10 inclusive, and all outgoing packets from those ports
allow broadcast:70 <DEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEADDEAD

allows all broadcast packets sent to local port 70 from any port on the node with SID DEAD...DEAD
allow >ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB:20100

allows all outgoing packets to port 20100 on the node with SID ABAB...ABAB
drop <*:8

drops all incoming packets (that were not allowed by prior rules) sent from port 8 on any remote node
allow <>0123012301230123012301230123012301230123012301230123012301230123

allows all incoming and outgoing packets (that were not dropped by prior rules) from and to the node with SID 0123...0123
allow <>4567456745674567456745674567456745674567456745674567456745674567:12-18

allows all incoming and outgoing packets (that were not dropped by prior rules) from and to ports 12 through 18 inclusive on the node with SID 4567...4567
drop all

drops all incoming and outgoing packets that were not allowed by prior rules

Special case: SID whitelist

A filter rules file that whitelists a set of SIDs will have the following form:

allow <>0001000100010001000100010001000100010001000100010001000100010001
allow <>0002000200020002000200020002000200020002000200020002000200020002
allow <>0003000300030003000300030003000300030003000300030003000300030003
...
allow <>000n000n000n000n000n000n000n000n000n000n000n000n000n000n000n000n
drop all

where the symbols 0001...0001 through 000n...000n are replaced by the hexadecimal representations of the actual SIDs in the whitelist.

Note: If the final line drop all is missing, then the whitelist will have no effect.

Special case: SID blacklist

A filter rules file that blacklists a set of SIDs will have the following form:

drop <>0001000100010001000100010001000100010001000100010001000100010001
drop <>0002000200020002000200020002000200020002000200020002000200020002
drop <>0003000300030003000300030003000300030003000300030003000300030003
...
drop <>000n000n000n000n000n000n000n000n000n000n000n000n000n000n000n000n

where the symbols 0001...0001 through 000n...000n are replaced by the hexadecimal representations of the actual SIDs in the blacklist.

Copyright 2014 Serval Project Inc.
Available under the Creative Commons Attribution 4.0 International licence.

7.8 KiB Raw Blame History