The only tool shipped with BIND 9 that generates SIG(0) signed messages
is ``nsupdate``.
-.. _DNSSEC:
-
-DNSSEC
-------
-
-Cryptographic authentication of DNS information is possible through the
-DNS Security ("DNSSEC-bis") extensions, defined in :rfc:`4033`, :rfc:`4034`,
-and :rfc:`4035`. This section describes the creation and use of DNSSEC
-signed zones.
-
-In order to set up a DNSSEC secure zone, there are a series of steps
-which must be followed. BIND 9 ships with several tools that are used in
-this process, which are explained in more detail below. In all cases,
-the ``-h`` option prints a full list of parameters. Note that the DNSSEC
-tools require the keyset files to be in the working directory or the
-directory specified by the ``-d`` option.
-
-There must also be communication with the administrators of the parent
-and/or child zone to transmit keys. A zone's security status must be
-indicated by the parent zone for a DNSSEC-capable resolver to trust its
-data. This is done through the presence or absence of a ``DS`` record at
-the delegation point.
-
-For other servers to trust data in this zone, they must be
-statically configured with either this zone's zone key or the zone key of
-another zone above this one in the DNS tree.
-
-.. _generating_dnssec_keys:
-
-Generating Keys
-~~~~~~~~~~~~~~~
-
-The ``dnssec-keygen`` program is used to generate keys.
-
-A secure zone must contain one or more zone keys. The zone keys
-sign all other records in the zone, as well as the zone keys of any
-secure delegated zones. Zone keys must have the same name as the zone, have a
-name type of ``ZONE``, and be usable for authentication. It is
-recommended that zone keys use a cryptographic algorithm designated as
-"mandatory to implement" by the IETF. Currently there are two algorithms,
-RSASHA256 and ECDSAP256SHA256; ECDSAP256SHA256 is recommended for
-current and future deployments.
-
-The following command generates an ECDSAP256SHA256 key for the
-``child.example`` zone:
-
-``dnssec-keygen -a ECDSAP256SHA256 -n ZONE child.example.``
-
-Two output files are produced: ``Kchild.example.+013+12345.key`` and
-``Kchild.example.+013+12345.private`` (where 12345 is an example of a
-key tag). The key filenames contain the key name (``child.example.``),
-the algorithm (5 is RSASHA1, 8 is RSASHA256, 13 is ECDSAP256SHA256, 15 is
-ED25519, etc.), and the key tag (12345 in this case). The private key (in
-the ``.private`` file) is used to generate signatures, and the public
-key (in the ``.key`` file) is used for signature verification.
-
-To generate another key with the same properties but with a different
-key tag, repeat the above command.
-
-The ``dnssec-keyfromlabel`` program is used to get a key pair from a
-crypto hardware device and build the key files. Its usage is similar to
-``dnssec-keygen``.
-
-The public keys should be inserted into the zone file by including the
-``.key`` files using ``$INCLUDE`` statements.
-
-.. _dnssec_zone_signing:
-
-Signing the Zone
-~~~~~~~~~~~~~~~~
-
-The ``dnssec-signzone`` program is used to sign a zone.
-
-Any ``keyset`` files corresponding to secure sub-zones should be
-present. The zone signer generates ``NSEC``, ``NSEC3``, and ``RRSIG``
-records for the zone, as well as ``DS`` for the child zones if ``-g``
-is specified. If ``-g`` is not specified, then DS RRsets for the
-secure child zones need to be added manually.
-
-By default, all zone keys which have an available private key are used
-to generate signatures. The following command signs the zone, assuming
-it is in a file called ``zone.child.example``:
-
-``dnssec-signzone -o child.example zone.child.example``
-
-One output file is produced: ``zone.child.example.signed``. This file
-should be referenced by ``named.conf`` as the input file for the zone.
-
-``dnssec-signzone`` also produces keyset and dsset files. These are used
-to provide the parent zone administrators with the ``DNSKEYs`` (or their
-corresponding ``DS`` records) that are the secure entry point to the zone.
-
-.. _dnssec_config:
-
-Configuring Servers for DNSSEC
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To enable ``named`` to validate answers received from other servers, the
-``dnssec-validation`` option must be set to either ``yes`` or ``auto``.
-
-When ``dnssec-validation`` is set to ``auto``, a trust anchor for the
-DNS root zone is automatically used. This trust anchor is provided
-as part of BIND and is kept up to date using :rfc:`5011` key management.
-
-When ``dnssec-validation`` is set to ``yes``, DNSSEC validation
-only occurs if at least one trust anchor has been explicitly configured
-in ``named.conf``, using a ``trust-anchors`` statement (or the
-``managed-keys`` and ``trusted-keys`` statements, both deprecated).
-
-When ``dnssec-validation`` is set to ``no``, DNSSEC validation does not
-occur.
-
-The default is ``auto`` unless BIND is built with
-``configure --disable-auto-validation``, in which case the default is
-``yes``.
-
-The keys specified in ``trust-anchors`` are copies of DNSKEY RRs for zones that are
-used to form the first link in the cryptographic chain of trust. Keys configured
-with the keyword ``static-key`` or ``static-ds`` are loaded directly into the
-table of trust anchors, and can only be changed by altering the
-configuration. Keys configured with ``initial-key`` or ``initial-ds`` are used
-to initialize :rfc:`5011` trust anchor maintenance, and are kept up-to-date
-automatically after the first time ``named`` runs.
-
-``trust-anchors`` is described in more detail later in this document.
-
-BIND 9 does not verify signatures on load, so zone keys
-for authoritative zones do not need to be specified in the configuration
-file.
-
-After DNSSEC is established, a typical DNSSEC configuration looks
-something like the following. It has one or more public keys for the
-root, which allows answers from outside the organization to be validated.
-It also has several keys for parts of the namespace that the
-organization controls. These are here to ensure that ``named`` is immune
-to compromised security in the DNSSEC components of parent zones.
-
-::
-
- trust-anchors {
- /* Root Key */
- "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS
- JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh
- aBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3zy2Xy
- 4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYg
- hf+6fElrmLkdaz MQ2OCnACR817DF4BBa7UR/beDHyp
- 5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M/lUUVRbke
- g1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq
- 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ
- 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ
- dgxbcDTClU0CRBdiieyLMNzXG3";
- /* Key for our organization's forward zone */
- example.com. static-ds 54135 5 2 "8EF922C97F1D07B23134440F19682E7519ADDAE180E20B1B1EC52E7F58B2831D"
-
- /* Key for our reverse zone. */
- 2.0.192.IN-ADDRPA.NET. static-key 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc
- xOdNax071L18QqZnQQQAVVr+i
- LhGTnNGp3HoWQLUIzKrJVZ3zg
- gy3WwNT6kZo6c0tszYqbtvchm
- gQC8CzKojM/W16i6MG/eafGU3
- siaOdS0yOI6BgPsw+YZdzlYMa
- IJGf4M4dyoKIhzdZyQ2bYQrjy
- Q4LB0lC7aOnsMyYKHHYeRvPxj
- IQXmdqgOJGq+vsevG06zW+1xg
- YJh9rCIfnm1GX/KMgxLPG2vXT
- D/RnLX+D3T3UL7HJYHJhAZD5L
- 59VvjSPsZJHeDCUyWYrvPZesZ
- DIRvhDD52SKvbheeTJUm6Ehkz
- ytNN2SN96QRk8j/iI8ib";
- };
-
- options {
- ...
- dnssec-validation yes;
- };
-
-..
-
-.. note::
-
- None of the keys listed in this example are valid. In particular, the
- root key is not valid.
-
-When DNSSEC validation is enabled and properly configured, the resolver
-rejects any answers from signed, secure zones which fail to
-validate, and returns SERVFAIL to the client.
-
-Responses may fail to validate for any of several reasons, including
-missing, expired, or invalid signatures, a key which does not match the
-DS RRset in the parent zone, or an insecure response from a zone which,
-according to its parent, should have been secure.
-
-.. note::
-
- When the validator receives a response from an unsigned zone that has
- a signed parent, it must confirm with the parent that the zone was
- intentionally left unsigned. It does this by verifying, via signed
- and validated NSEC/NSEC3 records, that the parent zone contains no DS
- records for the child.
-
- If the validator *can* prove that the zone is insecure, then the
- response is accepted. However, if it cannot, the validator must assume an
- insecure response to be a forgery; it rejects the response and logs
- an error.
-
- The logged error reads "insecurity proof failed" and "got insecure
- response; parent indicates it should be secure."
-
-
-.. include:: dnssec.rst
.. include:: managed-keys.rst
.. include:: pkcs11.rst
.. include:: dlz.rst
--- /dev/null
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0. If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. _dnssec:
+
+DNSSEC
+------
+DNS Security Extensions (DNSSEC) provide reliable protection from
+`cache poisoning`_ attacks. At the same time these extensions also provide other benefits:
+they limit the impact of `random subdomain attacks`_ on resolver caches and authoritative
+servers, and provide the foundation for modern applications like `authenticated
+and private e-mail transfer`_.
+
+To achieve this goal, DNSSEC adds `digital signatures`_ to DNS records in
+authoritative DNS zones, and DNS resolvers verify the validity of the signatures on the
+received records. If the signatures match the received data, the resolver can
+be sure that the data was not modified in transit.
+
+.. note::
+ DNSSEC and transport-level encryption are complementary!
+ Unlike typical transport-level encryption like DNS-over-TLS, DNS-over-HTTPS,
+ or VPN, DNSSEC makes DNS records verifiable at all points of the DNS
+ resolution chain.
+
+This section focuses on ways to deploy DNSSEC using BIND. For a more in-depth
+discussion of DNSSEC principles (e.g. :ref:`how_does_dnssec_change_dns_lookup`)
+please see :doc:`dnssec-guide`.
+
+.. _`cache poisoning`: https://en.wikipedia.org/wiki/DNS_cache_poisoning
+.. _`random subdomain attacks`: https://www.isc.org/blogs/nsec-caching-should-limit-excessive-queries-to-dns-root/
+.. _`digital signatures`: https://en.wikipedia.org/wiki/Digital_signature
+.. _`authenticated and private e-mail transfer`: https://github.com/internetstandards/toolbox-wiki/blob/main/DANE-for-SMTP-how-to.md
+
+
+.. _dnssec_zone_signing:
+
+Zone Signing
+~~~~~~~~~~~~
+
+BIND offers several ways to generate signatures and maintain their validity
+during the lifetime of a DNS zone:
+
+ - :ref:`dnssec_kasp` - **strongly recommended**
+ - :ref:`dnssec_dynamic_zones` - only for special needs
+ - :ref:`dnssec_tools` - discouraged, use only for debugging
+
+.. _zone_keys:
+
+Zone keys
+^^^^^^^^^
+Regardless of the :ref:`zone-signing <dnssec_zone_signing>` method in use, cryptographic keys are
+stored in files named like :file:`Kdnssec.example.+013+12345.key` and
+:file:`Kdnssec.example.+013+12345.private`.
+The private key (in the ``.private`` file) is used to generate signatures, and
+the public key (in the ``.key`` file) is used for signature verification.
+Additionally, the :ref:`dnssec_kasp` method creates a third file,
+:file:`Kdnssec.example+013+12345.state`, which is used to track DNSSEC key timings
+and to perform key rollovers safely.
+
+These filenames contain:
+
+ - the key name, which always matches the zone name (``dnssec.example.``),
+ - the `algorithm number`_ (013 is ECDSAP256SHA256, 008 is RSASHA256, etc.),
+ - and the key tag, i.e. a non-unique key identifier (12345 in this case).
+
+.. _`algorithm number`: https://www.iana.org/assignments/dns-sec-alg-numbers/dns-sec-alg-numbers.xhtml#dns-sec-alg-numbers-1
+
+
+.. warning::
+ Private keys are required for full disaster recovery. Back up key files in a
+ safe location and protect them from unauthorized access. Anyone with
+ access to the private key can create fake but seemingly valid DNS data.
+
+
+.. _dnssec_kasp:
+
+Fully Automated (Key and Signing Policy)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Key and Signing Policy (KASP) is a method of configuration that describes
+how to maintain DNSSEC signing keys and how to sign the zone.
+
+This is the recommended, fully automated way to sign and maintain DNS zones. For
+most use cases users can simply use the built-in default policy, which applies
+up-to-date DNSSEC practices:
+
+.. code-block:: none
+ :emphasize-lines: 4
+
+ zone "dnssec.example" {
+ type primary;
+ file "dnssec.example.db";
+ dnssec-policy default;
+ };
+
+This single line is sufficient to create the necessary signing keys, and generate
+``DNSKEY``, ``RRSIG``, and ``NSEC`` records for the zone. BIND also takes
+care of any DNSSEC maintenance for this zone, including replacing signatures
+that are about to expire and managing :ref:`key_rollovers`.
+
+.. note::
+ ``dnssec-policy`` needs write access to the zone. Please see
+ :ref:`dnssec_policy` for more details about implications for zone storage.
+
+The default policy creates one key that is used to sign the complete zone,
+and uses ``NSEC`` to enable authenticated denial of existence (a secure way
+to tell which records do not exist in a zone). This policy is recommended
+and typically does not need to be changed.
+
+If needed, a custom policy can be defined by adding a ``dnssec-policy`` statement
+into the configuration:
+
+.. code-block:: none
+
+
+ dnssec-policy "custom" {
+ dnskey-ttl 600;
+ keys {
+ ksk lifetime P1Y algorithm ecdsap384sha384;
+ zsk lifetime 60d algorithm ecdsap384sha384;
+ };
+ nsec3param iterations 0 optout no salt-length 0;
+ };
+
+This ``custom`` policy, for example:
+
+ - uses a very short ``DNSKEY`` TTL (600 seconds),
+ - uses two keys to sign the zone: a Key Signing Key (KSK) to sign the key
+ related RRsets (``DNSKEY``, ``CDS``, and ``CDNSKEY``), and a Zone Signing
+ Key (ZSK) to sign the rest of the zone. The KSK is automatically
+ rotated after one year and the ZSK after 60 days.
+
+Also:
+ - The configured keys have a lifetime set and use the ECDSAP384SHA384
+ algorithm.
+ - The last line instructs BIND to generate NSEC3 records for
+ :ref:`Proof of Non-Existence <advanced_discussions_proof_of_nonexistence>`,
+ using zero extra iterations and no salt. NSEC3 opt-out is disabled, meaning
+ insecure delegations also get an NSEC3 record.
+
+For more information about KASP configuration see :ref:`dnssec_policy_grammar`.
+
+The :ref:`dnssec_advanced_discussions` section in the DNSSEC Guide discusses the
+various policy settings and may be useful for determining values for specific
+needs.
+
+Key Rollover
+============
+
+When using a ``dnssec-policy``, a key lifetime can be set to trigger
+key rollovers. ZSK rollovers are fully automatic, but for KSK and CSK rollovers
+a DS record needs to be submitted to the parent. See
+:ref:`secure_delegation` for possible ways to do so.
+
+Once the DS is in the parent (and the DS of the predecessor key is withdrawn),
+BIND needs to be told that this event has happened. This can be done automatically
+by configuring parental agents:
+
+.. code-block:: none
+ :emphasize-lines: 5
+
+ zone "dnssec.example" {
+ type primary;
+ file "dnssec.example.db";
+ dnssec-policy default;
+ parental-agents { 192.0.2.1; };
+ };
+
+Here one server, ``192.0.2.1``, is configured for BIND to send DS queries to,
+to check the DS RRset for ``dnssec-example`` during key rollovers. This needs
+to be a trusted server, because BIND does not validate the response.
+
+If setting up a parental agent is undesirable, it is also possible to tell BIND that the
+DS is published in the parent with:
+:option:`rndc dnssec -checkds -key 12345 published dnssec.example. <rndc dnssec>`.
+and the DS for the predecessor key has been removed with:
+:option:`rndc dnssec -checkds -key 54321 withdrawn dnssec.example. <rndc dnssec>`.
+where 12345 and 54321 are the key tags of the successor and predecessor key,
+respectively.
+
+To roll a key sooner than scheduled, or to roll a key that
+has an unlimited lifetime, use:
+:option:`rndc dnssec -rollover -key 12345 dnssec.example. <rndc dnssec>`.
+
+To revert a signed zone back to an insecure zone, change
+the zone configuration to use the built-in "insecure" policy. Detailed
+instructions are described in :ref:`revert_to_unsigned`.
+
+.. _dnssec_dynamic_zones:
+
+Manual Key Management
+^^^^^^^^^^^^^^^^^^^^^
+
+.. warning::
+ The method described here allows full control over the keys used to sign
+ the zone. This is required only for very special cases and is generally
+ discouraged. Under normal circumstances, please use :ref:`dnssec_kasp`.
+
+
+.. _dnssec_dynamic_zones_multisigner_model:
+
+Multi-Signer Model
+==================
+
+Dynamic zones provide the ability to sign a zone by multiple providers, meaning
+each provider signs and serves the same zone independently. Such a setup requires
+some coordination between providers when it comes to key rollovers, and may be
+better suited to be configured with ``auto-dnssec allow;``. This permits keys to
+be updated and the zone to be re-signed only if the user issues the command
+:option:`rndc sign zonename <rndc sign>`.
+
+A zone can also be configured with ``auto-dnssec maintain``, which automatically
+adjusts the zone's DNSSEC keys on a schedule according to the key timing
+metadata. However, keys still need to be generated separately, for
+example with :iscman:`dnssec-keygen`.
+
+Of course, dynamic zones can also use ``dnssec-policy`` to fully automate DNSSEC
+maintenance. The next sections assume that more key
+management control is needed, and describe how to use dynamic DNS update to perform
+various DNSSEC operations.
+
+.. _dnssec_dynamic_zones_enabling_dnssec:
+
+Enabling DNSSEC Manually
+========================
+As an alternative to fully automated zone signing using :ref:`dnssec-policy
+<dnssec_kasp>`, a zone can be changed from insecure to secure using a dynamic
+DNS update. :iscman:`named` must be configured so that it can see the ``K*``
+files which contain the public and private parts of the `zone keys`_ that are
+used to sign the zone. Key files should be placed in the ``key-directory``, as
+specified in :iscman:`named.conf`:
+
+::
+
+ zone update.example {
+ type primary;
+ update-policy local;
+ auto-dnssec allow;
+ file "dynamic/update.example.db";
+ key-directory "keys/update.example/";
+ };
+
+If there are both a KSK and a ZSK available (or a CSK), this configuration causes the
+zone to be signed. An ``NSEC`` chain is generated as part of the initial signing
+process.
+
+In any secure zone which supports dynamic updates, :iscman:`named` periodically
+re-signs RRsets which have not been re-signed as a result of some update action.
+The signature lifetimes are adjusted to spread the re-sign load over time rather
+than all at once.
+
+.. _dnssec_dynamic_zones_publishing_dnskey_records:
+
+Publishing DNSKEY Records
+=========================
+
+To insert the keys via dynamic update:
+
+::
+
+ % nsupdate
+ > ttl 3600
+ > update add update.example DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
+ > update add update.example DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
+ > send
+
+In order to sign with these keys, the corresponding key files should also be
+placed in the ``key-directory``.
+
+.. _dnssec_dynamic_zones_nsec3:
+
+NSEC3
+=====
+
+To sign using :ref:`NSEC3 <advanced_discussions_nsec3>` instead of :ref:`NSEC
+<advanced_discussions_nsec>`, add an NSEC3PARAM record to the initial update
+request. The :term:`OPTOUT <opt-out>` bit in the NSEC3
+chain can be set in the flags field of the
+NSEC3PARAM record.
+
+::
+
+ % nsupdate
+ > ttl 3600
+ > update add update.example DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
+ > update add update.example DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
+ > update add update.example NSEC3PARAM 1 0 0 -
+ > send
+
+Note that the ``NSEC3PARAM`` record does not show up until :iscman:`named` has
+had a chance to build/remove the relevant chain. A private type record is
+created to record the state of the operation (see below for more details), and
+is removed once the operation completes.
+
+The ``NSEC3`` chain is generated and the ``NSEC3PARAM`` record is added before
+the ``NSEC`` chain is destroyed.
+
+While the initial signing and ``NSEC``/``NSEC3`` chain generation are occurring,
+other updates are possible as well.
+
+A new ``NSEC3PARAM`` record can be added via dynamic update. When the new
+``NSEC3`` chain has been generated, the ``NSEC3PARAM`` flag field is set to
+zero. At that point, the old ``NSEC3PARAM`` record can be removed. The old
+chain is removed after the update request completes.
+
+:iscman:`named` only supports creating new ``NSEC3`` chains where all the
+``NSEC3`` records in the zone have the same ``OPTOUT`` state. :iscman:`named`
+supports updates to zones where the ``NSEC3`` records in the chain have mixed
+``OPTOUT`` state. :iscman:`named` does not support changing the ``OPTOUT``
+state of an individual ``NSEC3`` record; if the ``OPTOUT`` state of an
+individual ``NSEC3`` needs to be changed, the entire chain must be changed.
+
+To switch back to ``NSEC``, use :iscman:`nsupdate` to remove any ``NSEC3PARAM``
+records. The ``NSEC`` chain is generated before the ``NSEC3`` chain is removed.
+
+.. _dnssec_dynamic_zones_dnskey_rollovers:
+
+DNSKEY Rollovers
+================
+
+To perform key rollovers via a dynamic update, the ``K*`` files for the new keys
+must be added so that :iscman:`named` can find them. The new ``DNSKEY`` RRs can
+then be added via dynamic update. When the zones are being signed, they are
+signed with the new key set; when the signing is complete, the private type
+records are updated so that the last octet is non-zero.
+
+If this is for a KSK, the parent and any trust anchor repositories of the new
+KSK must be informed.
+
+The maximum TTL in the zone must expire before removing the old ``DNSKEY``. If
+it is a KSK that is being updated, the DS RRset in the parent must also be
+updated and its TTL allowed to expire. This ensures that all clients are able to
+verify at least one signature when the old ``DNSKEY`` is removed.
+
+The old ``DNSKEY`` can be removed via ``UPDATE``, taking care to specify the
+correct key. :iscman:`named` cleans out any signatures generated by the old
+key after the update completes.
+
+.. _dnssec_dynamic_zones_going_insecure:
+
+Going Insecure
+==============
+
+To convert a signed zone to unsigned using dynamic DNS, delete all the
+``DNSKEY`` records from the zone apex using :iscman:`nsupdate`. All signatures,
+``NSEC`` or ``NSEC3`` chains, and associated ``NSEC3PARAM`` records are removed
+automatically when the zone is supposed to be re-signed.
+
+This requires the ``dnssec-secure-to-insecure`` option to be set to ``yes`` in
+:iscman:`named.conf`.
+
+In addition, if the ``auto-dnssec maintain`` or a ``dnssec-policy`` is used, it
+should be removed or changed to ``allow`` instead; otherwise it will re-sign.
+
+.. _dnssec_tools:
+
+Manual Signing
+^^^^^^^^^^^^^^
+
+There are several tools available to manually sign a zone.
+
+.. warning::
+
+ Please note manual procedures are available mainly for backwards
+ compatibility and should be used only by expert users with specific needs.
+
+To set up a DNSSEC secure zone manually, a series of steps
+must be followed. Please see chapter
+:ref:`advanced_discussions_manual_key_management_and_signing` in the
+:doc:`dnssec-guide` for more information.
+
+Monitoring with Private Type Records
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The state of the signing process is signaled by private type records (with a
+default type value of 65534). When signing is complete, those records with a
+non-zero initial octet have a non-zero value for the final octet.
+
+If the first octet of a private type record is non-zero, the record indicates
+either that the zone needs to be signed with the key matching the record, or
+that all signatures that match the record should be removed. Here are the
+meanings of the different values of the first octet:
+
+ - algorithm (octet 1)
+
+ - key ID in network order (octet 2 and 3)
+
+ - removal flag (octet 4)
+
+ - complete flag (octet 5)
+
+Only records flagged as "complete" can be removed via dynamic update; attempts
+to remove other private type records are silently ignored.
+
+If the first octet is zero (this is a reserved algorithm number that should
+never appear in a ``DNSKEY`` record), the record indicates that changes to the
+``NSEC3`` chains are in progress. The rest of the record contains an
+``NSEC3PARAM`` record, while the flag field tells what operation to perform
+based on the flag bits:
+
+ 0x01 OPTOUT
+
+ 0x80 CREATE
+
+ 0x40 REMOVE
+
+ 0x20 NONSEC
+
+.. _secure_delegation:
+
+Secure Delegation
+~~~~~~~~~~~~~~~~~
+
+Once a zone is signed on the authoritative servers, the last remaining step
+is to establish chain of trust [#validation]_ between the parent zone
+(``example.``) and the local zone (``dnssec.example.``).
+
+Generally the procedure is:
+
+ - **Wait** for stale data to expire from caches. The amount of time required
+ is equal to the maximum TTL value used in the zone before signing. This
+ step ensures that unsigned data expire from caches and resolvers do not get
+ confused by missing signatures.
+ - Insert/update DS records in the parent zone (``dnssec.example. DS`` record).
+
+There are multiple ways to update DS records in the parent zone. Refer to the
+documentation for the parent zone to find out which options are applicable to
+a given case zone. Generally the options are, from most- to least-recommended:
+
+ - Automatically update the DS record in the parent zone using
+ ``CDS``/``CDNSKEY`` records automatically generated by BIND. This requires
+ support for :rfc:`7344` in either parent zone, registry, or registrar. In
+ that case, configure BIND to :ref:`monitor DS records in the parent
+ zone <cds_cdnskey>` and everything will happen automatically at the right
+ time.
+ - Query the zone for automatically generated ``CDS`` or ``CDNSKEY`` records using
+ :iscman:`dig`, and then insert these records into the parent zone using
+ the method specified by the parent zone (web form, e-mail, API, ...).
+ - Generate DS records manually using the :iscman:`dnssec-dsfromkey` utility on
+ `zone keys`_, and then insert them into the parent zone.
+
+.. [#validation] For further details on how the chain of trust is used in practice, see
+ :ref:`dnssec_12_steps` in the :doc:`dnssec-guide`.
+
+
+
+DNSSEC Validation
+~~~~~~~~~~~~~~~~~
+
+The BIND resolver validates answers from authoritative servers by default. This
+behavior is controlled by the configuration statement :ref:`dnssec-validation
+<dnssec-validation-option>`.
+
+By default a trust anchor for the DNS root zone is used.
+This trust anchor is provided as part of BIND and is kept up-to-date using
+:ref:`rfc5011.support`.
+
+.. note::
+ DNSSEC validation works "out of the box" and does not require
+ additional configuration. Additional configuration options are intended only
+ for special cases.
+
+To validate answers, the resolver needs at least one trusted starting point,
+a "trust anchor." Essentially, trust anchors are copies of ``DNSKEY`` RRs for
+zones that are used to form the first link in the cryptographic chain of trust.
+Alternative trust anchors can be specified using :ref:`trust_anchors`, but
+this setup is very unusual and is recommended only for expert use.
+For more information, see :ref:`trust_anchors_description` in the
+:doc:`dnssec-guide`.
+
+The BIND authoritative server does not verify signatures on load, so zone keys
+for authoritative zones do not need to be specified in the configuration
+file.
+
+Validation Failures
+^^^^^^^^^^^^^^^^^^^
+
+When DNSSEC validation is configured, the resolver rejects any answers from
+signed, secure zones which fail to validate, and returns SERVFAIL to the
+client.
+
+Responses may fail to validate for any of several reasons, including
+missing, expired, or invalid signatures; a key which does not match the
+DS RRset in the parent zone; or an insecure response from a zone which,
+according to its parent, should have been secure.
+
+For more information see :ref:`dnssec_troubleshooting`.
+
+Coexistence With Unsigned (Insecure) Zones
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Zones not protected by DNSSEC are called "insecure," and these zones seamlessly
+coexist with signed zones.
+
+When the validator receives a response from an unsigned zone that has
+a signed parent, it must confirm with the parent that the zone was
+intentionally left unsigned. It does this by verifying, via signed
+and validated :ref:`NSEC/NSEC3 records
+<advanced_discussions_proof_of_nonexistence>`, that the parent zone contains no
+DS records for the child.
+
+If the validator *can* prove that the zone is insecure, then the
+response is accepted. However, if it cannot, the validator must assume an
+insecure response to be a forgery; it rejects the response and logs
+an error.
+
+The logged error reads "insecurity proof failed" and "got insecure
+response; parent indicates it should be secure."
+++ /dev/null
-.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
-..
-.. SPDX-License-Identifier: MPL-2.0
-..
-.. This Source Code Form is subject to the terms of the Mozilla Public
-.. License, v. 2.0. If a copy of the MPL was not distributed with this
-.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
-..
-.. See the COPYRIGHT file distributed with this work for additional
-.. information regarding copyright ownership.
-
-.. _dnssec.dynamic.zones:
-
-DNSSEC, Dynamic Zones, and Automatic Signing
---------------------------------------------
-
-Converting From Insecure to Secure
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A zone can be changed from insecure to secure in three ways: using a
-dynamic DNS update, via the ``auto-dnssec`` zone option, or by setting a
-DNSSEC policy for the zone with ``dnssec-policy``.
-
-For any method, ``named`` must be configured so that it can see
-the ``K*`` files which contain the public and private parts of the keys
-that are used to sign the zone. These files are generated
-by ``dnssec-keygen``, or created when needed by ``named`` if
-``dnssec-policy`` is used. Keys should be placed in the
-key-directory, as specified in ``named.conf``:
-
-::
-
- zone example.net {
- type primary;
- update-policy local;
- file "dynamic/example.net/example.net";
- key-directory "dynamic/example.net";
- };
-
-If one KSK and one ZSK DNSKEY key have been generated, this
-configuration causes all records in the zone to be signed with the
-ZSK, and the DNSKEY RRset to be signed with the KSK. An NSEC
-chain is generated as part of the initial signing process.
-
-With ``dnssec-policy``, it is possible to specify which keys should be
-KSK and/or ZSK. To sign all records with a key, a CSK must be specified.
-For example:
-
-::
-
- dnssec-policy csk {
- keys {
- csk lifetime unlimited algorithm 13;
- };
- };
-
-Dynamic DNS Update Method
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To insert the keys via dynamic update:
-
-::
-
- % nsupdate
- > ttl 3600
- > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
- > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
- > send
-
-While the update request completes almost immediately, the zone is
-not completely signed until ``named`` has had time to "walk" the zone
-and generate the NSEC and RRSIG records. The NSEC record at the apex
-is added last, to signal that there is a complete NSEC chain.
-
-To sign using NSEC3 instead of NSEC, add an
-NSEC3PARAM record to the initial update request. The OPTOUT bit in the NSEC3
-chain can be set in the flags field of the
-NSEC3PARAM record.
-
-::
-
- % nsupdate
- > ttl 3600
- > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
- > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
- > update add example.net NSEC3PARAM 1 1 100 1234567890
- > send
-
-Again, this update request completes almost immediately; however,
-the record does not show up until ``named`` has had a chance to
-build/remove the relevant chain. A private type record is created
-to record the state of the operation (see below for more details), and
-is removed once the operation completes.
-
-While the initial signing and NSEC/NSEC3 chain generation is happening,
-other updates are possible as well.
-
-Fully Automatic Zone Signing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To enable automatic signing, set a ``dnssec-policy`` or add the
-``auto-dnssec`` option to the zone statement in ``named.conf``.
-``auto-dnssec`` has two possible arguments: ``allow`` or ``maintain``.
-
-With ``auto-dnssec allow``, ``named`` can search the key directory for
-keys matching the zone, insert them into the zone, and use them to sign
-the zone. It does so only when it receives an
-``rndc sign <zonename>``.
-
-``auto-dnssec maintain`` includes the above functionality, but also
-automatically adjusts the zone's DNSKEY records on a schedule according to
-the keys' timing metadata. (See :ref:`man_dnssec-keygen` and
-:ref:`man_dnssec-settime` for more information.)
-
-``dnssec-policy`` is similar to ``auto-dnssec maintain``, but
-``dnssec-policy`` also automatically creates new keys when necessary. In
-addition, any configuration related to DNSSEC signing is retrieved from the
-policy, ignoring existing DNSSEC ``named.conf`` options.
-
-``named`` periodically searches the key directory for keys matching
-the zone; if the keys' metadata indicates that any change should be
-made to the zone - such as adding, removing, or revoking a key - then that
-action is carried out. By default, the key directory is checked for
-changes every 60 minutes; this period can be adjusted with
-``dnssec-loadkeys-interval``, up to a maximum of 24 hours. The
-``rndc loadkeys`` command forces ``named`` to check for key updates immediately.
-
-If keys are present in the key directory the first time the zone is
-loaded, the zone is signed immediately, without waiting for an
-``rndc sign`` or ``rndc loadkeys`` command. Those commands can still be
-used when there are unscheduled key changes.
-
-When new keys are added to a zone, the TTL is set to match that of any
-existing DNSKEY RRset. If there is no existing DNSKEY RRset, the
-TTL is set to the TTL specified when the key was created (using the
-``dnssec-keygen -L`` option), if any, or to the SOA TTL.
-
-To sign the zone using NSEC3 instead of NSEC, submit an
-NSEC3PARAM record via dynamic update prior to the scheduled publication
-and activation of the keys. The OPTOUT bit for the NSEC3 chain can be set
-in the flags field of the NSEC3PARAM record. The
-NSEC3PARAM record does not appear in the zone immediately, but it is
-stored for later reference. When the zone is signed and the NSEC3
-chain is completed, the NSEC3PARAM record appears in the zone.
-
-Using the ``auto-dnssec`` option requires the zone to be configured to
-allow dynamic updates, by adding an ``allow-update`` or
-``update-policy`` statement to the zone configuration. If this has not
-been done, the configuration fails.
-
-Private Type Records
-~~~~~~~~~~~~~~~~~~~~
-
-The state of the signing process is signaled by private type records
-(with a default type value of 65534). When signing is complete, those
-records with a non-zero initial octet have a non-zero value for the final octet.
-
-If the first octet of a private type record is non-zero, the
-record indicates either that the zone needs to be signed with the key matching
-the record, or that all signatures that match the record should be
-removed. Here are the meanings of the different values of the first octet:
-
- - algorithm (octet 1)
-
- - key id in network order (octet 2 and 3)
-
- - removal flag (octet 4)
-
- - complete flag (octet 5)
-
-Only records flagged as "complete" can be removed via dynamic update; attempts
-to remove other private type records are silently ignored.
-
-If the first octet is zero (this is a reserved algorithm number that
-should never appear in a DNSKEY record), the record indicates that
-changes to the NSEC3 chains are in progress. The rest of the record
-contains an NSEC3PARAM record, while the flag field tells what operation to
-perform based on the flag bits:
-
- 0x01 OPTOUT
-
- 0x80 CREATE
-
- 0x40 REMOVE
-
- 0x20 NONSEC
-
-DNSKEY Rollovers
-~~~~~~~~~~~~~~~~
-
-As with insecure-to-secure conversions, DNSSEC keyrolls can be done
-in two ways: using a dynamic DNS update, or via the ``auto-dnssec`` zone
-option.
-
-Dynamic DNS Update Method
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To perform key rollovers via a dynamic update, the ``K*``
-files for the new keys must be added so that ``named`` can find them.
-The new DNSKEY RRs can then be added via dynamic update. ``named`` then causes the
-zone to be signed with the new keys; when the signing is complete, the
-private type records are updated so that the last octet is non-zero.
-
-If this is for a KSK, the parent and any trust anchor
-repositories of the new KSK must be informed.
-
-The maximum TTL in the zone must expire before removing the
-old DNSKEY. If it is a KSK that is being updated,
-the DS RRset in the parent must also be updated and its TTL allowed to expire. This
-ensures that all clients are able to verify at least one signature
-when the old DNSKEY is removed.
-
-The old DNSKEY can be removed via UPDATE, taking care to specify the
-correct key. ``named`` cleans out any signatures generated by the
-old key after the update completes.
-
-Automatic Key Rollovers
-~~~~~~~~~~~~~~~~~~~~~~~
-
-When a new key reaches its activation date (as set by ``dnssec-keygen``
-or ``dnssec-settime``), and if the ``auto-dnssec`` zone option is set to
-``maintain``, ``named`` automatically carries out the key rollover.
-If the key's algorithm has not previously been used to sign the zone,
-then the zone is fully signed as quickly as possible. However, if
-the new key replaces an existing key of the same algorithm, the
-zone is re-signed incrementally, with signatures from the old key
-replaced with signatures from the new key as their signature
-validity periods expire. By default, this rollover completes in 30 days,
-after which it is safe to remove the old key from the DNSKEY RRset.
-
-NSEC3PARAM Rollovers via UPDATE
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The new NSEC3PARAM record can be added via dynamic update. When the new NSEC3
-chain has been generated, the NSEC3PARAM flag field is set to zero. At
-that point, the old NSEC3PARAM record can be removed. The old chain is
-removed after the update request completes.
-
-Converting From NSEC to NSEC3
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Add a ``nsec3param`` option to your ``dnssec-policy`` and
-run ``rndc reconfig``.
-
-Or use ``nsupdate`` to add an NSEC3PARAM record.
-
-In both cases, the NSEC3 chain is generated and the NSEC3PARAM record is
-added before the NSEC chain is destroyed.
-
-Converting From NSEC3 to NSEC
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To do this, remove the ``nsec3param`` option from the ``dnssec-policy`` and
-run ``rndc reconfig``.
-
-Or use ``nsupdate`` to remove all NSEC3PARAM records with a
-zero flag field. The NSEC chain is generated before the NSEC3 chain
-is removed.
-
-Converting From Secure to Insecure
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To convert a signed zone to unsigned using dynamic DNS, delete all the
-DNSKEY records from the zone apex using ``nsupdate``. All signatures,
-NSEC or NSEC3 chains, and associated NSEC3PARAM records are removed
-automatically. This takes place after the update request completes.
-
-This requires the ``dnssec-secure-to-insecure`` option to be set to
-``yes`` in ``named.conf``.
-
-In addition, if the ``auto-dnssec maintain`` zone statement is used, it
-should be removed or changed to ``allow`` instead; otherwise it will re-sign.
-
-Periodic Re-signing
-~~~~~~~~~~~~~~~~~~~
-
-In any secure zone which supports dynamic updates, ``named``
-periodically re-signs RRsets which have not been re-signed as a result of
-some update action. The signature lifetimes are adjusted to
-spread the re-sign load over time rather than all at once.
-
-NSEC3 and OPTOUT
-~~~~~~~~~~~~~~~~
-
-``named`` only supports creating new NSEC3 chains where all the NSEC3
-records in the zone have the same OPTOUT state. ``named`` supports
-UPDATES to zones where the NSEC3 records in the chain have mixed OPTOUT
-state. ``named`` does not support changing the OPTOUT state of an
-individual NSEC3 record; if the
-OPTOUT state of an individual NSEC3 needs to be changed, the entire chain must be changed.
requirements
configuration
reference
+ dnssec.inc
advanced
security
troubleshooting
projects / thirdparty / bind9.git / commitdiff
