diff options
Diffstat (limited to 'lib/krb5/krb5-plugin.cat7')
| -rw-r--r-- | lib/krb5/krb5-plugin.cat7 | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/lib/krb5/krb5-plugin.cat7 b/lib/krb5/krb5-plugin.cat7 new file mode 100644 index 000000000000..6d8ac426ace7 --- /dev/null +++ b/lib/krb5/krb5-plugin.cat7 @@ -0,0 +1,168 @@ + +KRB5-PLUGIN(7) BSD Miscellaneous Information Manual KRB5-PLUGIN(7) + +NNAAMMEE + kkrrbb55--pplluuggiinn -- plugin interface for Heimdal + +SSYYNNOOPPSSIISS + ##iinncclluuddee <<kkrrbb55..hh>> + ##iinncclluuddee <<kkrrbb55//aann22llnn__pplluuggiinn..hh>> + ##iinncclluuddee <<kkrrbb55//ccccaacchhee__pplluuggiinn..hh>> + ##iinncclluuddee <<kkrrbb55//ddbb__pplluuggiinn..hh>> + ##iinncclluuddee <<kkrrbb55//kkuusseerrookk__pplluuggiinn..hh>> + ##iinncclluuddee <<kkrrbb55//llooccaattee__pplluuggiinn..hh>> + ##iinncclluuddee <<kkrrbb55//sseenndd__ttoo__kkddcc__pplluuggiinn..hh>> + +DDEESSCCRRIIPPTTIIOONN + 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, _k_r_b_5_p_l_u_g_i_n___k_u_s_e_r_o_k___f_t_a_b_l_e 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. _m_i_n_o_r___v_e_r_s_i_o_n , an int. Plugin minor versions are defined in each + plugin type's associated header file. + 2. _i_n_i_t , 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. _f_i_n_i , 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 _i_n_i_t entry point to register a DB type. The DB plugin's _f_i_n_i + 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 _l_u_s_e_r , _p_r_i_n_c_i_p_a_l and _r_e_s_u_l_t arguments are self-explanatory (see + krb5_kuserok(3) ). The _p_l_u_g___c_t_x argument is the context output by the + plugin's init function. The _r_u_l_e 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 _k_5_l_o_g_i_n___d_i_r argument provides an alterna- + tive k5login file location, if not NULL. The _f_l_a_g_s 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 _a_n_2_l_n plugin are similar to those of the kuserok + plugin, but the result, being a string, is set by calling the _s_e_t___r_e_s___f + function argument with the _s_e_t___r_e_s___c_t_x and result string as arguments. + The _s_e_t___r_e_s___f function will make a copy of the string. + +FFIILLEESS + libdir/plugin/krb5/* Shared objects containing plugins for + Heimdal. + +EEXXAAMMPPLLEESS + An example an2ln plugin that maps principals to a constant "nouser" fol- + lows: + + #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, + }; + +SSEEEE AALLSSOO + krb5_plugin_register(3) krb5_kuserok(3) krb5_aname_to_localname(3) + +HEIMDAL December 21, 2011 HEIMDAL |