NAME

       krb5-plugin — plugin interface for Heimdal

SYNOPSIS

       #include <krb5.h>
       #include <krb5/an2ln_plugin.h>
       #include <krb5/ccache_plugin.h>
       #include <krb5/db_plugin.h>
       #include <krb5/kuserok_plugin.h>
       #include <krb5/locate_plugin.h>
       #include <krb5/send_to_kdc_plugin.h>

DESCRIPTION

       Heimdal  has  a  plugin  interface.  Plugins may be statically linked into Heimdal and registered via the
       krb5_plugin_register(3) function, or they may be dynamically loaded from shared objects  present  in  the
       Heimdal plugins directories.

       Plugins  consist  of  a  C  struct whose struct name is given in the associated header file, such as, for
       example,   krb5plugin_kuserok_ftable   and   a   pointer   to   which   is    either    registered    via
       krb5_plugin_register(3)  or  found  in a shared object via a symbol lookup for the symbol name defined in
       the associated header file (e.g., "kuserok" for the plugin for krb5_kuserok(3) ).

       The plugin structs for all plugin types always begin with the same three common fields:
       1.   minor_version , an int.  Plugin minor versions are defined in each plugin type's  associated  header
            file.
       2.   init  ,  a  pointer  to  a  function  with  two arguments, a krb5_context and a void **, returning a
            krb5_error_code.  This function will be called to initialize a plugin-specific context in  the  form
            of a void * that will be output through the init function's second argument.
       3.   fini  ,  a pointer to a function of one argument, a void *, consisting of the plugin's context to be
            destroyed, and returning void.

       Each plugin type must add zero or more fields to this struct following  the  above  three.   Plugins  are
       typically  invoked  in  no  particular  order until one succeeds or fails, or all return a special return
       value such as KRB5_PLUGIN_NO_HANDLE to indicate that the plugin was not applicable.   Most  plugin  types
       obtain  deterministic plugin behavior in spite of the non-deterministic invocation order by, for example,
       invoking all plugins for each "rule" and passing the rule to each plugin with the expectation  that  just
       one plugin will match any given rule.

       There  is  a database plugin system intended for many of the uses of databases in Heimdal.  The plugin is
       expected to call heim_db_register(3) from its init entry point to register a DB type.   The  DB  plugin's
       fini function must do nothing, and the plugin must not provide any other entry points.

       The  krb5_kuserok  plugin  adds  a  single  field  to its struct: a pointer to a function that implements
       kuserok functionality with the following form:

             static krb5_error_code
             kuserok(void *plug_ctx, krb5_context context, const char *rule,
                     unsigned int flags, const char *k5login_dir,
                     const char *luser, krb5_const_principal principal,
                     krb5_boolean *result)

       The luser , principal and result arguments are self-explanatory (see  krb5_kuserok(3)  ).   The  plug_ctx
       argument  is  the context output by the plugin's init function.  The rule argument is a kuserok rule from
       the krb5.conf file; each plugin is invoked once for each rule until all plugins  fail  or  one  succeeds.
       The  k5login_dir argument provides an alternative k5login file location, if not NULL.  The flags argument
       indicates whether the plugin may call krb5_aname_to_localname(3) (KUSEROK_ANAME_TO_LNAME_OK), and whether
       k5login databases are expected to be authoritative (KUSEROK_K5LOGIN_IS_AUTHORITATIVE).

       The plugin for krb5_aname_to_localname(3) is named "an2ln" and has a single extra field  for  the  plugin
       struct:

             typedef krb5_error_code (*set_result_f)(void *, const char *);

             static krb5_error_code
             an2ln(void *plug_ctx, krb5_context context, const char *rule,
                   krb5_const_principal aname, set_result_f set_res_f, void *set_res_ctx)

       The  arguments  for  the an2ln plugin are similar to those of the kuserok plugin, but the result, being a
       string, is set by calling the set_res_f function argument with  the  set_res_ctx  and  result  string  as
       arguments.  The set_res_f function will make a copy of the string.

FILES

       libdir/plugin/krb5/*
               Shared objects containing plugins for Heimdal.

EXAMPLES

       An example an2ln plugin that maps principals to a constant "nouser" follows:

             #include <krb5/an2ln_plugin.h>

             static krb5_error_code KRB5_CALLCONV
             nouser_plug_init(krb5_context context, void **ctx)
             {
                 *ctx = NULL;
                 return 0;
             }

             static void KRB5_CALLCONV nouser_plug_fini(void *ctx) { }

             static krb5_error_code KRB5_CALLCONV
             nouser_plug_an2ln(void *plug_ctx, krb5_context context,
                               const char *rule,
                               krb5_const_principal aname,
                               set_result_f set_res_f, void *set_res_ctx)
             {
                 krb5_error_code ret;

                 if (strcmp(rule, "NOUSER") != 0)
                     return KRB5_PLUGIN_NO_HANDLE;

                 ret = set_res_f(set_res_ctx, "nouser");

                 return ret;
             }

             krb5plugin_an2ln_ftable an2ln = {
                 KRB5_PLUGIN_AN2LN_VERSION_0,
                 nouser_plug_init,
                 nouser_plug_fini,
                 nouser_plug_an2ln,
             };

       An  example  kuserok plugin that rejects all requests follows.  (Note that there exists a built-in plugin
       with this functionality; see krb5_kuserok(3) ).

             #include <krb5/kuserok_plugin.h>

             static krb5_error_code KRB5_CALLCONV
             reject_plug_init(krb5_context context, void **ctx)
             {
                 *ctx = NULL;
                 return 0;
             }

             static void KRB5_CALLCONV reject_plug_fini(void *ctx) { }

             static krb5_error_code KRB5_CALLCONV
             reject_plug_kuserok(void *plug_ctx, krb5_context context, const char *rule,
                                 unsigned int flags, const char *k5login_dir,
                                 const char *luser, krb5_const_principal principal,
                                 krb5_boolean *result)
             {
                 if (strcmp(rule, "REJECT") != 0)
                     return KRB5_PLUGIN_NO_HANDLE;

                 *result = FALSE;
                 return 0;
             }

             krb5plugin_kuserok_ftable kuserok = {
                 KRB5_PLUGIN_KUSEROK_VERSION_0,
                 reject_plug_init,
                 reject_plug_fini,
                 reject_plug_kuserok,
             };

SEE ALSO

       krb5_plugin_register(3) krb5_kuserok(3) krb5_aname_to_localname(3)

HEIMDAL                                         December 21, 2011                                 KRB5-PLUGIN(7)