Query policies

This module can block, rewrite, or alter inbound queries based on user-defined policies.

Each policy rule has two parts: a filter and an action. A filter selects which queries will be affected by the policy, and action which modifies queries matching the associated filter.

Typically a rule is defined as follows: filter(action(action parameters), filter parameters). For example, a filter can be suffix which matches queries whose suffix part is in specified set, and one of possible actions is DENY, which denies resolution. These are combined together into policy.suffix(policy.DENY, {todname('badguy.example.')}). The rule is effective when it is added into rule table using policy.add(), please see Policy examples.

This module is enabled by default because it implements mandatory RFC 6761 logic. When no rule applies to a query, built-in rules for special-use and locally-served domain names are applied. These rules can be overriden by action PASS, see Policy examples below. For debugging purposes you can also add modules.unload('policy') to your config to unload the module.

Filters

A filter selects which queries will be affected by specified action. There are several policy filters available in the policy. table:

• all(action) - always applies the action
• pattern(action, pattern) - applies the action if QNAME matches a regular expression
• suffix(action, table) - applies the action if QNAME suffix matches one of suffixes in the table (useful for "is domain in zone" rules), uses Aho-Corasick string matching algorithm from CloudFlare (BSD 3-clause)
• :any:`policy.suffix_common`
• rpz(default_action, path) - implements a subset of RPZ in zonefile format. See below for details: :any:`policy.rpz`.
• custom filter function

Actions

An action is function which modifies DNS query, and is either of type chain or non-chain. So-called chain actions modify the query and allow other rules to evaluate and modify the same query. Non-chain actions have opposite behavior, i.e. modify the query and stop rule processing.

Resolver comes with several actions available in the policy. table:

Non-chain actions

Following actions stop the policy matching on the query, i.e. other rules are not evaluated once rule with following actions matches:

• PASS - let the query pass through; it's useful to make exceptions before wider rules
• DENY - reply NXDOMAIN authoritatively
• DENY_MSG(msg) - reply NXDOMAIN authoritatively and add explanatory message to additional section
• DROP - terminate query resolution and return SERVFAIL to the requestor
• REFUSE - terminate query resolution and return REFUSED to the requestor
• TC - set TC=1 if the request came through UDP, forcing client to retry with TCP
• FORWARD(ip) - resolve a query via forwarding to an IP while validating and caching locally
• TLS_FORWARD({{ip, authentication}}) - resolve a query via TLS connection forwarding to an IP while validating and caching locally
• STUB(ip) - similar to FORWARD(ip) but without attempting DNSSEC validation. Each request may be either answered from cache or simply sent to one of the IPs with proxying back the answer.
• REROUTE({{subnet,target}, ...}) - reroute addresses in response matching given subnet to given target, e.g. {'192.0.2.0/24', '127.0.0.0'} will rewrite '192.0.2.55' to '127.0.0.55', see :ref:`renumber module <mod-renumber>` for more information.

FORWARD, TLS_FORWARD and STUB support up to four IP addresses "in a single call".

Chain actions

Following actions allow to keep trying to match other rules, until a non-chain action is triggered:

• MIRROR(ip) - mirror query to given IP and continue solving it (useful for partial snooping).
• QTRACE - pretty-print DNS response packets into the log for the query and its sub-queries. It's useful for debugging weird DNS servers.
• FLAGS(set, clear) - set and/or clear some flags for the query. There can be multiple flags to set/clear. You can just pass a single flag name (string) or a set of names.

Also, it is possible to write your own action (i.e. Lua function). It is possible to implement complex heuristics, e.g. to deflect Slow drip DNS attacks or gray-list resolution of misbehaving zones.

Forwarding over TLS protocol (DNS-over-TLS)

Policy TLS_FORWARD allows you to forward queries using Transport Layer Security protocol, which hides the content of your queries from an attacker observing the network traffic. Further details about this protocol can be found in RFC 7858 and IETF draft dprive-dtls-and-tls-profiles.

Queries affected by TLS_FORWARD policy will always be resolved over TLS connection. Knot Resolver does not implement fallback to non-TLS connection, so if TLS connection cannot be established or authenticated according to the configuration, the resolution will fail.

To test this feature you need to either :ref:`configure Knot Resolver as DNS-over-TLS server <tls-server-config>`, or pick some public DNS-over-TLS server. Please see DNS Privacy Project homepage for list of public servers.

When multiple servers are specified, the one with the lowest round-trip time is used.

CA+hostname authentication

Traditional PKI authentication requires server to present certificate with specified hostname, which is issued by one of trusted CAs. Example policy is:

policy.TLS_FORWARD({
        {'2001:DB8::d0c', hostname='res.example.com'}})

• hostname must be a valid domain name matching server's certificate. It will also be sent to the server as SNI.
• ca_file optionally contains a path to a CA certificate (or certificate bundle) in PEM format. If you omit that, the system CA certificate store will be used instead (usually sufficient). A list of paths is also accepted, but all of them must be valid PEMs.

