From: Petr Špaček Date: Fri, 15 Mar 2019 16:23:57 +0000 (+0100) Subject: trust_anchors: document distrust and polish related docs X-Git-Tag: v4.0.0~15^2~20 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=aaff913c57254bf34fdee6d9f287e6c848e55d49;p=thirdparty%2Fknot-resolver.git trust_anchors: document distrust and polish related docs --- diff --git a/daemon/README.rst b/daemon/README.rst index 2bcd35bd9..9ffc5125d 100644 --- a/daemon/README.rst +++ b/daemon/README.rst @@ -423,8 +423,18 @@ policy, or automatically maintained by the resolver itself. .. function:: trust_anchors.config(keyfile, readonly) - Alias for `add_file`. It is also equivalent to CLI parameter ``-k `` - and ``trust_anchors.file = keyfile``. + Alias for `add_file`. Its use is discouraged and will be removed in future versions. + +.. function:: trust_anchors.distrust(zonename) + + Remove specified trust anchor from trusted key set. Removing trust anchor for the root zone effectivelly disables DNSSEC validation (unless you configured another trust anchor). + + .. code-block:: lua + + > trust_anchors.distrust('.') + true + + If you want to disable DNSSEC validation for a particular domain but keep it enabled for the rest of DNS tree, use :func:`trust_anchors.set_insecure`. .. envvar:: trust_anchors.keyfile_default = keyfile_default @@ -435,7 +445,7 @@ policy, or automatically maintained by the resolver itself. :return: int (default: 30 * day) - Modify RFC5011 hold-down timer to given value. Example: ``30 * sec`` + Modify RFC5011 hold-down timer to given value. Intended only for testing purposes. Example: ``30 * sec`` .. envvar:: trust_anchors.refresh_time = nil @@ -443,6 +453,7 @@ policy, or automatically maintained by the resolver itself. Modify RFC5011 refresh timer to given value (not set by default), this will force trust anchors to be updated every N seconds periodically instead of relying on RFC5011 logic and TTLs. + Intended only for testing purposes. Example: ``10 * sec`` .. envvar:: trust_anchors.keep_removed = 0 @@ -457,16 +468,15 @@ policy, or automatically maintained by the resolver itself. :param table nta_list: List of domain names (text format) representing NTAs. - When you use a domain name as an NTA, DNSSEC validation will be turned off at/below these names. + When you use a domain name as an *negative trust anchor* (NTA), DNSSEC validation will be turned off at/below these names. Each function call replaces the previous NTA set. You can find the current active set in ``trust_anchors.insecure`` variable. - - .. tip:: Use the `trust_anchors.negative = {}` alias for easier configuration. + If you want to disable DNSSEC validation completely use :func:`trust_anchors.distrust` function instead. Example output: .. code-block:: lua - > trust_anchors.negative = { 'bad.boy', 'example.com' } + > trust_anchors.set_insecure({ 'bad.boy', 'example.com' }) > trust_anchors.insecure [1] => bad.boy [2] => example.com @@ -481,6 +491,8 @@ policy, or automatically maintained by the resolver itself. Inserts DS/DNSKEY record(s) into current keyset. These will not be managed or updated, use it only for testing or if you have a specific use case for not using a keyfile. + .. note:: Static keys are very error-prone and should not be used in production. Use :func:`trust_anchors.add_file` instead. + Example output: .. code-block:: lua diff --git a/daemon/lua/trust_anchors.lua.in b/daemon/lua/trust_anchors.lua.in index e77cc3a6a..360fb5c70 100644 --- a/daemon/lua/trust_anchors.lua.in +++ b/daemon/lua/trust_anchors.lua.in @@ -369,7 +369,8 @@ local function add_file(path, unmanaged) end end -local function distrust(owner) +local function distrust(zname) + local owner = kres.str2dname(zname) if not trust_anchors.keysets[owner] then return false end diff --git a/daemon/lua/trust_anchors.test/ta.test.lua b/daemon/lua/trust_anchors.test/ta.test.lua index e8654b763..b9759b5f3 100644 --- a/daemon/lua/trust_anchors.test/ta.test.lua +++ b/daemon/lua/trust_anchors.test/ta.test.lua @@ -30,7 +30,7 @@ local function test_distrust() assert(root_ta ~= nil, 'we got non-NULL TA RRset') assert(root_ta.rrs.count, 1, 'we have a root TA set to be deleted') - trust_anchors.distrust('\0') + trust_anchors.distrust('.') same(trust_anchors.keysets['\0'], nil, 'Lua interface does not have the removed key') local root_ta = ffi.C.kr_ta_get(ta_c, '\0') diff --git a/modules/ta_update/ta_update.test.lua b/modules/ta_update/ta_update.test.lua index a986c88b0..8fc5399e5 100644 --- a/modules/ta_update/ta_update.test.lua +++ b/modules/ta_update/ta_update.test.lua @@ -40,7 +40,7 @@ local function test_ta_update_vs_trust_anchors_dependency() ok(modules.unload('ta_update'), 'module can be unloaded') same(ta_update, nil, 'unloaded module is nil') - ok(trust_anchors.distrust('\0'), 'managed root TA can be removed') + ok(trust_anchors.distrust('.'), 'managed root TA can be removed') same(trust_anchors.keysets['\0'], nil, 'TA removal works') end @@ -52,7 +52,7 @@ local function test_unloaded() worker.sleep(0.3) ok(counter == 0, 'TA is actually unmanaged') - ok(trust_anchors.distrust('\0'), 'unmanaged root TA can be removed') + ok(trust_anchors.distrust('.'), 'unmanaged root TA can be removed') same(trust_anchors.keysets['\0'], nil, 'TA removal works') end