1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
3 * krb5/authdata_plugin.h
5 * Copyright (C) 2007 Apple Inc. All Rights Reserved.
7 * Export of this software from the United States of America may
8 * require a specific license from the United States Government.
9 * It is the responsibility of any person or organization contemplating
10 * export to obtain such a license before exporting.
12 * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
13 * distribute this software and its documentation for any purpose and
14 * without fee is hereby granted, provided that the above copyright
15 * notice appear in all copies and that both that copyright notice and
16 * this permission notice appear in supporting documentation, and that
17 * the name of M.I.T. not be used in advertising or publicity pertaining
18 * to distribution of the software without specific, written prior
19 * permission. Furthermore if you modify this software you must label
20 * your software as modified software and not distribute it in such a
21 * fashion that it might be confused with the original M.I.T. software.
22 * M.I.T. makes no representations about the suitability of
23 * this software for any purpose. It is provided "as is" without express
24 * or implied warranty.
26 * AuthorizationData plugin definitions for Kerberos 5.
30 * This is considered an INTERNAL interface at this time.
32 * Some work is needed before exporting it:
36 * + Test cases (preferably automated testing under "make check").
37 * + Hook into TGS exchange too; will change API.
38 * + Examine memory management issues, especially for Windows; may
41 * Other changes that would be nice to have, but not necessarily
42 * before making this interface public:
44 * + Library support for AD-IF-RELEVANT and similar wrappers. (We can
45 * make the plugin construct them if it wants them.)
46 * + KDC could combine/optimize wrapped AD elements provided by
47 * multiple plugins, e.g., two IF-RELEVANT sequences could be
48 * merged. (The preauth plugin API also has this bug, we're going
49 * to need a general fix.)
52 #ifndef KRB5_AUTHDATA_PLUGIN_H_INCLUDED
53 #define KRB5_AUTHDATA_PLUGIN_H_INCLUDED
54 #include <krb5/krb5.h>
57 * While arguments of these types are passed-in, for the most part a
58 * authorization data module can treat them as opaque. If we need
59 * keying data, we can ask for it directly.
61 struct _krb5_db_entry_new;
64 * The function table / structure which an authdata server module must export as
65 * "authdata_server_0". NOTE: replace "0" with "1" for the type and
66 * variable names if this gets picked up by upstream. If the interfaces work
67 * correctly, future versions of the table will add either more callbacks or
68 * more arguments to callbacks, and in both cases we'll be able to wrap the v0
71 /* extern krb5plugin_authdata_ftable_v0 authdata_server_0; */
72 typedef struct krb5plugin_authdata_server_ftable_v0 {
73 /* Not-usually-visible name. */
77 * Per-plugin initialization/cleanup. The init function is called
78 * by the KDC when the plugin is loaded, and the fini function is
79 * called before the plugin is unloaded. Both are optional.
81 krb5_error_code (*init_proc)(krb5_context, void **);
82 void (*fini_proc)(krb5_context, void *);
84 * Actual authorization data handling function. If this field
85 * holds a null pointer, this mechanism will be skipped, and the
86 * init/fini functions will not be run.
88 * This function should only modify the field
89 * enc_tkt_reply->authorization_data. All other values should be
90 * considered inputs only. And, it should *modify* the field, not
91 * overwrite it and assume that there are no other authdata
94 * Memory management: authorization_data is a malloc-allocated,
95 * null-terminated sequence of malloc-allocated pointers to
96 * authorization data structures. This plugin code currently
97 * assumes the libraries, KDC, and plugin all use the same malloc
98 * pool, which may be a problem if/when we get the KDC code
101 * If this function returns a non-zero error code, a message
102 * is logged, but no other action is taken. Other authdata
103 * plugins will be called, and a response will be sent to the
104 * client (barring other problems).
106 krb5_error_code (*authdata_proc)(krb5_context,
107 struct _krb5_db_entry_new *client,
109 krb5_kdc_req *request,
110 krb5_enc_tkt_part *enc_tkt_reply);
111 } krb5plugin_server_authdata_ftable_v0;
113 typedef krb5plugin_server_authdata_ftable_v0 krb5plugin_authdata_ftable_v0;
115 typedef struct krb5plugin_authdata_server_ftable_v2 {
116 /* Not-usually-visible name. */
120 * Per-plugin initialization/cleanup. The init function is called
121 * by the KDC when the plugin is loaded, and the fini function is
122 * called before the plugin is unloaded. Both are optional.
124 krb5_error_code (*init_proc)(krb5_context, void **);
125 void (*fini_proc)(krb5_context, void *);
127 * Actual authorization data handling function. If this field
128 * holds a null pointer, this mechanism will be skipped, and the
129 * init/fini functions will not be run.
131 * This function should only modify the field
132 * enc_tkt_reply->authorization_data. All other values should be
133 * considered inputs only. And, it should *modify* the field, not
134 * overwrite it and assume that there are no other authdata
137 * Memory management: authorization_data is a malloc-allocated,
138 * null-terminated sequence of malloc-allocated pointers to
139 * authorization data structures. This plugin code currently
140 * assumes the libraries, KDC, and plugin all use the same malloc
141 * pool, which may be a problem if/when we get the KDC code
142 * running on Windows.
144 * If this function returns a non-zero error code, a message
145 * is logged, but no other action is taken. Other authdata
146 * plugins will be called, and a response will be sent to the
147 * client (barring other problems).
149 krb5_error_code (*authdata_proc)(krb5_context,
151 struct _krb5_db_entry_new *client,
152 struct _krb5_db_entry_new *server,
153 struct _krb5_db_entry_new *tgs,
154 krb5_keyblock *client_key,
155 krb5_keyblock *server_key,
156 krb5_keyblock *tgs_key,
158 krb5_kdc_req *request,
159 krb5_const_principal for_user_princ,
160 krb5_enc_tkt_part *enc_tkt_request,
161 krb5_enc_tkt_part *enc_tkt_reply);
162 } krb5plugin_authdata_server_ftable_v2;
164 typedef krb5plugin_authdata_server_ftable_v2 krb5plugin_authdata_ftable_v2;
166 typedef krb5_error_code
167 (*authdata_client_plugin_init_proc)(krb5_context context,
168 void **plugin_context);
170 #define AD_USAGE_AS_REQ 0x01
171 #define AD_USAGE_TGS_REQ 0x02
172 #define AD_USAGE_AP_REQ 0x04
173 #define AD_USAGE_KDC_ISSUED 0x08
174 #define AD_USAGE_MASK 0x0F
175 #define AD_INFORMATIONAL 0x10
177 struct _krb5_authdata_context;
180 (*authdata_client_plugin_flags_proc)(krb5_context kcontext,
181 void *plugin_context,
182 krb5_authdatatype ad_type,
186 (*authdata_client_plugin_fini_proc)(krb5_context kcontext,
187 void *plugin_context);
189 typedef krb5_error_code
190 (*authdata_client_request_init_proc)(krb5_context kcontext,
191 struct _krb5_authdata_context *context,
192 void *plugin_context,
193 void **request_context);
196 (*authdata_client_request_fini_proc)(krb5_context kcontext,
197 struct _krb5_authdata_context *context,
198 void *plugin_context,
199 void *request_context);
201 typedef krb5_error_code
202 (*authdata_client_import_authdata_proc)(krb5_context kcontext,
203 struct _krb5_authdata_context *context,
204 void *plugin_context,
205 void *request_context,
206 krb5_authdata **authdata,
207 krb5_boolean kdc_issued_flag,
208 krb5_const_principal issuer);
210 typedef krb5_error_code
211 (*authdata_client_export_authdata_proc)(krb5_context kcontext,
212 struct _krb5_authdata_context *context,
213 void *plugin_context,
214 void *request_context,
216 krb5_authdata ***authdata);
218 typedef krb5_error_code
219 (*authdata_client_get_attribute_types_proc)(krb5_context kcontext,
220 struct _krb5_authdata_context *context,
221 void *plugin_context,
222 void *request_context,
225 typedef krb5_error_code
226 (*authdata_client_get_attribute_proc)(krb5_context kcontext,
227 struct _krb5_authdata_context *context,
228 void *plugin_context,
229 void *request_context,
230 const krb5_data *attribute,
231 krb5_boolean *authenticated,
232 krb5_boolean *complete,
234 krb5_data *display_value,
237 typedef krb5_error_code
238 (*authdata_client_set_attribute_proc)(krb5_context kcontext,
239 struct _krb5_authdata_context *context,
240 void *plugin_context,
241 void *request_context,
242 krb5_boolean complete,
243 const krb5_data *attribute,
244 const krb5_data *value);
246 typedef krb5_error_code
247 (*authdata_client_delete_attribute_proc)(krb5_context kcontext,
248 struct _krb5_authdata_context *context,
249 void *plugin_context,
250 void *request_context,
251 const krb5_data *attribute);
253 typedef krb5_error_code
254 (*authdata_client_export_internal_proc)(krb5_context kcontext,
255 struct _krb5_authdata_context *context,
256 void *plugin_context,
257 void *request_context,
258 krb5_boolean restrict_authenticated,
262 (*authdata_client_free_internal_proc)(krb5_context kcontext,
263 struct _krb5_authdata_context *context,
264 void *plugin_context,
265 void *request_context,
268 typedef krb5_error_code
269 (*authdata_client_verify_proc)(krb5_context kcontext,
270 struct _krb5_authdata_context *context,
271 void *plugin_context,
272 void *request_context,
273 const krb5_auth_context *auth_context,
274 const krb5_keyblock *key,
275 const krb5_ap_req *req);
277 typedef krb5_error_code
278 (*authdata_client_size_proc)(krb5_context kcontext,
279 struct _krb5_authdata_context *context,
280 void *plugin_context,
281 void *request_context,
284 typedef krb5_error_code
285 (*authdata_client_externalize_proc)(krb5_context kcontext,
286 struct _krb5_authdata_context *context,
287 void *plugin_context,
288 void *request_context,
292 typedef krb5_error_code
293 (*authdata_client_internalize_proc)(krb5_context kcontext,
294 struct _krb5_authdata_context *context,
295 void *plugin_context,
296 void *request_context,
300 typedef krb5_error_code
301 (*authdata_client_copy_proc)(krb5_context kcontext,
302 struct _krb5_authdata_context *context,
303 void *plugin_context,
304 void *request_context,
305 void *dst_plugin_context,
306 void *dst_request_context);
308 typedef struct krb5plugin_authdata_client_ftable_v0 {
310 krb5_authdatatype *ad_type_list;
311 authdata_client_plugin_init_proc init;
312 authdata_client_plugin_fini_proc fini;
313 authdata_client_plugin_flags_proc flags;
314 authdata_client_request_init_proc request_init;
315 authdata_client_request_fini_proc request_fini;
316 authdata_client_get_attribute_types_proc get_attribute_types;
317 authdata_client_get_attribute_proc get_attribute;
318 authdata_client_set_attribute_proc set_attribute;
319 authdata_client_delete_attribute_proc delete_attribute;
320 authdata_client_export_authdata_proc export_authdata;
321 authdata_client_import_authdata_proc import_authdata;
322 authdata_client_export_internal_proc export_internal;
323 authdata_client_free_internal_proc free_internal;
324 authdata_client_verify_proc verify;
325 authdata_client_size_proc size;
326 authdata_client_externalize_proc externalize;
327 authdata_client_internalize_proc internalize;
328 authdata_client_copy_proc copy; /* optional */
329 } krb5plugin_authdata_client_ftable_v0;
331 #endif /* KRB5_AUTHDATA_PLUGIN_H_INCLUDED */