Document TXT records for realm lookup

Even though they are subject to vulnerabilities via DNS spoofing
and we accordingly don't recommend their use, we do have the code
to use them.  Just as we document dns_lookup_realm in krb5.conf(5),
document them here.

ticket: 7407

diff --git a/doc/rst_source/krb_admins/realm_config.rst b/doc/rst_source/krb_admins/realm_config.rst
index 2a0e0cc2243d553ce1362dbfabd561bf9ab14a9f..a19c3d76cb7f7a3ac13cb71d42a4f7d38f662403 100644 (file)
--- a/doc/rst_source/krb_admins/realm_config.rst
+++ b/doc/rst_source/krb_admins/realm_config.rst
@@ -38,7 +38,7 @@ descriptive names which end with your domain name, such as::
 Mapping hostnames onto Kerberos realms
 --------------------------------------
 
-Mapping hostnames onto Kerberos realms is done in one of two ways.
+Mapping hostnames onto Kerberos realms is done in one of three ways.
 
 The first mechanism works through a set of rules in the
 :ref:`domain_realm` section of :ref:`krb5.conf(5)`.  You can specify
@@ -60,6 +60,27 @@ the KDC must be running MIT krb5 1.7 or later.  The
 :ref:`kdc_realms` section of :ref:`kdc.conf(5)` can be used to
 fine-tune referral behavior on the KDC.
 
+It is also possible for clients to use DNS TXT records, if
+**dns_lookup_realm** is enabled in :ref:`krb5.conf(5)`.  Such lookups
+are disabled by default because DNS is an insecure protocol and security
+holes could result if DNS records are spoofed.  If enabled, the client
+will try to look up a TXT record formed by prepending the prefix
+``_kerberos`` to the hostname in question.  If that record is not
+found, the client will attempt a lookup by prepending ``_kerberos`` to the
+host's domain name, then its parent domain, up to the top-level domain.
+For the hostname ``boston.engineering.example.com``, the names looked up
+would be::
+
+    _kerberos.boston.engineering.example.com
+    _kerberos.engineering.example.com
+    _kerberos.example.com
+    _kerberos.com
+
+The value of the first TXT record found is taken as the realm name.
+
+Even if you do not choose to use this mechanism within your site,
+you may wish to set it up anyway, for use when interacting with other sites.
+
 
 Ports for the KDC and admin services
 ------------------------------------