1.. _localauth_plugin: 2 3Local authorization interface (localauth) 4========================================= 5 6The localauth interface was first introduced in release 1.12. It 7allows modules to control the relationship between Kerberos principals 8and local system accounts. When an application calls 9:c:func:`krb5_kuserok` or :c:func:`krb5_aname_to_localname`, localauth 10modules are consulted to determine the result. For a detailed 11description of the localauth interface, see the header file 12``<krb5/localauth_plugin.h>``. 13 14A module can create and destroy per-library-context state objects 15using the **init** and **fini** methods. If the module does not need 16any state, it does not need to implement these methods. 17 18The optional **userok** method allows a module to control the behavior 19of :c:func:`krb5_kuserok`. The module receives the authenticated name 20and the local account name as inputs, and can return either 0 to 21authorize access, KRB5_PLUGIN_NO_HANDLE to defer the decision to other 22modules, or another error (canonically EPERM) to authoritatively deny 23access. Access is granted if at least one module grants access and no 24module authoritatively denies access. 25 26The optional **an2ln** method can work in two different ways. If the 27module sets an array of uppercase type names in **an2ln_types**, then 28the module's **an2ln** method will only be invoked by 29:c:func:`krb5_aname_to_localname` if an **auth_to_local** value in 30:ref:`krb5.conf(5)` refers to one of the module's types. In this 31case, the *type* and *residual* arguments will give the type name and 32residual string of the **auth_to_local** value. 33 34If the module does not set **an2ln_types** but does implement 35**an2ln**, the module's **an2ln** method will be invoked for all 36:c:func:`krb5_aname_to_localname` operations unless an earlier module 37determines a mapping, with *type* and *residual* set to NULL. The 38module can return KRB5_LNAME_NO_TRANS to defer mapping to later 39modules. 40 41If a module implements **an2ln**, it must also implement 42**free_string** to ensure that memory is allocated and deallocated 43consistently. 44