1*7f2fe78bSCy Schubert.. _hostrealm_plugin: 2*7f2fe78bSCy Schubert 3*7f2fe78bSCy SchubertHost-to-realm interface (hostrealm) 4*7f2fe78bSCy Schubert=================================== 5*7f2fe78bSCy Schubert 6*7f2fe78bSCy SchubertThe host-to-realm interface was first introduced in release 1.12. It 7*7f2fe78bSCy Schubertallows modules to control the local mapping of hostnames to realm 8*7f2fe78bSCy Schubertnames as well as the default realm. For a detailed description of the 9*7f2fe78bSCy Schuberthostrealm interface, see the header file 10*7f2fe78bSCy Schubert``<krb5/hostrealm_plugin.h>``. 11*7f2fe78bSCy Schubert 12*7f2fe78bSCy SchubertAlthough the mapping methods in the hostrealm interface return a list 13*7f2fe78bSCy Schubertof one or more realms, only the first realm in the list is currently 14*7f2fe78bSCy Schubertused by callers. Callers may begin using later responses in the 15*7f2fe78bSCy Schubertfuture. 16*7f2fe78bSCy Schubert 17*7f2fe78bSCy SchubertAny mapping method may return KRB5_PLUGIN_NO_HANDLE to defer 18*7f2fe78bSCy Schubertprocessing to a later module. 19*7f2fe78bSCy Schubert 20*7f2fe78bSCy SchubertA module can create and destroy per-library-context state objects 21*7f2fe78bSCy Schubertusing the **init** and **fini** methods. If the module does not need 22*7f2fe78bSCy Schubertany state, it does not need to implement these methods. 23*7f2fe78bSCy Schubert 24*7f2fe78bSCy SchubertThe optional **host_realm** method allows a module to determine 25*7f2fe78bSCy Schubertauthoritative realm mappings for a hostname. The first authoritative 26*7f2fe78bSCy Schubertmapping is used in preference to KDC referrals when getting service 27*7f2fe78bSCy Schubertcredentials. 28*7f2fe78bSCy Schubert 29*7f2fe78bSCy SchubertThe optional **fallback_realm** method allows a module to determine 30*7f2fe78bSCy Schubertfallback mappings for a hostname. The first fallback mapping is tried 31*7f2fe78bSCy Schubertif there is no authoritative mapping for a realm, and KDC referrals 32*7f2fe78bSCy Schubertfailed to produce a successful result. 33*7f2fe78bSCy Schubert 34*7f2fe78bSCy SchubertThe optional **default_realm** method allows a module to determine the 35*7f2fe78bSCy Schubertlocal default realm. 36*7f2fe78bSCy Schubert 37*7f2fe78bSCy SchubertIf a module implements any of the above methods, it must also 38*7f2fe78bSCy Schubertimplement **free_list** to ensure that memory is allocated and 39*7f2fe78bSCy Schubertdeallocated consistently. 40