From b5a8703fdb8e16f760bfb730df64f07173bb881d Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 5 Jan 2016 14:20:27 +0100 Subject: [PATCH] man: add documentation for dnssec-trust-anchors.d(5) --- Makefile-man.am | 14 ++- man/dnssec-trust-anchors.d.xml | 189 +++++++++++++++++++++++++++++++ man/resolved.conf.xml | 21 ++-- man/systemd-resolved.service.xml | 2 + 4 files changed, 216 insertions(+), 10 deletions(-) create mode 100644 man/dnssec-trust-anchors.d.xml diff --git a/Makefile-man.am b/Makefile-man.am index e91ecfdfdf..98769fbee8 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -1990,16 +1990,21 @@ endif if ENABLE_RESOLVED MANPAGES += \ + man/dnssec-trust-anchors.d.5 \ man/nss-resolve.8 \ man/resolved.conf.5 \ man/systemd-resolved.service.8 MANPAGES_ALIAS += \ man/libnss_resolve.so.2.8 \ man/resolved.conf.d.5 \ - man/systemd-resolved.8 + man/systemd-resolved.8 \ + man/systemd.negative.5 \ + man/systemd.positive.5 man/libnss_resolve.so.2.8: man/nss-resolve.8 man/resolved.conf.d.5: man/resolved.conf.5 man/systemd-resolved.8: man/systemd-resolved.service.8 +man/systemd.negative.5: man/dnssec-trust-anchors.d.5 +man/systemd.positive.5: man/dnssec-trust-anchors.d.5 man/libnss_resolve.so.2.html: man/nss-resolve.html $(html-alias) @@ -2009,6 +2014,12 @@ man/resolved.conf.d.html: man/resolved.conf.html man/systemd-resolved.html: man/systemd-resolved.service.html $(html-alias) +man/systemd.negative.html: man/dnssec-trust-anchors.d.html + $(html-alias) + +man/systemd.positive.html: man/dnssec-trust-anchors.d.html + $(html-alias) + endif if ENABLE_RFKILL @@ -2434,6 +2445,7 @@ EXTRA_DIST += \ man/coredumpctl.xml \ man/crypttab.xml \ man/daemon.xml \ + man/dnssec-trust-anchors.d.xml \ man/file-hierarchy.xml \ man/halt.xml \ man/hostname.xml \ diff --git a/man/dnssec-trust-anchors.d.xml b/man/dnssec-trust-anchors.d.xml new file mode 100644 index 0000000000..9a7cf3c881 --- /dev/null +++ b/man/dnssec-trust-anchors.d.xml @@ -0,0 +1,189 @@ + + + + + + + + dnssec-trust-anchors.d + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + dnssec-trust-anchors.d + 5 + + + + dnssec-trust-anchors.d + systemd.positive + systemd.negative + DNSSEC trust anchor configuration files + + + + /etc/dnssec-trust-anchors.d/*.positive + /run/dnssec-trust-anchors.d/*.positive + /usr/lib/dnssec-trust-anchors.d/*.positive + /etc/dnssec-trust-anchors.d/*.negative + /run/dnssec-trust-anchors.d/*.negative + /usr/lib/dnssec-trust-anchors.d/*.negative + + + + Description + + The DNSSEC trust anchor configuration files define positive + and negative trust anchors + systemd-resolved.service8 + bases DNSSEC integrity proofs on. + + + + Positive Trust Anchors + + Positive trust anchor configuration files contain DNSKEY and + DS resource record definitions to use as base for DNSSEC integrity + proofs. See RFC 4035, + Section 4.4 for more information about DNSSEC trust + anchors. + + Positive trust anchors are read from files with the suffix + .positive located in + /etc/dnssec-trust-anchors.d/, + /run/dnssec-trust-anchors.d/ and + /usr/lib/dnssec-trust-anchors.d/. These + directories are searched in the specified order, and a trust + anchor file of the same name in an earlier path overrides a trust + anchor files in a later path. To disable a trust anchor file + shipped in /usr/lib/dnssec-trust-anchors.d/ + it is sufficient to provide an identically-named file in + /etc/dnssec-trust-anchors.d/ or + /run/dnssec-trust-anchors.d/ that is either + empty or a symlink to /dev/null ("masked"). + + Positive trust anchor files are simple text files resembling + DNS zone files, as documented in RFC 1035, Section + 5. One DS or DNSKEY resource record may be listed per + line. Empty lines and lines starting with a semicolon + (;) are ignored and considered comments. A DS + resource record is specified like in the following example: + + . IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5 + + The first word specifies the domain, use + . for the root domain. The domain may be + specified with or without trailing dot, which is considered + equivalent. The second word must be IN the + third word DS. The following words specify the + key tag, signature algorithm, digest algorithm, followed by the + hex-encoded key fingerprint. See RFC 4034, + Section 5 for details about the precise syntax and meaning + of these fields. + + Alternatively, DNSKEY resource records may be used to define + trust anchors, like in the following example: + + . IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0= + + The first word specifies the domain again, the second word + must be IN, followed by + DNSKEY. The subsequent words encode the DNSKEY + flags, protocol and algorithm fields, followed by the key data + encoded in Base64. See See RFC 4034, + Section 2 for details about the precise syntax and meaning + of these fields. + + If multiple DS or DNSKEY records are defined for the same + domain (possibly even in different trust anchor files), all keys + are used and are considered equivalent as base for DNSSEC + proofs. + + Note that systemd-resolved will + automatically use a built-in trust anchor key for the Internet + root domain if no positive trust anchors are defined for the root + domain. In most cases it is hence unnecessary to define an + explicit key with trust anchor files. The built-in key is disabled + as soon as at least one trust anchor key for the root domain is + defined in trust anchor files. + + It is generally recommended to encode trust anchors in DS + resource records, rather than DNSKEY resource records. + + If a trust anchor specified via a DS record is found revoked + it is automatically removed from the trust anchor database for the + runtime. See RFC + 5011 for details about revoked trust anchors. Note that + systemd-resolved will not update its trust + anchor database from DNS servers automatically. Instead, it is + recommended to update the resolver software or update the new + trust anchor via adding in new trust anchor files. + + The current DNSSEC trust anchor for the Internet's root + domain is available a the IANA + Trust Anchor and Keys page. + + + + Negative Trust Anchors + + Negative trust anchors define domains where DNSSEC + validation shall be turned off. Negative trust anchor files are + found at the same location as positive trust anchor files, and + follow the same overriding rules. They are text files with the + .negative suffix. Empty lines and lines whose + first character is ; are ignored. Each line + specifies one domain name where DNSSEC validation shall be + disabled on. + + Negative trust anchors are useful to support private DNS + subtrees that are not referenced from the Internet DNS hierarchy, + and not signed. + + RFC + 7646 for details on negative trust anchors. + + + + See Also + + systemd1, + systemd-resolved.service8, + resolved.conf5 + + + + diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml index 857a93b653..8473bbe5c9 100644 --- a/man/resolved.conf.xml +++ b/man/resolved.conf.xml @@ -148,15 +148,17 @@ DNSSEC requires knowledge of "trust anchors" to prove data integrity. The trust anchor for the Internet root domain - is built into the resolver. However, trust anchors may change - in regular intervals, and old trust anchors may be revoked. In - such a case DNSSEC validation is not possible until new trust - anchors are configured locally or the resolver software - package is updated with the new root trust anchor. In effect, - when the built-in trust anchor is revoked and - DNSSEC= is true, all further lookups will - fail, as it cannot be proved anymore whether lookups are - correctly signed, or validly unsigned. If + is built into the resolver, additional trust anchors may be + defined with + dnssec-trust-anchors.d5. + Trust anchors may change in regular intervals, and old trust + anchors may be revoked. In such a case DNSSEC validation is + not possible until new trust anchors are configured locally or + the resolver software package is updated with the new root + trust anchor. In effect, when the built-in trust anchor is + revoked and DNSSEC= is true, all further + lookups will fail, as it cannot be proved anymore whether + lookups are correctly signed, or validly unsigned. If DNSSEC= is set to downgrade-ok the resolver will automatically turn of DNSSEC validation in such a case. @@ -188,6 +190,7 @@ systemd1, systemd-resolved.service8, systemd-networkd.service8, + dnssec-trust-anchors.d5, resolv.conf4 diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 10198812e1..8e1ca1c092 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -144,7 +144,9 @@ systemd1, resolved.conf5, + dnssec-trust-anchors.d5, nss-resolve8, + resolv.conf5, systemd.network5, systemd-networkd.service8