diff options
Diffstat (limited to 'third_party/heimdal/lib/krb5/krb5-plugin.7')
| -rw-r--r-- | third_party/heimdal/lib/krb5/krb5-plugin.7 | 359 |
1 files changed, 359 insertions, 0 deletions
diff --git a/third_party/heimdal/lib/krb5/krb5-plugin.7 b/third_party/heimdal/lib/krb5/krb5-plugin.7 new file mode 100644 index 0000000..0b1e729 --- /dev/null +++ b/third_party/heimdal/lib/krb5/krb5-plugin.7 @@ -0,0 +1,359 @@ +.\" Copyright (c) 1999 - 2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id$ +.\" +.Dd December 21, 2011 +.Dt KRB5-PLUGIN 7 +.Os HEIMDAL +.Sh NAME +.Nm krb5-plugin +.Nd plugin interface for Heimdal +.Sh SYNOPSIS +.In krb5.h +.In krb5/an2ln_plugin.h +.In krb5/ccache_plugin.h +.In krb5/db_plugin.h +.In krb5/kuserok_plugin.h +.In krb5/locate_plugin.h +.In krb5/send_to_kdc_plugin.h +.Sh DESCRIPTION +Heimdal has a plugin interface. Plugins may be statically linked into +Heimdal and registered via the +.Xr krb5_plugin_register 3 +function, or they may be dynamically loaded from shared objects present +in the Heimdal plugins directories. +.Pp +Plugins consist of a C struct whose struct name is given in the +associated header file, such as, for example, +.Va krb5plugin_kuserok_ftable +and a pointer to which is either registered via +.Xr 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 +.Xr krb5_kuserok 3 +). +The plugin load function must be of type +.Va heim_plugin_load_ft +which is: +.Bd -literal -offset indent +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); + +.Ed +where +.Va HEIM_CALLCONV +is +.Va __stdcall +on Windows. +.Pp +The plugin should set the get_instance output parameter to the a +function that will return the instances of its library +dependencies. For example: +.Bd -literal -offset indent +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; +} +.Ed +.Pp +The +.Va 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. +.Pp +The output parameters +.Va plugins +and +.Va n_plugins +output an array of pointers to function tabls, and the number of +those, respectively. +.Pp +The plugin structs for all plugin types always begin with the same three +common fields: +.Bl -enum -compact +.It +.Va minor_version +, an int. Plugin minor versions are defined in each plugin type's +associated header file. +.It +.Va init +, a pointer to a function with two arguments, a +.Va heim_pcontext +(which for krb5 plugins is actually a krb5_context), +and a +.Va void ** +, returning a heim_error_code. This function will be called to +initialize a plugin-specific context in the form of a +.Va void * +that will be output through the init function's second argument. +.It +.Va fini +, a pointer to a function of one argument, a +.Va void * +, consisting of the plugin's context to be destroyed, and +returning +.Va void. +.El +.Pp +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, +.Va KRB5_PLUGIN_NO_HANDLE +indicates that the plugin was not applicable. +.Pp +Heimdal plugin callers either invoke all plugins until one returns an +error or all return +.Va KRB5_PLUGIN_NO_HANDLE +, or invoke all plugins until one returns a value other than +.Va KRB5_PLUGIN_NO_HANDLE +with the expectation that only one plugin would return success and all +oters would return +.Va KRB5_PLUGIN_NO_HANDLE. +Thus Heimdal plugin invokation can be deterministic in spite of +non-deterministic invocation order. +.Pp +There is a database plugin system intended for many of the uses of +databases in Heimdal. The plugin is expected to call +.Xr heim_db_register 3 +from its +.Va init +entry point to register a DB type. The DB plugin's +.Va fini +function must do nothing, and the plugin must not provide any other +entry points. +.Pp +The krb5_kuserok plugin adds a single field to its struct: a pointer to +a function that implements kuserok functionality with the following +form: +.Bd -literal -offset indent +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) +.Ed +.Pp +The +.Va luser +, +.Va principal +and +.Va result +arguments are self-explanatory (see +.Xr krb5_kuserok 3 +). The +.Va plug_ctx +argument is the context output by the plugin's init function. The +.Va 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 +.Va k5login_dir +argument provides an alternative k5login file location, if not NULL. +The +.Va flags +argument indicates whether the plugin may call +.Xr krb5_aname_to_localname 3 +(KUSEROK_ANAME_TO_LNAME_OK), and whether k5login databases are expected to be +authoritative (KUSEROK_K5LOGIN_IS_AUTHORITATIVE). +.Pp +The plugin for +.Xr krb5_aname_to_localname 3 +is named "an2ln" and has a single extra field for the plugin struct: +.Bd -literal -offset indent +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) +.Ed +.Pp +The arguments for the +.Va an2ln +plugin are similar to those of the kuserok plugin, but the result, being +a string, is set by calling the +.Va set_res_f +function argument with the +.Va set_res_ctx +and result string as arguments. The +.Va set_res_f +function will make a copy of the string. +.Sh FILES +.Bl -tag -compact +.It Pa libdir/plugin/krb5/* +Shared objects containing plugins for Heimdal. +.El +.Sh EXAMPLES +.Pp +An example an2ln plugin that maps principals to a constant "nouser" +follows: +.Pp +.Bd -literal -offset indent +#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; +} +.Ed +.Pp +An example kuserok plugin that rejects all requests follows. (Note that +there exists a built-in plugin with this functionality; see +.Xr krb5_kuserok 3 +). +.Pp +.Bd -literal -offset indent +#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; +} + +.Ed +.Sh SEE ALSO +.Xr krb5_plugin_register 3 +.Xr krb5_kuserok 3 +.Xr krb5_aname_to_localname 3 |