.. _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.