All footnotes need to have unique name and be referenced
With Sphinx 8.1.0, footnotes can't stand on their own and have to be
referenced from somewhere, otherwise build fails, e.g.:
doc/dnssec-guide/signing.rst:1470: WARNING: Footnote [#] is not referenced. [ref.footnote]
(cherry picked from commit bdf8859e2d)
This commit is contained in:
@@ -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
|
||||
`<https://stats.labs.apnic.net/dnssec/XA>`__
|
||||
|
||||
@@ -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 <https://georgewbush-whitehouse.archives.gov/omb/memoranda/fy2008/m08-23.pdf>`__,
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user