Local authorization interface (localauth)

The localauth interface was first introduced in release 1.12. It allows modules to control the relationship between Kerberos principals and local system accounts. When an application calls krb5_kuserok() or krb5_aname_to_localname(), localauth modules are consulted to determine the result. For a detailed description of the localauth interface, see the header file <krb5/localauth_plugin.h>.

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 userok method allows a module to control the behavior of krb5_kuserok(). The module receives the authenticated name and the local account name as inputs, and can return either 0 to authorize access, KRB5_PLUGIN_NO_HANDLE to defer the decision to other modules, or another error (canonically EPERM) to authoritatively deny access. Access is granted if at least one module grants access and no module authoritatively denies access.

The optional an2ln method can work in two different ways. If the module sets an array of uppercase type names in an2ln_types, then the module’s an2ln method will only be invoked by krb5_aname_to_localname() if an auth_to_local value in krb5.conf refers to one of the module’s types. In this case, the type and residual arguments will give the type name and residual string of the auth_to_local value.

If the module does not set an2ln_types but does implement an2ln, the module’s an2ln method will be invoked for all krb5_aname_to_localname() operations unless an earlier module determines a mapping, with type and residual set to NULL. The module can return KRB5_LNAME_NO_TRANS to defer mapping to later modules.

If a module implements an2ln, it must also implement free_string to ensure that memory is allocated and deallocated consistently.