.. 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.

.. _rfc5011.support:

Dynamic Trust Anchor Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

BIND is able to maintain DNSSEC trust anchors using :rfc:`5011` key
management. This feature allows :iscman:`named` to keep track of changes to
critical DNSSEC keys without any need for the operator to make changes
to configuration files.

Validating Resolver
^^^^^^^^^^^^^^^^^^^

To configure a validating resolver to use :rfc:`5011` to maintain a trust
anchor, configure the trust anchor using a :any:`trust-anchors` statement and
the ``initial-key`` keyword. Information about this can be found in
the :any:`trust-anchors` statement description.

Authoritative Server
^^^^^^^^^^^^^^^^^^^^

To set up an authoritative zone for :rfc:`5011` trust anchor maintenance,
generate two (or more) key signing keys (KSKs) for the zone. Sign the
zone with one of them; this is the "active" KSK. All KSKs which do not
sign the zone are "stand-by" keys.

Any validating resolver which is configured to use the active KSK as an
:rfc:`5011`-managed trust anchor takes note of the stand-by KSKs in the
zone's DNSKEY RRset, and stores them for future reference. The resolver
rechecks the zone periodically; after 30 days, if the new key is
still there, the key is accepted by the resolver as a valid
trust anchor for the zone. Anytime after this 30-day acceptance timer
has completed, the active KSK can be revoked, and the zone can be
"rolled over" to the newly accepted key.

The easiest way to place a stand-by key in a zone is to use the "smart
signing" features of :iscman:`dnssec-keygen` and :iscman:`dnssec-signzone`. If a key
exists with a publication date in the past, but an activation date which is
unset or in the future, :option:`dnssec-signzone -S` includes the
DNSKEY record in the zone but does not sign with it:

::

   $ dnssec-keygen -K keys -f KSK -P now -A now+2y example.net
   $ dnssec-signzone -S -K keys example.net

To revoke a key, use the command :iscman:`dnssec-revoke`. This
adds the REVOKED bit to the key flags and regenerates the ``K*.key``
and ``K*.private`` files.

After revoking the active key, the zone must be signed with both the
revoked KSK and the new active KSK. Smart signing takes care of this
automatically.

Once a key has been revoked and used to sign the DNSKEY RRset in which
it appears, that key is never again accepted as a valid trust
anchor by the resolver. However, validation can proceed using the new
active key, which was accepted by the resolver when it was a
stand-by key.

See :rfc:`5011` for more details on key rollover scenarios.

When a key has been revoked, its key ID changes, increasing by 128 and
wrapping around at 65535. So, for example, the key
"``Kexample.com.+005+10000``" becomes "``Kexample.com.+005+10128``".

If two keys have IDs exactly 128 apart and one is revoked, the two
key IDs will collide, causing several problems. To prevent this,
:iscman:`dnssec-keygen` does not generate a new key if another key
which may collide is present. This checking only occurs if the new keys are
written to the same directory that holds all other keys in use for that
zone.

Older versions of BIND 9 did not have this protection. Exercise caution
if using key revocation on keys that were generated by previous
releases, or if using keys stored in multiple directories or on multiple
machines.

It is expected that a future release of BIND 9 will address this problem
in a different way, by storing revoked keys with their original
unrevoked key IDs.