krb5 commit: Document hostrealm interface

[Greg Hudson]

https://github.com/krb5/krb5/commit/2721a662a3d88601bff991599928c1566be7485a
commit 2721a662a3d88601bff991599928c1566be7485a
Author: Greg Hudson <ghudson at mit.edu>
Date:   Wed Aug 7 15:48:36 2013 -0400

    Document hostrealm interface
    
    ticket: 7687

 doc/admin/conf_files/krb5_conf.rst |   26 ++++++++++++++++++++++++
 doc/plugindev/hostrealm.rst        |   39 ++++++++++++++++++++++++++++++++++++
 doc/plugindev/index.rst            |    1 +
 3 files changed, 66 insertions(+), 0 deletions(-)

diff --git a/doc/admin/conf_files/krb5_conf.rst b/doc/admin/conf_files/krb5_conf.rst
index 4063027..6fa94e7 100644
--- a/doc/admin/conf_files/krb5_conf.rst
+++ b/doc/admin/conf_files/krb5_conf.rst
@@ -743,6 +743,32 @@ built-in modules exist for these interfaces:
 **encrypted_timestamp**
     This module implements the encrypted timestamp mechanism.
 
+.. _hostrealm:
+
+hostrealm interface
+###################
+
+The hostrealm section (introduced in release 1.12) controls modules
+for the host-to-realm interface, which affects the local mapping of
+hostnames to realm names and the choice of default realm.  The following
+built-in modules exist for this interface:
+
+**profile**
+    This module consults the [domain_realm] section of the profile for
+    authoritative host-to-realm mappings, and the **default_realm**
+    variable for the default realm.
+
+**dns**
+    This module looks for DNS records for fallback host-to-realm
+    mappings and the default realm.  It only operates if the
+    **dns_lookup_realm** variable is set to true.
+
+**domain**
+    This module applies heuristics for fallback host-to-realm
+    mappings.  It implements the **realm_try_domains** variable, and
+    uses the uppercased parent domain of the hostname if that does not
+    produce a result.
+
 .. _localauth:
 
 localauth interface
diff --git a/doc/plugindev/hostrealm.rst b/doc/plugindev/hostrealm.rst
new file mode 100644
index 0000000..fe1ec38
--- /dev/null
+++ b/doc/plugindev/hostrealm.rst
@@ -0,0 +1,39 @@
+.. _hostrealm_plugin:
+
+Host-to-realm interface (hostrealm)
+===================================
+
+The host-to-realm interface was first introduced in release 1.12.  It
+allows modules to control the local mapping of hostnames to realm
+names as well as the default realm.  For a detailed description of the
+hostrealm interface, see the header file
+``<krb5/hostrealm_plugin.h>``.
+
+Although the mapping methods in the hostrealm interface return a list
+of one or more realms, only the first realm in the list is currently
+used by callers.  Callers may begin using later responses in the
+future.
+
+Any mapping method may return KRB5_PLUGIN_NO_HANDLE to defer
+processing to a later module.
+
+A module can create and destroy per-library-context state objects
+using the **init** and **fini** methods.  If the module does not need
+any state, it does not need to implement these methods.
+
+The optional **host_realm** method allows a module to determine
+authoritative realm mappings for a hostname.  The first authoritative
+mapping is used in preference to KDC referrals when getting service
+credentials.
+
+The optional **fallback_realm** method allows a module to determine
+fallback mappings for a hostname.  The first fallback mapping is tried
+if there is no authoritative mapping for a realm, and KDC referrals
+failed to produce a succesful result.
+
+The optional **default_realm** method allows a module to determine the
+local default realm.
+
+If a module implements any of the above methods, it must also
+implement **free_list** to ensure that memory is allocated and
+deallocated consistently.
diff --git a/doc/plugindev/index.rst b/doc/plugindev/index.rst
index 548d23e..3fb9217 100644
--- a/doc/plugindev/index.rst
+++ b/doc/plugindev/index.rst
@@ -25,6 +25,7 @@ Contents
    ccselect.rst
    pwqual.rst
    kadm5_hook.rst
+   hostrealm.rst
    localauth.rst
    locate.rst
    profile.rst