doc/plugindev/localauth.rst

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