1 files changed, 92 insertions, 0 deletions
diff --git a/doc/arm/managed-keys.inc.rst b/doc/arm/managed-keys.inc.rst
new file mode 100644
index 0000000..a8eb4c7
--- /dev/null
+++ b/doc/arm/managed-keys.inc.rst
@@ -0,0 +1,92 @@
+.. 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.