mech_eap/authdata_plugin.h

   1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /*
   3  * krb5/authdata_plugin.h
   4  *
   5  * Copyright (C) 2007 Apple Inc.  All Rights Reserved.
   6  *
   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.
  11  *
  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.
  25  *
  26  * AuthorizationData plugin definitions for Kerberos 5.
  27  */
  28
  29 /*
  30  * This is considered an INTERNAL interface at this time.
  31  *
  32  * Some work is needed before exporting it:
  33  *
  34  * + Documentation.
  35  * + Sample code.
  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
  39  *   change API.
  40  *
  41  * Other changes that would be nice to have, but not necessarily
  42  * before making this interface public:
  43  *
  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.)
  50  */
  51
  52 #ifndef KRB5_AUTHDATA_PLUGIN_H_INCLUDED
  53 #define KRB5_AUTHDATA_PLUGIN_H_INCLUDED
  54 #include <krb5/krb5.h>
  55
  56 /*
  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.
  60  */
  61 struct _krb5_db_entry_new;
  62
  63 /*
  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
  69  * functions.
  70  */
  71 /* extern krb5plugin_authdata_ftable_v0 authdata_server_0; */
  72 typedef struct krb5plugin_authdata_server_ftable_v0 {
  73     /* Not-usually-visible name. */
  74     char *name;
  75
  76     /*
  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.
  80      */
  81     krb5_error_code (*init_proc)(krb5_context, void **);
  82     void (*fini_proc)(krb5_context, void *);
  83     /*
  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.
  87      *
  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
  92      * plugins in use.
  93      *
  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
  99      * running on Windows.
 100      *
 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).
 105      */
 106     krb5_error_code (*authdata_proc)(krb5_context,
 107                                      struct _krb5_db_entry_new *client,
 108                                      krb5_data *req_pkt,
 109                                      krb5_kdc_req *request,
 110                                      krb5_enc_tkt_part *enc_tkt_reply);
 111 } krb5plugin_server_authdata_ftable_v0;
 112
 113 typedef krb5plugin_server_authdata_ftable_v0 krb5plugin_authdata_ftable_v0;
 114
 115 typedef struct krb5plugin_authdata_server_ftable_v2 {
 116     /* Not-usually-visible name. */
 117     char *name;
 118
 119     /*
 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.
 123      */
 124     krb5_error_code (*init_proc)(krb5_context, void **);
 125     void (*fini_proc)(krb5_context, void *);
 126     /*
 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.
 130      *
 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
 135      * plugins in use.
 136      *
 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.
 143      *
 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).
 148      */
 149     krb5_error_code (*authdata_proc)(krb5_context,
 150                                      unsigned int flags,
 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,
 157                                      krb5_data *req_pkt,
 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;
 163
 164 typedef krb5plugin_authdata_server_ftable_v2 krb5plugin_authdata_ftable_v2;
 165
 166 typedef krb5_error_code
 167 (*authdata_client_plugin_init_proc)(krb5_context context,
 168                                     void **plugin_context);
 169
 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
 176
 177 struct _krb5_authdata_context;
 178
 179 typedef void
 180 (*authdata_client_plugin_flags_proc)(krb5_context kcontext,
 181                                      void *plugin_context,
 182                                      krb5_authdatatype ad_type,
 183                                      krb5_flags *flags);
 184
 185 typedef void
 186 (*authdata_client_plugin_fini_proc)(krb5_context kcontext,
 187                                     void *plugin_context);
 188
 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);
 194
 195 typedef void
 196 (*authdata_client_request_fini_proc)(krb5_context kcontext,
 197                                      struct _krb5_authdata_context *context,
 198                                      void *plugin_context,
 199                                      void *request_context);
 200
 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);
 209
 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,
 215                                         krb5_flags usage,
 216                                         krb5_authdata ***authdata);
 217
 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,
 223                                             krb5_data **attrs);
 224
 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,
 233                                       krb5_data *value,
 234                                       krb5_data *display_value,
 235                                       int *more);
 236
 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);
 245
 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);
 252
 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,
 259                                         void **ptr);
 260
 261 typedef void
 262 (*authdata_client_free_internal_proc)(krb5_context kcontext,
 263                                       struct _krb5_authdata_context *context,
 264                                       void *plugin_context,
 265                                       void *request_context,
 266                                       void *ptr);
 267
 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);
 276
 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,
 282                              size_t *sizep);
 283
 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,
 289                                     krb5_octet **buffer,
 290                                     size_t *lenremain);
 291
 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,
 297                                     krb5_octet **buffer,
 298                                     size_t *lenremain);
 299
 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);
 307
 308 typedef struct krb5plugin_authdata_client_ftable_v0 {
 309     char *name;
 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;
 330
 331 #endif /* KRB5_AUTHDATA_PLUGIN_H_INCLUDED */