1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ 2 /* 3 * Copyright (c) 2006 Red Hat, Inc. 4 * Portions copyright (c) 2006, 2011 Massachusetts Institute of Technology 5 * All Rights Reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions are met: 9 * 10 * * Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in 14 * the documentation and/or other materials provided with the 15 * distribution. 16 * * Neither the name of Red Hat, Inc., nor the names of its 17 * contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 21 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 22 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 23 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 24 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /* 34 * Declarations for clpreauth plugin module implementors. 35 * 36 * The clpreauth interface has a single supported major version, which is 37 * 1. Major version 1 has a current minor version of 2. clpreauth modules 38 * should define a function named clpreauth_<modulename>_initvt, matching 39 * the signature: 40 * 41 * krb5_error_code 42 * clpreauth_modname_initvt(krb5_context context, int maj_ver, 43 * int min_ver, krb5_plugin_vtable vtable); 44 * The initvt function should: 45 * 46 * - Check that the supplied maj_ver number is supported by the module, or 47 * return KRB5_PLUGIN_VER_NOTSUPP if it is not. 48 * 49 * - Cast the vtable pointer as appropriate for the interface and maj_ver: 50 * maj_ver == 1: Cast to krb5_clpreauth_vtable 51 * 52 * - Initialize the methods of the vtable, stopping as appropriate for the 53 * supplied min_ver. Optional methods may be left uninitialized. 54 * 55 * Memory for the vtable is allocated by the caller, not by the module. 56 */ 57 58 #ifndef KRB5_CLPREAUTH_PLUGIN_H 59 #define KRB5_CLPREAUTH_PLUGIN_H 60 61 #include <krb5/krb5.h> 62 #include <krb5/plugin.h> 63 64 /* clpreauth mechanism property flags */ 65 66 /* Provides a real answer which we can send back to the KDC. The client 67 * assumes that one real answer will be enough. */ 68 #define PA_REAL 0x00000001 69 70 /* Doesn't provide a real answer, but must be given a chance to run before any 71 * REAL mechanism callbacks. */ 72 #define PA_INFO 0x00000002 73 74 /* Abstract type for a client request information handle. */ 75 typedef struct krb5_clpreauth_rock_st *krb5_clpreauth_rock; 76 77 /* Abstract types for module data and per-request module data. */ 78 typedef struct krb5_clpreauth_moddata_st *krb5_clpreauth_moddata; 79 typedef struct krb5_clpreauth_modreq_st *krb5_clpreauth_modreq; 80 81 /* Before using a callback after version 1, modules must check the vers 82 * field of the callback structure. */ 83 typedef struct krb5_clpreauth_callbacks_st { 84 int vers; 85 86 /* 87 * If an AS-REP has been received, return the enctype of the AS-REP 88 * encrypted part. Otherwise return the enctype chosen from etype-info, or 89 * the first requested enctype if no etype-info was received. 90 */ 91 krb5_enctype (*get_etype)(krb5_context context, krb5_clpreauth_rock rock); 92 93 /* Get a pointer to the FAST armor key, or NULL if the client is not using 94 * FAST. The returned pointer is an alias and should not be freed. */ 95 krb5_keyblock *(*fast_armor)(krb5_context context, 96 krb5_clpreauth_rock rock); 97 98 /* 99 * Get a pointer to the client-supplied reply key, possibly invoking the 100 * prompter to ask for a password if this has not already been done. The 101 * returned pointer is an alias and should not be freed. 102 */ 103 krb5_error_code (*get_as_key)(krb5_context context, 104 krb5_clpreauth_rock rock, 105 krb5_keyblock **keyblock); 106 107 /* Replace the reply key to be used to decrypt the AS response. */ 108 krb5_error_code (*set_as_key)(krb5_context context, 109 krb5_clpreauth_rock rock, 110 const krb5_keyblock *keyblock); 111 112 /* End of version 1 clpreauth callbacks. */ 113 114 /* 115 * Get the current time for use in a preauth response. If 116 * allow_unauth_time is true and the library has been configured to allow 117 * it, the current time will be offset using unauthenticated timestamp 118 * information received from the KDC in the preauth-required error, if one 119 * has been received. Otherwise, the timestamp in a preauth-required error 120 * will only be used if it is protected by a FAST channel. Only set 121 * allow_unauth_time if using an unauthenticated time offset would not 122 * create a security issue. 123 */ 124 krb5_error_code (*get_preauth_time)(krb5_context context, 125 krb5_clpreauth_rock rock, 126 krb5_boolean allow_unauth_time, 127 krb5_timestamp *time_out, 128 krb5_int32 *usec_out); 129 130 /* Set a question to be answered by the responder and optionally provide 131 * a challenge. */ 132 krb5_error_code (*ask_responder_question)(krb5_context context, 133 krb5_clpreauth_rock rock, 134 const char *question, 135 const char *challenge); 136 137 /* Get an answer from the responder, or NULL if the question was 138 * unanswered. */ 139 const char *(*get_responder_answer)(krb5_context context, 140 krb5_clpreauth_rock rock, 141 const char *question); 142 143 /* Indicate interest in the AS key through the responder interface. */ 144 void (*need_as_key)(krb5_context context, krb5_clpreauth_rock rock); 145 146 /* 147 * Get a configuration/state item from an input ccache, which may allow it 148 * to retrace the steps it took last time. The returned data string is an 149 * alias and should not be freed. 150 */ 151 const char *(*get_cc_config)(krb5_context context, 152 krb5_clpreauth_rock rock, const char *key); 153 154 /* 155 * Set a configuration/state item which will be recorded to an output 156 * ccache, if the calling application supplied one. Both key and data 157 * should be valid UTF-8 text. 158 */ 159 krb5_error_code (*set_cc_config)(krb5_context context, 160 krb5_clpreauth_rock rock, 161 const char *key, const char *data); 162 163 /* End of version 2 clpreauth callbacks (added in 1.11). */ 164 165 /* 166 * Prevent further fallbacks to other preauth mechanisms if the KDC replies 167 * with an error. (The module itself can still respond to errors with its 168 * tryagain method, or continue after KDC_ERR_MORE_PREAUTH_DATA_REQUIRED 169 * errors with its process method.) A module should invoke this callback 170 * from the process method when it generates an authenticated request using 171 * credentials; often this will be the first or only client message 172 * generated by the mechanism. 173 */ 174 void (*disable_fallback)(krb5_context context, krb5_clpreauth_rock rock); 175 176 /* End of version 3 clpreauth callbacks (added in 1.17). */ 177 } *krb5_clpreauth_callbacks; 178 179 /* 180 * Optional: per-plugin initialization/cleanup. The init function is called by 181 * libkrb5 when the plugin is loaded, and the fini function is called before 182 * the plugin is unloaded. These may be called multiple times in case the 183 * plugin is used in multiple contexts. The returned context lives the 184 * lifetime of the krb5_context. 185 */ 186 typedef krb5_error_code 187 (*krb5_clpreauth_init_fn)(krb5_context context, 188 krb5_clpreauth_moddata *moddata_out); 189 typedef void 190 (*krb5_clpreauth_fini_fn)(krb5_context context, 191 krb5_clpreauth_moddata moddata); 192 193 /* 194 * Optional (mandatory before MIT krb5 1.12): pa_type will be a member of the 195 * vtable's pa_type_list. Return PA_REAL if pa_type is a real 196 * preauthentication type or PA_INFO if it is an informational type. If this 197 * function is not defined in 1.12 or later, all pa_type values advertised by 198 * the module will be assumed to be real. 199 */ 200 typedef int 201 (*krb5_clpreauth_get_flags_fn)(krb5_context context, krb5_preauthtype pa_type); 202 203 /* 204 * Optional: per-request initialization/cleanup. The request_init function is 205 * called when beginning to process a get_init_creds request and the 206 * request_fini function is called when processing of the request is complete. 207 * This is optional. It may be called multiple times in the lifetime of a 208 * krb5_context. 209 */ 210 typedef void 211 (*krb5_clpreauth_request_init_fn)(krb5_context context, 212 krb5_clpreauth_moddata moddata, 213 krb5_clpreauth_modreq *modreq_out); 214 typedef void 215 (*krb5_clpreauth_request_fini_fn)(krb5_context context, 216 krb5_clpreauth_moddata moddata, 217 krb5_clpreauth_modreq modreq); 218 219 /* 220 * Optional: process server-supplied data in pa_data and set responder 221 * questions. 222 * 223 * encoded_previous_request may be NULL if there has been no previous request 224 * in the AS exchange. 225 */ 226 typedef krb5_error_code 227 (*krb5_clpreauth_prep_questions_fn)(krb5_context context, 228 krb5_clpreauth_moddata moddata, 229 krb5_clpreauth_modreq modreq, 230 krb5_get_init_creds_opt *opt, 231 krb5_clpreauth_callbacks cb, 232 krb5_clpreauth_rock rock, 233 krb5_kdc_req *request, 234 krb5_data *encoded_request_body, 235 krb5_data *encoded_previous_request, 236 krb5_pa_data *pa_data); 237 238 /* 239 * Mandatory: process server-supplied data in pa_data and return created data 240 * in pa_data_out. Also called after the AS-REP is received if the AS-REP 241 * includes preauthentication data of the associated type. 242 * 243 * as_key contains the client-supplied key if known, or an empty keyblock if 244 * not. If it is empty, the module may use gak_fct to fill it in. 245 * 246 * encoded_previous_request may be NULL if there has been no previous request 247 * in the AS exchange. 248 */ 249 typedef krb5_error_code 250 (*krb5_clpreauth_process_fn)(krb5_context context, 251 krb5_clpreauth_moddata moddata, 252 krb5_clpreauth_modreq modreq, 253 krb5_get_init_creds_opt *opt, 254 krb5_clpreauth_callbacks cb, 255 krb5_clpreauth_rock rock, 256 krb5_kdc_req *request, 257 krb5_data *encoded_request_body, 258 krb5_data *encoded_previous_request, 259 krb5_pa_data *pa_data, 260 krb5_prompter_fct prompter, void *prompter_data, 261 krb5_pa_data ***pa_data_out); 262 263 /* 264 * Optional: Attempt to use error and error_padata to try to recover from the 265 * given error. To work with both FAST and non-FAST errors, an implementation 266 * should generally consult error_padata rather than decoding error->e_data. 267 * For non-FAST errors, it contains the e_data decoded as either pa-data or 268 * typed-data. 269 * 270 * If this function is provided, and it returns 0 and stores data in 271 * pa_data_out, then the client library will retransmit the request. 272 */ 273 typedef krb5_error_code 274 (*krb5_clpreauth_tryagain_fn)(krb5_context context, 275 krb5_clpreauth_moddata moddata, 276 krb5_clpreauth_modreq modreq, 277 krb5_get_init_creds_opt *opt, 278 krb5_clpreauth_callbacks cb, 279 krb5_clpreauth_rock rock, 280 krb5_kdc_req *request, 281 krb5_data *encoded_request_body, 282 krb5_data *encoded_previous_request, 283 krb5_preauthtype pa_type, 284 krb5_error *error, 285 krb5_pa_data **error_padata, 286 krb5_prompter_fct prompter, void *prompter_data, 287 krb5_pa_data ***pa_data_out); 288 289 /* 290 * Optional: receive krb5_get_init_creds_opt information. The attr and value 291 * information supplied should be copied into moddata by the module if it 292 * wishes to reference it after returning from this call. 293 */ 294 typedef krb5_error_code 295 (*krb5_clpreauth_supply_gic_opts_fn)(krb5_context context, 296 krb5_clpreauth_moddata moddata, 297 krb5_get_init_creds_opt *opt, 298 const char *attr, const char *value); 299 300 typedef struct krb5_clpreauth_vtable_st { 301 /* Mandatory: name of module. */ 302 const char *name; 303 304 /* Mandatory: pointer to zero-terminated list of pa_types which this module 305 * can provide services for. */ 306 krb5_preauthtype *pa_type_list; 307 308 /* Optional: pointer to zero-terminated list of enc_types which this module 309 * claims to add support for. */ 310 krb5_enctype *enctype_list; 311 312 krb5_clpreauth_init_fn init; 313 krb5_clpreauth_fini_fn fini; 314 krb5_clpreauth_get_flags_fn flags; 315 krb5_clpreauth_request_init_fn request_init; 316 krb5_clpreauth_request_fini_fn request_fini; 317 krb5_clpreauth_process_fn process; 318 krb5_clpreauth_tryagain_fn tryagain; 319 krb5_clpreauth_supply_gic_opts_fn gic_opts; 320 /* Minor version 1 ends here. */ 321 322 krb5_clpreauth_prep_questions_fn prep_questions; 323 /* Minor version 2 ends here. */ 324 } *krb5_clpreauth_vtable; 325 326 /* 327 * This function allows a clpreauth plugin to obtain preauth options. The 328 * preauth_data returned from this function should be freed by calling 329 * krb5_get_init_creds_opt_free_pa(). 330 */ 331 krb5_error_code KRB5_CALLCONV 332 krb5_get_init_creds_opt_get_pa(krb5_context context, 333 krb5_get_init_creds_opt *opt, 334 int *num_preauth_data, 335 krb5_gic_opt_pa_data **preauth_data); 336 337 /* 338 * This function frees the preauth_data that was returned by 339 * krb5_get_init_creds_opt_get_pa(). 340 */ 341 void KRB5_CALLCONV 342 krb5_get_init_creds_opt_free_pa(krb5_context context, 343 int num_preauth_data, 344 krb5_gic_opt_pa_data *preauth_data); 345 346 #endif /* KRB5_CLPREAUTH_PLUGIN_H */ 347