trust_anchors: document distrust and polish related docs

diff --git a/daemon/README.rst b/daemon/README.rst
index 2bcd35bd92c4fa0e7399b7d5c45d6404dfbcc9b2..9ffc5125de0afc4a5304e00d96383c19934e2de1 100644 (file)
--- 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 <keyfile>``
-   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 e77cc3a6a006b9de8598da1568ca4e3ff1f93e69..360fb5c701e6803fe512b6d4a2ddaff8d6b88ea1 100644 (file)
--- 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 e8654b76347c314306de8f7d7830357c075fff71..b9759b5f311b8bd2108c1db7bd5b92a9d1884187 100644 (file)
--- 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 a986c88b0b70cbfc90239b3e523128024ed7e3a6..8fc5399e524ce68a7bf83f9b7651827bafd3ede1 100644 (file)
--- 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