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:
- minor_version , an int. Plugin minor
versions are defined in each plugin type's associated header file.
- 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.
- 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 invokation
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
nouser_plug_init(krb5_context context, void **ctx)
{
*ctx = NULL;
return 0;
}
static void nouser_plug_fini(void *ctx) { }
static krb5_error_code
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
reject_plug_init(krb5_context context, void **ctx)
{
*ctx = NULL;
return 0;
}
static void reject_plug_fini(void *ctx) { }
static krb5_error_code
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)