diff --git a/doc/dnssec-guide/advanced-discussions.rst b/doc/dnssec-guide/advanced-discussions.rst index 984435e5f4..2712f4f186 100644 --- a/doc/dnssec-guide/advanced-discussions.rst +++ b/doc/dnssec-guide/advanced-discussions.rst @@ -1009,13 +1009,14 @@ Below are a few challenges and disadvantages that DNSSEC faces. 6. *Not enough people are using it today*: While it's estimated (as of mid-2020) that roughly 30% of the global Internet DNS traffic is - validating [#]_ , that doesn't mean that many of the DNS zones are - actually signed. What this means is, even if your company's zone is - signed today, fewer than 30% of the Internet's servers are taking - advantage of this extra security. It gets worse: with less than 1.5% - of the ``com.`` domains signed, even if your DNSSEC validation is enabled today, - it's not likely to buy you or your users a whole lot more protection - until these popular domain names decide to sign their zones. + validating, [#apnic_validating_stats]_ that doesn't mean that many of + the DNS zones are actually signed. What this means is, even if your + company's zone is signed today, fewer than 30% of the Internet's + servers are taking advantage of this extra security. It gets worse: + with less than 1.5% of the ``com.`` domains signed, even if your + DNSSEC validation is enabled today, it's not likely to buy you or + your users a whole lot more protection until these popular domain + names decide to sign their zones. The last point may have more impact than you realize. Consider this: HTTP and HTTPS make up the majority of traffic on the Internet. While you may have @@ -1030,6 +1031,6 @@ CNAME to ``foo.random-cloud-provider.com``. As long as fully validate everything when they visit your web page and could be redirected elsewhere by a cache poisoning attack. -.. [#] +.. [#apnic_validating_stats] Based on APNIC statistics at ``__ diff --git a/doc/dnssec-guide/introduction.rst b/doc/dnssec-guide/introduction.rst index e8e70f0eda..8809445f2b 100644 --- a/doc/dnssec-guide/introduction.rst +++ b/doc/dnssec-guide/introduction.rst @@ -346,7 +346,7 @@ want to consider deploying DNSSEC: implementing DNSSEC, if your organization is subject to compliance standards that mandate it. For example, the US government set a deadline in 2008 to have all ``.gov`` subdomains signed by - December 2009 [#]_. So if you operate a subdomain in ``.gov``, you + December 2009. [#omb_memo]_ So if you operate a subdomain in ``.gov``, you must implement DNSSEC to be compliant. ICANN also requires that all new top-level domains support DNSSEC. @@ -369,7 +369,7 @@ want to consider deploying DNSSEC: infrastructure. To take a peek at these next-generation DNS features, check out :ref:`introduction_to_dane`. -.. [#] +.. [#omb_memo] The Office of Management and Budget (OMB) for the US government published `a memo in 2008 `__, diff --git a/doc/dnssec-guide/recipes.rst b/doc/dnssec-guide/recipes.rst index e961584d61..9f917ab6a3 100644 --- a/doc/dnssec-guide/recipes.rst +++ b/doc/dnssec-guide/recipes.rst @@ -560,7 +560,8 @@ since this new KSK is not active yet. You can do it immediately after the new DS record has been generated on December 1, or you can wait until the next day after you have verified that the new DNSKEY record is added to the zone. Below are some screenshots from -GoDaddy's web-based interface, used to add a new DS record [#]_. +GoDaddy's web-based interface, used to add a new DS record. +[#godaddy_iface_note]_ 1. After logging in, click the green "Launch" button next to the domain name you want to manage. @@ -761,7 +762,7 @@ Congratulations, the KSK rollover is complete! As for the actual key files (ending in ``.key`` and ``.private``), they may be deleted at this point, but they do not have to be. -.. [#] +.. [#godaddy_iface_note] The screenshots were taken from GoDaddy's interface at the time the original version of this guide was published (2015). It may have changed since then. diff --git a/doc/dnssec-guide/signing.rst b/doc/dnssec-guide/signing.rst index 3138e96430..9a2501eea3 100644 --- a/doc/dnssec-guide/signing.rst +++ b/doc/dnssec-guide/signing.rst @@ -439,8 +439,9 @@ Look for Signatures in Your Zone ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Another way to see if your zone data is signed is to check for the -presence of a signature. With DNSSEC, every record [#]_ now comes with at -least one corresponding signature, known as an RRSIG. +presence of a signature. With DNSSEC, every record +[#every_record_signed]_ now comes with at least one corresponding +signature, known as an RRSIG. :: @@ -552,7 +553,7 @@ containing the information we uploaded in ;; ANSWER SECTION: example.com. 61179 IN DS 10376 13 2 B92E22CAE0B41430EC38D3F7EDF1183C3A94F4D4748569250C15EE33B8312EF0 -.. [#] +.. [#every_record_signed] Well, almost every record: NS records and glue records for delegations do not have RRSIG records. If there are no delegations, then every record in your zone is @@ -885,7 +886,7 @@ Working with the Parent Zone (2) Once the zone is signed, the only required manual tasks are to monitor KSK or CSK key rolls and pass the new DS record to the parent zone. However, if the parent can process CDS or CDNSKEY records, -you may not even have to do that [#]_. +you may not even have to do that. [#parent_zone_security_considerations]_ When the time approaches for the roll of a KSK or CSK, BIND adds a CDS and a CDNSKEY record for the key in question to the apex of the @@ -939,7 +940,7 @@ your zone, presumably using the same mechanism you used to upload the records for the first time. Again, you need to use the :iscman:`rndc` tool to tell :iscman:`named` that the DS record has been published. -.. [#] +.. [#parent_zone_security_considerations] For security reasons, a parent zone that supports CDS/CDNSKEY may require the DS record to be manually uploaded when we first sign the zone. Until our zone is signed, the parent cannot be sure that a CDS or CDNSKEY @@ -1038,8 +1039,9 @@ ending in ``.private`` are the private keys, and contain the information that :iscman:`named` actually uses to sign the zone. Of the two pairs, one is the zone-signing key (ZSK), and one is the -key-signing key (KSK). We can tell which is which by looking at the file -contents (the actual keys are shortened here for ease of display): +key-signing key (KSK). [#signal_zone_presence]_ We can tell which is +which by looking at the file contents (the actual keys are shortened +here for ease of display): .. code-block:: console @@ -1089,11 +1091,13 @@ information in the key files, you can implement any DNSSEC policy you want for your zones. All the dates are the same, and are the date and time that -:iscman:`dnssec-keygen` created the key. We can use :iscman:`dnssec-settime` to -modify the dates [#]_. For example, to publish this key in -the zone on 1 July 2020, use it to sign records for a year starting on -15 July 2020, and remove it from the zone at the end of July 2021, we -can use the following command: +:iscman:`dnssec-keygen` created the key. We can use +:iscman:`dnssec-settime` to modify the dates. The dates can also be +modified using an editor, but that is likely to be more error-prone than +using :iscman:`dnssec-settime`. For example, to publish this key in the +zone on 1 July 2020, use it to sign records for a year starting on 15 +July 2020, and remove it from the zone at the end of July 2021, we can +use the following command: .. code-block:: console @@ -1193,11 +1197,7 @@ Finally, we should note that the :iscman:`dnssec-keygen` command supports the same set of switches so we could have set the dates when we created the key. -.. [#] - The dates can also be modified using an editor, but that is likely to - be more error-prone than using :iscman:`dnssec-settime`. - -.. [#] +.. [#signal_zone_presence] Only one key file - for either a KSK or ZSK - is needed to signal the presence of the zone. :iscman:`dnssec-keygen` creates files of both types as needed. diff --git a/doc/dnssec-guide/validation.rst b/doc/dnssec-guide/validation.rst index 8d069327fe..9ad528d85b 100644 --- a/doc/dnssec-guide/validation.rst +++ b/doc/dnssec-guide/validation.rst @@ -76,13 +76,13 @@ not loading; or the web browser returning an error message indicating that the page cannot be displayed. For example, if root name servers were misconfigured with the wrong information about ``.org``, it could cause all validation for ``.org`` domains to fail. To end -users, it would appear that all ``.org`` web -sites were out of service [#]_. Should you encounter DNSSEC-related problems, don't be -tempted to disable validation; there is almost certainly a solution that -leaves validation enabled. A basic troubleshooting guide can be found in -:ref:`dnssec_troubleshooting`. +users, it would appear that all ``.org`` web sites were out of service. +[#wrong_root_addr]_ Should you encounter DNSSEC-related problems, don't +be tempted to disable validation; there is almost certainly a solution +that leaves validation enabled. A basic troubleshooting guide can be +found in :ref:`dnssec_troubleshooting`. -.. [#] +.. [#wrong_root_addr] Of course, something like this could happen for reasons other than DNSSEC: for example, the root publishing the wrong addresses for the ``.org`` nameservers. @@ -400,7 +400,7 @@ Let's discuss the difference between *yes* and *auto*. If set to using the :any:`trust-anchors` statement (with either the ``static-key`` or ``static-ds`` modifier) in the configuration file; if set to *auto* (the default, and as shown in the example), then no further -action should be required as BIND includes a copy [#]_ of the root key. +action should be required as BIND includes a copy [#root_zone_key_update]_ of the root key. When set to *auto*, BIND automatically keeps the keys (also known as trust anchors, discussed in :ref:`trust_anchors_description`) up-to-date without intervention from the DNS administrator. @@ -646,7 +646,7 @@ If you followed the recommendation in :ref:`easy_start_guide_for_recursive_servers`, by setting :any:`dnssec-validation` to *auto*, there is nothing left to do. BIND already includes a copy of the root key, and automatically updates it -when the root key changes. [#]_ It looks something like this: +when the root key changes. [#root_zone_key_update]_ It looks something like this: :: @@ -715,7 +715,7 @@ the top-level domains have been signed, including all the largest ones. Unless you have a particular need to manage keys yourself, it is best to use the BIND defaults and let the software manage the root key. -.. [#] +.. [#root_zone_key_update] The root zone was signed in July 2010 and, as at the time of this writing (mid-2020), the key has been changed once, in October 2018. The intention going forward is to roll the key once every five years.