krb5 commit: Document TXT records for realm lookup

[Benjamin Kaduk]

https://github.com/krb5/krb5/commit/89465b37e226f75e5685aae1d3848f8c467f9d02
commit 89465b37e226f75e5685aae1d3848f8c467f9d02
Author: Ben Kaduk <kaduk at mit.edu>
Date:   Thu Oct 4 13:42:13 2012 -0400

    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

 doc/rst_source/krb_admins/realm_config.rst |   23 ++++++++++++++++++++++-
 1 files changed, 22 insertions(+), 1 deletions(-)

diff --git a/doc/rst_source/krb_admins/realm_config.rst b/doc/rst_source/krb_admins/realm_config.rst
index 2a0e0cc..a19c3d7 100644
--- 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
 ------------------------------------