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][NAF]'s [Open Technology Institute][OTI]. 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 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 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 [SID][]s 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 [SID][]s 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.** ![CC-BY-4.0](./cc-by-4.0.png) Available under the [Creative Commons Attribution 4.0 International licence][CC BY 4.0]. [Serval Project]: http://www.servalproject.org/ [CC BY 4.0]: ../LICENSE-DOCUMENTATION.md [grant]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:activity:naf6 [NAF]: http://www.newamerica.net/ [OTI]: http://oti.newamerica.net/ [Serval DNA]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:servaldna: [config option]: ./Servald-Configuration.md [SID]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:sid [MDP]: ./Mesh-Datagram-Protocol.md [MDP port]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:mdp_port_number