host-matching — configuration semantics of lists of hosts
The Kernun Firewall configuration files can contain lists of hosts to be matched against client/server hostnames or IP addresses. This man page describes the semantics of such lists.
According to the Kernun Firewall configuration file syntax (see configuration(7) for details), you can create a host list containing members of several types:
hostname, e.g. www.tns.cz (meaning: www.tns.cz and all its addresses; the name is resolved to IP addresses during proxy startup and then periodically refreshed when needed)
regular expression, e.g. /^www\..*\.cz$/ (meaning: all hosts named 'www' in domains under TLD 'cz')
single IP address, e.g. [192.168.1.1] (square brackets are not metasymbols, they mark IP addresses in configuration)
IP address range, e.g. [192.168.1.12]-[192.168.2.5]
IP address with mask, e.g. [10.0.1.0/255.0.255.0] or [10.0.1.0/0xFF00FF00] (means: all IP addresses with the 1st and the 3rd bytes equal to 10 and 1, respectively)
IP address with mask size, e.g. [192.168.1.0/24] (meaning: all IP addresses with the first 24 bits defined by 192.168.1.0 address)
symbol * (meaning: all hosts)
sublist (meaning: all hosts represented by a sublist)
Members can be prefixed with an exclamation mark
('!'); in such a
case, all names/addresses represented by the particular member are
excluded from the list (so-called excluding or negative members).
For example,
{ ! [192.168.3.3]-[192.168.3.8], * }
means: All but the six addresses specified by the range.
Note that if a sublist is negative, it means that all hosts represented by the sublist are excluded. It does NOT mean that all hosts excluded in the sublist are automatically included in the superlist.
For example,
{ ! [10.1.1.1], [10.0.0.0/8] }
means: The network of 10.* except for 10.1.1.1. However,
{ ! { ! [10.1.1.1], [10.0.0.0/8] }, ...
means: All 10s except 10.1.1.1 are excluded. It does not imply inclusion of 10.1.1.1!
As a conclusion, if a negative member is not followed by a positive member on any list level, the resulting list has the same effect as an empty list.
For example,
{ ! { ! [10.1.1.1], [10.0.0.0/8] } }
means: no hosts are allowed (even [10.1.1.1] is not allowed).
The order of appearance of members in the list is important. Each list is searched from the left to the right and the first match, either positive (for non-excluding member) or negative (for excluding member) stops the search and defines the result (success or failure) that is passed to superlist.
In fact, hostnames are “stronger” than regular expressions. Let us suppose a host 'a.b.c' with IP address 10.1.2.3 and two lists in the configuration: { a.b.c } and { /^a\.b\.c$/ }. If the proxy is testing the hostname 'a.b.c', both lists match. However, if it is testing the IP address, it doesn't know the hostname and the latter list doesn't match. The former one matches because it behaves like the { a.b.c, [10.1.2.3] } list.
The host being matched is known either by an IP address or by a hostname. This is the so-called primary key. However, the matching algorithm may, in some cases, use also a set of so-called secondary keys:
If the primary key is a hostname (e.g. when an HTTP request contains a hostname and the proxy is trying to match it against a particular ACL server list), it is first resolved by a DNS and all IP addresses asociated with it create its secondary key-set.
If a primary key resolves to more than one secondary key, we must define how to match those secondary keys. Specifically: is it sufficient if just one of the secondary keys matches for the whole key to match, or must all of the secondary keys match? We recognize these two modes of matching of a secondary key-set and use them both, each in a different context.
This mode is applied if the list is used to
permit some feature, i.e. when matching a host against
a server-list in a non-denying ACL (a standard ACL without
the deny option).
In this case, if the primary key or all secondary keys are positively matched, the result is positive (i.e., the host is accepted). If the primary key or any secondary key is negatively matched, the result is negative.
This mode is used if the list is used to deny some feature, i.e. when matching a host against a server-list in a denying ACL (an ACL with the deny option set).
In this case, if the primary key or any secondary key is positively matched, the result is positive (and the host will be denied). If the primary key or all secondary keys are matched negatively, the result is negative.
If a list contains a positive (non-excluding) sublist, the matching mode for the sublist is the same as for the superlist. However, if the sublist is negative (excluding), the matching mode changes to the opposite one. For instance, if a hostname resolving to two IPs 10.1.1.1 and 10.2.2.2 is to be rejected by a MATCH-ANY list and we choose to do it by a negative sublist, the sublist must be as follows:
..., ! { [10.1.1.1], [10.2.2.2] }
because it will be searched in MATCH-ALL mode (all IPs must be excluded for the host to be excluded).
A rule that applies to both modes is that if the top-level list has been searched through without positive result, the result is negative.
The secondary key-set is created for the host being matched, and every element of the set is flagged as NOT_MATCHED.
Next, the list members are taken in the order of appearance in the list and
if the member is a regexp then
the hostname is checked against the member and if it matches, the result is stated (either positive or negative, according to the member)
the IP address never matches against regexp
if the member is a hostname then
the hostname is checked against the member (hostname member against hostname key, then IP addresses that the list member resolves to against IP addresses in the secondary key-set) and if it matches, the result is stated (either positive or negative, according to the member)
the IP address is checked against the set of IP addresses that the list member resolves to
if the member is an IP address (or network or range of addresses) then
each of addresses in the secondary key-set that are still NOT_MATCHED is checked against the member and if a match is found, the secondary key is flagged as POSITIVE or NEGATIVE (depending on the “sign” of the list)
the IP address is checked against the member and if it matches, the result is stated (positive or negative)
if the member is * (positive), the result
is positive
if the member is * (negative), the result
is negative.
Now,
if any set-element is flagged NEGATIVE, the result is negative
if all set-elements are flagged POSITIVE, the result is positive
if any set-element is flagged POSITIVE, the result is positive
if all set-elements are flagged NEGATIVE, the result is negative
If the result is not stated, go on searching the list.
If the result is not stated after passing the end of the list, the result is negative.
Suppose the following configuration:
ACL crazy {
SERVER { ! [10.1.2.3], /\\.crazy\\.com$/ };
DENY;
}
We want to deny access to the crazy.com domain, except for the host 10.1.2.3. Suppose that www.crazy.com administrator tries to compromise this restriction and defines another "fictitious" interface to www.crazy.com with the address 10.1.2.3. A user is trying to contact www.crazy.com. It resolves to two addresses, and one of them matches the first member of the list. However, this is not satisfactory for restrictive matching (used for DENY), the algorithm continues and the second member of the list is matched with a positive result and the access is denied.
Suppose another configuration:
ACL friend {
SERVER { [10.0.0.0/255.0.0.0] };
COMMAND * PERMIT;
}
We want to allow access to the A-class network 10. However, a host www.friend.com has another interface to another network. This is why connections to www.friend.com will not be allowed - not all its IPs will be flagged as POSITIVE during the matching process. (Of course, this rejection is not necessarily fatal - there can still be another ACL suitable for this host.) If we want to allow the host in this ACL, ALL of its IP addresses or its NAME must be present in the list. Connection to any IP address (not a hostname) within the network 10 will be granted.