KRB5-PLUGIN(7)

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 via a plugin load function exported by a shared object. Plugin load functions should be named by concatenating the name defined in the associated header file with the string "plugin_load" (e.g. "krb5_plugin_kuserok_plugin_load" for the plugin for krb5_kuserok(3) ). The plugin load function must be of type heim_plugin_load_ft which is:

    krb5_error_code HEIM_CALLCONV
    my_plugin_load(heim_pcontext context,
                   krb5_get_instance_func_t *get_instance,
                   size_t *num_plugins,
                   heim_plugin_common_ftable_cp **plugins);

where HEIM_CALLCONV is __stdcall on Windows.

The plugin should set the get_instance output parameter to the a function that will return the instances of its library dependencies. For example:

    static uintptr_t HEIM_LIB_CALL
    my_plugin_get_instance(const char *name)
    {
        if (strcmp(name, "krb5") == 0)
            return krb5_get_instance(name);
        return 0;
    }

The get_instance function is used to check that dynamically-linked plugins are linked with the same Heimdal shared objects as the one loading and running the plugin.

The output parameters plugins and n_plugins output an array of pointers to function tabls, and the number of those, respectively.

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 heim_pcontext (which for krb5 plugins is actually a krb5_context), and a void ** , returning a heim_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 may add 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 that indicates that the plugin was not applicable. For krb5 plugins, KRB5_PLUGIN_NO_HANDLE indicates that the plugin was not applicable.

Heimdal plugin callers either invoke all plugins until one returns an error or all return KRB5_PLUGIN_NO_HANDLE , or invoke all plugins until one returns a value other than KRB5_PLUGIN_NO_HANDLE with the expectation that only one plugin would return success and all oters would return KRB5_PLUGIN_NO_HANDLE. Thus Heimdal plugin invokation can be deterministic in spite of non-deterministic invocation order.

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>
    /* Note that `context' here is actually a krb5_context value */
    static krb5_error_code KRB5_CALLCONV
    nouser_plug_init(heim_pcontext 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,
    };
    static const krb5plugin_an2ln_ftable *const plugins[] = {
        &an2ln
    };
    static uintptr_t
    an2ln_get_instance(const char *libname)
    {
        if (strcmp(libname, "krb5") == 0)
    	return krb5_get_instance(libname);
        return 0;
    }
    /* Note that `context' here is actually a krb5_context value */
    krb5_error_code
    an2ln_plugin_load(heim_pcontext context,
                     krb5_get_instance_func_t *get_instance,
                     size_t *num_plugins,
                     const krb5plugin_an2ln_ftable * const **pplugins)
    {
        *get_instance = an2ln_get_instance;
        *num_plugins = sizeof(plugins) / sizeof(plugins[0]);
        *pplugins = plugins;
        return 0;
    }

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(heim_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;
    }
    static krb5plugin_kuserok_ftable kuserok = {
        KRB5_PLUGIN_KUSEROK_VERSION_0,
        reject_plug_init,
        reject_plug_fini,
        reject_plug_kuserok,
    };
    static const krb5plugin_kuserok_ftable *const plugins[] = {
        &kuserok
    };
    static uintptr_t
    kuserok_get_instance(const char *libname)
    {
        if (strcmp(libname, "krb5") == 0)
    	return krb5_get_instance(libname);
        return 0;
    }
    krb5_error_code
    krb5_plugin_kuserok_plugin_load(
        heim_context context,
        krb5_get_instance_func_t *get_instance,
        size_t *num_plugins,
        const krb5plugin_kuserok_ftable * const **pplugins)
    {
        *krb5_instance = kuserok_get_instance;
        *num_plugins = sizeof(plugins) / sizeof(plugins[0]);
        *pplugins = plugins;
        return 0;
    }

SEE ALSO
krb5_plugin_register(3) krb5_kuserok(3) krb5_aname_to_localname(3)