diff options
author | Greg Hudson <ghudson@mit.edu> | 2013-08-07 15:48:36 -0400 |
---|---|---|
committer | Greg Hudson <ghudson@mit.edu> | 2013-08-15 12:39:58 -0400 |
commit | 2721a662a3d88601bff991599928c1566be7485a (patch) | |
tree | 494052fe33335b21f954953496a2a25386ae52f4 /doc | |
parent | 7ad5f3bfd8b57d2f4c001182792e25968309ca8a (diff) | |
download | krb5-2721a662a3d88601bff991599928c1566be7485a.tar.gz krb5-2721a662a3d88601bff991599928c1566be7485a.tar.xz krb5-2721a662a3d88601bff991599928c1566be7485a.zip |
Document hostrealm interface
ticket: 7687
Diffstat (limited to 'doc')
-rw-r--r-- | doc/admin/conf_files/krb5_conf.rst | 26 | ||||
-rw-r--r-- | doc/plugindev/hostrealm.rst | 39 | ||||
-rw-r--r-- | 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 40630277b9..6fa94e7c81 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 0000000000..fe1ec3845a --- /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 548d23ee78..3fb921778c 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 |