1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
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
|
