1KRB5-PLUGIN(7) BSD Miscellaneous Information Manual KRB5-PLUGIN(7)
2
4 krb5-plugin — plugin interface for Heimdal
5
7 #include <krb5.h>
8 #include <krb5/an2ln_plugin.h>
9 #include <krb5/ccache_plugin.h>
10 #include <krb5/db_plugin.h>
11 #include <krb5/kuserok_plugin.h>
12 #include <krb5/locate_plugin.h>
13 #include <krb5/send_to_kdc_plugin.h>
14
16 Heimdal has a plugin interface. Plugins may be statically linked into
17 Heimdal and registered via the krb5_plugin_register(3) function, or they
18 may be dynamically loaded from shared objects present in the Heimdal
19 plugins directories.
20 Plugins consist of a C struct whose struct name is given in the associ‐
22 ated header file, such as, for example, krb5plugin_kuserok_ftable and a
23 pointer to which is either registered via krb5_plugin_register(3) or
24 found in a shared object via a symbol lookup for the symbol name defined
25 in the associated header file (e.g., "kuserok" for the plugin for
26 krb5_kuserok(3) ).
27 The plugin structs for all plugin types always begin with the same three
29 common fields:
30 1. minor_version , an int. Plugin minor versions are defined in each
31 plugin type's associated header file.
32 2. init , a pointer to a function with two arguments, a krb5_context
33 and a void **, returning a krb5_error_code. This function will be
34 called to initialize a plugin-specific context in the form of a void
35 * that will be output through the init function's second argument.
36 3. fini , a pointer to a function of one argument, a void *, consisting
37 of the plugin's context to be destroyed, and returning void.
38 Each plugin type must add zero or more fields to this struct following
40 the above three. Plugins are typically invoked in no particular order
41 until one succeeds or fails, or all return a special return value such as
42 KRB5_PLUGIN_NO_HANDLE to indicate that the plugin was not applicable.
43 Most plugin types obtain deterministic plugin behavior in spite of the
44 non-deterministic invocation order by, for example, invoking all plugins
45 for each "rule" and passing the rule to each plugin with the expectation
46 that just one plugin will match any given rule.
47 There is a database plugin system intended for many of the uses of data‐
49 bases in Heimdal. The plugin is expected to call heim_db_register(3)
50 from its init entry point to register a DB type. The DB plugin's fini
51 function must do nothing, and the plugin must not provide any other entry
52 points.
53 The krb5_kuserok plugin adds a single field to its struct: a pointer to a
55 function that implements kuserok functionality with the following form:
56 static krb5_error_code
58 kuserok(void *plug_ctx, krb5_context context, const char *rule,
59 unsigned int flags, const char *k5login_dir,
60 const char *luser, krb5_const_principal principal,
61 krb5_boolean *result)
62 The luser , principal and result arguments are self-explanatory (see
64 krb5_kuserok(3) ). The plug_ctx argument is the context output by the
65 plugin's init function. The rule argument is a kuserok rule from the
66 krb5.conf file; each plugin is invoked once for each rule until all plug‐
67 ins fail or one succeeds. The k5login_dir argument provides an alterna‐
68 tive k5login file location, if not NULL. The flags argument indicates
69 whether the plugin may call krb5_aname_to_localname(3)
70 (KUSEROK_ANAME_TO_LNAME_OK), and whether k5login databases are expected
71 to be authoritative (KUSEROK_K5LOGIN_IS_AUTHORITATIVE).
72 The plugin for krb5_aname_to_localname(3) is named "an2ln" and has a sin‐
74 gle extra field for the plugin struct:
75 typedef krb5_error_code (*set_result_f)(void *, const char *);
77 static krb5_error_code
79 an2ln(void *plug_ctx, krb5_context context, const char *rule,
80 krb5_const_principal aname, set_result_f set_res_f, void *set_res_ctx)
81 The arguments for the an2ln plugin are similar to those of the kuserok
83 plugin, but the result, being a string, is set by calling the set_res_f
84 function argument with the set_res_ctx and result string as arguments.
85 The set_res_f function will make a copy of the string.
86
88 libdir/plugin/krb5/* Shared objects containing plugins for
89 Heimdal.
90
92 An example an2ln plugin that maps principals to a constant "nouser" fol‐
93 lows:
94 #include <krb5/an2ln_plugin.h>
96 static krb5_error_code
98 nouser_plug_init(krb5_context context, void **ctx)
99 {
100 *ctx = NULL;
101 return 0;
102 }
103 static void nouser_plug_fini(void *ctx) { }
105 static krb5_error_code
107 nouser_plug_an2ln(void *plug_ctx, krb5_context context,
108 const char *rule,
109 krb5_const_principal aname,
110 set_result_f set_res_f, void *set_res_ctx)
111 {
112 krb5_error_code ret;
113 if (strcmp(rule, "NOUSER") != 0)
115 return KRB5_PLUGIN_NO_HANDLE;
116 ret = set_res_f(set_res_ctx, "nouser");
118 return ret;
120 }
121 krb5plugin_an2ln_ftable an2ln = {
123 KRB5_PLUGIN_AN2LN_VERSION_0,
124 nouser_plug_init,
125 nouser_plug_fini,
126 nouser_plug_an2ln,
127 };
128 An example kuserok plugin that rejects all requests follows. (Note that
130 there exists a built-in plugin with this functionality; see
131 krb5_kuserok(3) ).
132 #include <krb5/kuserok_plugin.h>
134 static krb5_error_code
136 reject_plug_init(krb5_context context, void **ctx)
137 {
138 *ctx = NULL;
139 return 0;
140 }
141 static void reject_plug_fini(void *ctx) { }
143 static krb5_error_code
145 reject_plug_kuserok(void *plug_ctx, krb5_context context, const char *rule,
146 unsigned int flags, const char *k5login_dir,
147 const char *luser, krb5_const_principal principal,
148 krb5_boolean *result)
149 {
150 if (strcmp(rule, "REJECT") != 0)
151 return KRB5_PLUGIN_NO_HANDLE;
152 *result = FALSE;
154 return 0;
155 }
156 krb5plugin_kuserok_ftable kuserok = {
158 KRB5_PLUGIN_KUSEROK_VERSION_0,
159 reject_plug_init,
160 reject_plug_fini,
161 reject_plug_kuserok,
162 };
163
165 krb5_plugin_register(3) krb5_kuserok(3) krb5_aname_to_localname(3)
166HEIMDAL December 21, 2011 HEIMDAL