Key-pinned authentication

Instead of CAs, you can specify hashes of accepted certificates in pin_sha256. They are in the usual format -- base64 from sha256. You may still specify hostname if you want SNI to be sent.

TLS Examples

modules = { 'policy' }
-- forward all queries over TLS to the specified server
policy.add(policy.all(policy.TLS_FORWARD({{'192.0.2.1', pin_sha256='YQ=='}})))
-- for brevity, other TLS examples omit policy.add(policy.all())
-- single server authenticated using its certificate pin_sha256
  policy.TLS_FORWARD({{'192.0.2.1', pin_sha256='YQ=='}})  -- pin_sha256 is base64-encoded
-- single server authenticated using hostname and system-wide CA certificates
  policy.TLS_FORWARD({{'192.0.2.1', hostname='res.example.com'}})
-- single server using non-standard port
  policy.TLS_FORWARD({{'192.0.2.1@443', pin_sha256='YQ=='}})  -- use @ or # to specify port
-- single server with multiple valid pins (e.g. anycast)
  policy.TLS_FORWARD({{'192.0.2.1', pin_sha256={'YQ==', 'Wg=='}})
-- multiple servers, each with own authenticator
  policy.TLS_FORWARD({ -- please note that { here starts list of servers
        {'192.0.2.1', pin_sha256='Wg=='},
        -- server must present certificate issued by specified CA and hostname must match
        {'2001:DB8::d0c', hostname='res.example.com', ca_file='/etc/knot-resolver/tlsca.crt'}
})

Policy examples

-- Whitelist 'www[0-9].badboy.cz'
policy.add(policy.pattern(policy.PASS, '\4www[0-9]\6badboy\2cz'))
-- Block all names below badboy.cz
policy.add(policy.suffix(policy.DENY, {todname('badboy.cz.')}))

-- Custom rule
local ffi = require('ffi')
local function genRR (state, req)
        local answer = req.answer
        local qry = req:current()
        if qry.stype ~= kres.type.A then
                return state
        end
        ffi.C.kr_pkt_make_auth_header(answer)
        answer:rcode(kres.rcode.NOERROR)
        answer:begin(kres.section.ANSWER)
        answer:put(qry.sname, 900, answer:qclass(), kres.type.A, '\192\168\1\3')
        return kres.DONE
end
policy.add(policy.suffix(genRR, { todname('my.example.cz.') }))

-- Disallow ANY queries
policy.add(function (req, query)
        if query.stype == kres.type.ANY then
                return policy.DROP
        end
end)
-- Enforce local RPZ
policy.add(policy.rpz(policy.DENY, 'blacklist.rpz'))
-- Forward all queries below 'company.se' to given resolver;
-- beware: typically this won't work due to DNSSEC - see "Replacing part..." below
policy.add(policy.suffix(policy.FORWARD('192.168.1.1'), {todname('company.se')}))
-- Forward reverse queries about the 192.168.1.1/24 space to .1 port 5353
-- and do it directly without attempts to validate DNSSEC etc.
policy.add(policy.suffix(policy.STUB('192.168.1.1@5353'), {todname('1.168.192.in-addr.arpa')}))
-- Forward all queries matching pattern
policy.add(policy.pattern(policy.FORWARD('2001:DB8::1'), '\4bad[0-9]\2cz'))
-- Forward all queries (to public resolvers https://www.nic.cz/odvr)
policy.add(policy.all(policy.FORWARD({'2001:678:1::206', '193.29.206.206'})))
-- Print all responses with matching suffix
policy.add(policy.suffix(policy.QTRACE, {todname('rhybar.cz.')}))
-- Print all responses
policy.add(policy.all(policy.QTRACE))
-- Mirror all queries and retrieve information
local rule = policy.add(policy.all(policy.MIRROR('127.0.0.2')))
-- Print information about the rule
print(string.format('id: %d, matched queries: %d', rule.id, rule.count)
-- Reroute all addresses found in answer from 192.0.2.0/24 to 127.0.0.x
-- this policy is enforced on answers, therefore 'postrule'
local rule = policy.add(policy.REROUTE({'192.0.2.0/24', '127.0.0.0'}), true)
-- Delete rule that we just created
policy.del(rule.id)

Replacing part of the DNS tree

You may want to resolve most of the DNS namespace by usual means while letting some other resolver solve specific subtrees. Such data would typically be rejected by DNSSEC validation starting from the ICANN root keys. Therefore, if you trust the resolver and your link to it, you can simply use the STUB action instead of FORWARD to avoid validation only for those subtrees.

Another issue is caused by caching, because Knot Resolver only keeps a single cache for everything. For example, if you add an alternative top-level domain while using the ICANN root zone for the rest, at some point the cache may obtain records proving that your top-level domain does not exist, and those records could then be used when the positive records fall out of cache. The easiest work-around is to disable reading from cache for those subtrees; the other resolver is often very close anyway.

Additional properties

Most properties (actions, filters) are described above.