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