KRB5-PLUGIN(7)       BSD Miscellaneous Information Manual       KRB5-PLUGIN(7)

[1mNAME[0m
     [1mkrb5-plugin [22m-- plugin interface for Heimdal

[1mSYNOPSIS[0m
     [1m#include <krb5.h>[0m
     [1m#include <krb5/an2ln_plugin.h>[0m
     [1m#include <krb5/ccache_plugin.h>[0m
     [1m#include <krb5/db_plugin.h>[0m
     [1m#include <krb5/kuserok_plugin.h>[0m
     [1m#include <krb5/locate_plugin.h>[0m
     [1m#include <krb5/send_to_kdc_plugin.h>[0m

[1mDESCRIPTION[0m
     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 associ-
     ated header file, such as, for example, [4mkrb5plugin_kuserok_ftable[24m 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.   [4mminor_version[24m , an int.  Plugin minor versions are defined in each
          plugin type's associated header file.
     2.   [4minit[24m , 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.   [4mfini[24m , 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 data-
     bases in Heimdal.  The plugin is expected to call heim_db_register(3)
     from its [4minit[24m entry point to register a DB type.  The DB plugin's [4mfini[0m
     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 [4mluser[24m , [4mprincipal[24m and [4mresult[24m arguments are self-explanatory (see
     krb5_kuserok(3) ).  The [4mplug_ctx[24m argument is the context output by the
     plugin's init function.  The [4mrule[24m argument is a kuserok rule from the
     krb5.conf file; each plugin is invoked once for each rule until all plug-
     ins fail or one succeeds.  The [4mk5login_dir[24m argument provides an alterna-
     tive k5login file location, if not NULL.  The [4mflags[24m 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 sin-
     gle 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 [4man2ln[24m plugin are similar to those of the kuserok
     plugin, but the result, being a string, is set by calling the [4mset_res_f[0m
     function argument with the [4mset_res_ctx[24m and result string as arguments.
     The [4mset_res_f[24m function will make a copy of the string.

[1mFILES[0m
     libdir/plugin/krb5/*
             Shared objects containing plugins for Heimdal.

[1mEXAMPLES[0m
     An example an2ln plugin that maps principals to a constant "nouser" fol-
     lows:

           #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,
           };

[1mSEE ALSO[0m
     krb5_plugin_register(3) krb5_kuserok(3) krb5_aname_to_localname(3)

HEIMDAL                        December 21, 2011                       HEIMDAL
