1159d09a2SMark Phalan 2159d09a2SMark Phalan /* 3159d09a2SMark Phalan * <krb5/preauth_plugin.h> 4159d09a2SMark Phalan * 5159d09a2SMark Phalan * Copyright (c) 2006 Red Hat, Inc. 6159d09a2SMark Phalan * Portions copyright (c) 2006 Massachusetts Institute of Technology 7159d09a2SMark Phalan * All Rights Reserved. 8159d09a2SMark Phalan * 9159d09a2SMark Phalan * Redistribution and use in source and binary forms, with or without 10159d09a2SMark Phalan * modification, are permitted provided that the following conditions are met: 11159d09a2SMark Phalan * 12159d09a2SMark Phalan * * Redistributions of source code must retain the above copyright 13159d09a2SMark Phalan * notice, this list of conditions and the following disclaimer. 14159d09a2SMark Phalan * * Redistributions in binary form must reproduce the above copyright 15159d09a2SMark Phalan * notice, this list of conditions and the following disclaimer in 16159d09a2SMark Phalan * the documentation and/or other materials provided with the 17159d09a2SMark Phalan * distribution. 18159d09a2SMark Phalan * * Neither the name of Red Hat, Inc., nor the names of its 19159d09a2SMark Phalan * contributors may be used to endorse or promote products derived 20159d09a2SMark Phalan * from this software without specific prior written permission. 21159d09a2SMark Phalan * 22159d09a2SMark Phalan * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 23159d09a2SMark Phalan * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 24159d09a2SMark Phalan * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 25159d09a2SMark Phalan * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 26159d09a2SMark Phalan * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 27159d09a2SMark Phalan * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 28159d09a2SMark Phalan * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 29159d09a2SMark Phalan * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 30159d09a2SMark Phalan * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 31159d09a2SMark Phalan * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 32159d09a2SMark Phalan * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 33159d09a2SMark Phalan * 34159d09a2SMark Phalan * Preauthentication plugin definitions for Kerberos 5. 35159d09a2SMark Phalan */ 36159d09a2SMark Phalan 37159d09a2SMark Phalan #ifndef KRB5_PREAUTH_PLUGIN_H_INCLUDED 38159d09a2SMark Phalan #define KRB5_PREAUTH_PLUGIN_H_INCLUDED 39159d09a2SMark Phalan #include <krb5.h> 40159d09a2SMark Phalan 41159d09a2SMark Phalan /* 42159d09a2SMark Phalan * While arguments of these types are passed-in, for the most part a preauth 43159d09a2SMark Phalan * module can treat them as opaque. If we need keying data, we can ask for 44159d09a2SMark Phalan * it directly. 45159d09a2SMark Phalan */ 46159d09a2SMark Phalan struct _krb5_db_entry_new; 47159d09a2SMark Phalan struct _krb5_key_data; 48159d09a2SMark Phalan struct _krb5_preauth_client_rock; 49159d09a2SMark Phalan 50159d09a2SMark Phalan /* 51159d09a2SMark Phalan * Preauth mechanism property flags, unified from previous definitions in the 52159d09a2SMark Phalan * KDC and libkrb5 sources. 53159d09a2SMark Phalan */ 54159d09a2SMark Phalan 55159d09a2SMark Phalan /* Provides a real answer which we can send back to the KDC (client-only). The 56159d09a2SMark Phalan * client assumes that one real answer will be enough. */ 57159d09a2SMark Phalan #define PA_REAL 0x00000001 58159d09a2SMark Phalan 59159d09a2SMark Phalan /* Doesn't provide a real answer, but must be given a chance to run before any 60159d09a2SMark Phalan * REAL mechanism callbacks (client-only). */ 61159d09a2SMark Phalan #define PA_INFO 0x00000002 62159d09a2SMark Phalan 63159d09a2SMark Phalan /* Causes the KDC to include this mechanism in a list of supported preauth 64159d09a2SMark Phalan * types if the user's DB entry flags the user as requiring hardware-based 65159d09a2SMark Phalan * preauthentication (server-only). */ 66159d09a2SMark Phalan #define PA_HARDWARE 0x00000004 67159d09a2SMark Phalan 68159d09a2SMark Phalan /* Causes the KDC to include this mechanism in a list of supported preauth 69159d09a2SMark Phalan * types if the user's DB entry flags the user as requiring preauthentication, 70159d09a2SMark Phalan * and to fail preauthentication if we can't verify the client data. The 71159d09a2SMark Phalan * flipside of PA_SUFFICIENT (server-only). */ 72159d09a2SMark Phalan #define PA_REQUIRED 0x00000008 73159d09a2SMark Phalan 74159d09a2SMark Phalan /* Causes the KDC to include this mechanism in a list of supported preauth 75159d09a2SMark Phalan * types if the user's DB entry flags the user as requiring preauthentication, 76159d09a2SMark Phalan * and to mark preauthentication as successful if we can verify the client 77159d09a2SMark Phalan * data. The flipside of PA_REQUIRED (server-only). */ 78159d09a2SMark Phalan #define PA_SUFFICIENT 0x00000010 79159d09a2SMark Phalan 80159d09a2SMark Phalan /* Marks this preauthentication mechanism as one which changes the key which is 81159d09a2SMark Phalan * used for encrypting the response to the client. Modules which have this 82159d09a2SMark Phalan * flag have their server_return_proc called before modules which do not, and 83159d09a2SMark Phalan * are passed over if a previously-called module has modified the encrypting 84159d09a2SMark Phalan * key (server-only). */ 85159d09a2SMark Phalan #define PA_REPLACES_KEY 0x00000020 86159d09a2SMark Phalan 87159d09a2SMark Phalan /* Causes the KDC to check with this preauthentication module even if the 88159d09a2SMark Phalan * client has no entry in the realm database. If the module returns a success 89159d09a2SMark Phalan * code, continue processing and assume that its return_padata callback will 90159d09a2SMark Phalan * supply us with a key for encrypting the AS reply (server-only). */ 91159d09a2SMark Phalan /* #define PA_VIRTUAL (0x00000040 | PA_REPLACES_KEY) */ 92159d09a2SMark Phalan 93159d09a2SMark Phalan /* Not really a padata type, so don't include it in any list of preauth types 94159d09a2SMark Phalan * which gets sent over the wire. */ 95159d09a2SMark Phalan #define PA_PSEUDO 0x00000080 96159d09a2SMark Phalan 97159d09a2SMark Phalan 98159d09a2SMark Phalan /*************************************************************************** 99159d09a2SMark Phalan * 100159d09a2SMark Phalan * Client-side preauthentication plugin interface definition. 101159d09a2SMark Phalan * 102159d09a2SMark Phalan ***************************************************************************/ 103159d09a2SMark Phalan 104159d09a2SMark Phalan /* 105159d09a2SMark Phalan * A callback which will obtain the user's long-term AS key by prompting the 106159d09a2SMark Phalan * user for the password, then salting it properly, and so on. For the moment, 107159d09a2SMark Phalan * it's identical to the get_as_key callback used inside of libkrb5, but we 108159d09a2SMark Phalan * define a new typedef here instead of making the existing one public to 109159d09a2SMark Phalan * isolate ourselves from potential future changes. 110159d09a2SMark Phalan */ 111159d09a2SMark Phalan typedef krb5_error_code 112159d09a2SMark Phalan (*preauth_get_as_key_proc)(krb5_context, 113159d09a2SMark Phalan krb5_principal, 114159d09a2SMark Phalan krb5_enctype, 115159d09a2SMark Phalan krb5_prompter_fct, 116159d09a2SMark Phalan void *prompter_data, 117159d09a2SMark Phalan krb5_data *salt, 118159d09a2SMark Phalan krb5_data *s2kparams, 119159d09a2SMark Phalan krb5_keyblock *as_key, 120159d09a2SMark Phalan void *gak_data); 121159d09a2SMark Phalan 122159d09a2SMark Phalan /* 123159d09a2SMark Phalan * A client module's callback functions are allowed to request various 124159d09a2SMark Phalan * information to enable it to process a request. 125159d09a2SMark Phalan */ 126159d09a2SMark Phalan enum krb5plugin_preauth_client_request_type { 127159d09a2SMark Phalan /* The returned krb5_data item holds the enctype used to encrypt the 128159d09a2SMark Phalan * encrypted portion of the AS_REP packet. */ 129159d09a2SMark Phalan krb5plugin_preauth_client_get_etype = 1, 130159d09a2SMark Phalan /* Free the data returned from krb5plugin_preauth_client_req_get_etype */ 131159d09a2SMark Phalan krb5plugin_preauth_client_free_etype = 2 132159d09a2SMark Phalan }; 133159d09a2SMark Phalan typedef krb5_error_code 134159d09a2SMark Phalan (*preauth_get_client_data_proc)(krb5_context, 135159d09a2SMark Phalan struct _krb5_preauth_client_rock *, 136159d09a2SMark Phalan krb5_int32 request_type, 137159d09a2SMark Phalan krb5_data **); 138159d09a2SMark Phalan 139159d09a2SMark Phalan /* Per-plugin initialization/cleanup. The init function is called 140159d09a2SMark Phalan * by libkrb5 when the plugin is loaded, and the fini function is 141159d09a2SMark Phalan * called before the plugin is unloaded. Both are optional and 142159d09a2SMark Phalan * may be called multiple times in case the plugin is used in 143159d09a2SMark Phalan * multiple contexts. The returned context lives the lifetime of 144159d09a2SMark Phalan * the krb5_context */ 145159d09a2SMark Phalan typedef krb5_error_code 146159d09a2SMark Phalan (*preauth_client_plugin_init_proc)(krb5_context context, 147159d09a2SMark Phalan void **plugin_context); 148159d09a2SMark Phalan typedef void 149159d09a2SMark Phalan (*preauth_client_plugin_fini_proc)(krb5_context context, 150159d09a2SMark Phalan void *plugin_context); 151159d09a2SMark Phalan 152159d09a2SMark Phalan /* A callback which returns flags indicating if the module is a "real" or 153159d09a2SMark Phalan * an "info" mechanism, and so on. This function is called for each entry 154159d09a2SMark Phalan * in the client_pa_type_list. */ 155159d09a2SMark Phalan typedef int 156159d09a2SMark Phalan (*preauth_client_get_flags_proc)(krb5_context context, 157159d09a2SMark Phalan krb5_preauthtype pa_type); 158159d09a2SMark Phalan 159159d09a2SMark Phalan /* Per-request initialization/cleanup. The request_init function is 160159d09a2SMark Phalan * called when beginning to process a get_init_creds request and the 161159d09a2SMark Phalan * request_fini function is called when processing of the request is 162159d09a2SMark Phalan * complete. This is optional. It may be called multiple times in 163159d09a2SMark Phalan * the lifetime of a krb5_context. */ 164159d09a2SMark Phalan typedef void 165159d09a2SMark Phalan (*preauth_client_request_init_proc)(krb5_context context, 166159d09a2SMark Phalan void *plugin_context, 167159d09a2SMark Phalan void **request_context); 168159d09a2SMark Phalan typedef void 169159d09a2SMark Phalan (*preauth_client_request_fini_proc)(krb5_context context, 170159d09a2SMark Phalan void *plugin_context, 171159d09a2SMark Phalan void *request_context); 172159d09a2SMark Phalan 173159d09a2SMark Phalan /* Client function which processes server-supplied data in pa_data, 174159d09a2SMark Phalan * returns created data in out_pa_data, storing any of its own state in 175159d09a2SMark Phalan * client_context if data for the associated preauthentication type is 176159d09a2SMark Phalan * needed. It is also called after the AS-REP is received if the AS-REP 177159d09a2SMark Phalan * includes preauthentication data of the associated type. 178159d09a2SMark Phalan * NOTE! the encoded_previous_request will be NULL the first time this 179159d09a2SMark Phalan * function is called, because it is expected to only ever contain the data 180159d09a2SMark Phalan * obtained from a previous call to this function. */ 181159d09a2SMark Phalan typedef krb5_error_code 182159d09a2SMark Phalan (*preauth_client_process_proc)(krb5_context context, 183159d09a2SMark Phalan void *plugin_context, 184159d09a2SMark Phalan void *request_context, 185159d09a2SMark Phalan krb5_get_init_creds_opt *opt, 186159d09a2SMark Phalan preauth_get_client_data_proc get_data_proc, 187159d09a2SMark Phalan struct _krb5_preauth_client_rock *rock, 188159d09a2SMark Phalan krb5_kdc_req *request, 189159d09a2SMark Phalan krb5_data *encoded_request_body, 190159d09a2SMark Phalan krb5_data *encoded_previous_request, 191159d09a2SMark Phalan krb5_pa_data *pa_data, 192159d09a2SMark Phalan krb5_prompter_fct prompter, 193159d09a2SMark Phalan void *prompter_data, 194159d09a2SMark Phalan preauth_get_as_key_proc gak_fct, 195159d09a2SMark Phalan void *gak_data, 196159d09a2SMark Phalan krb5_data *salt, 197159d09a2SMark Phalan krb5_data *s2kparams, 198159d09a2SMark Phalan krb5_keyblock *as_key, 199159d09a2SMark Phalan krb5_pa_data ***out_pa_data); 200159d09a2SMark Phalan 201159d09a2SMark Phalan /* Client function which can attempt to use e-data in the error response to 202159d09a2SMark Phalan * try to recover from the given error. If this function is not NULL, and 203159d09a2SMark Phalan * it stores data in out_pa_data which is different data from the contents 204159d09a2SMark Phalan * of in_pa_data, then the client library will retransmit the request. */ 205159d09a2SMark Phalan typedef krb5_error_code 206159d09a2SMark Phalan (*preauth_client_tryagain_proc)(krb5_context context, 207159d09a2SMark Phalan void *plugin_context, 208159d09a2SMark Phalan void *request_context, 209159d09a2SMark Phalan krb5_get_init_creds_opt *opt, 210159d09a2SMark Phalan preauth_get_client_data_proc get_data_proc, 211159d09a2SMark Phalan struct _krb5_preauth_client_rock *rock, 212159d09a2SMark Phalan krb5_kdc_req *request, 213159d09a2SMark Phalan krb5_data *encoded_request_body, 214159d09a2SMark Phalan krb5_data *encoded_previous_request, 215159d09a2SMark Phalan krb5_pa_data *in_pa_data, 216159d09a2SMark Phalan krb5_error *error, 217159d09a2SMark Phalan krb5_prompter_fct prompter, 218159d09a2SMark Phalan void *prompter_data, 219159d09a2SMark Phalan preauth_get_as_key_proc gak_fct, 220159d09a2SMark Phalan void *gak_data, 221159d09a2SMark Phalan krb5_data *salt, 222159d09a2SMark Phalan krb5_data *s2kparams, 223159d09a2SMark Phalan krb5_keyblock *as_key, 224159d09a2SMark Phalan krb5_pa_data ***out_pa_data); 225159d09a2SMark Phalan 226159d09a2SMark Phalan /* 227159d09a2SMark Phalan * Client function which receives krb5_get_init_creds_opt information. 228159d09a2SMark Phalan * The attr and value information supplied should be copied locally by 229159d09a2SMark Phalan * the module if it wishes to reference it after returning from this call. 230159d09a2SMark Phalan */ 231159d09a2SMark Phalan typedef krb5_error_code 232159d09a2SMark Phalan (*preauth_client_supply_gic_opts_proc)(krb5_context context, 233159d09a2SMark Phalan void *plugin_context, 234159d09a2SMark Phalan krb5_get_init_creds_opt *opt, 235159d09a2SMark Phalan const char *attr, 236159d09a2SMark Phalan const char *value); 237159d09a2SMark Phalan 238159d09a2SMark Phalan /* 239159d09a2SMark Phalan * The function table / structure which a preauth client module must export as 240159d09a2SMark Phalan * "preauthentication_client_0". If the interfaces work correctly, future 241159d09a2SMark Phalan * versions of the table will add either more callbacks or more arguments to 242159d09a2SMark Phalan * callbacks, and in both cases we'll be able to wrap the v0 functions. 243159d09a2SMark Phalan */ 244159d09a2SMark Phalan typedef struct krb5plugin_preauth_client_ftable_v1 { 245159d09a2SMark Phalan /* Not-usually-visible name. */ 246159d09a2SMark Phalan char *name; 247159d09a2SMark Phalan 248159d09a2SMark Phalan /* Pointer to zero-terminated list of pa_types which this module can 249159d09a2SMark Phalan * provide services for. */ 250159d09a2SMark Phalan krb5_preauthtype *pa_type_list; 251159d09a2SMark Phalan 252159d09a2SMark Phalan /* Pointer to zero-terminated list of enc_types which this module claims 253159d09a2SMark Phalan * to add support for. */ 254159d09a2SMark Phalan krb5_enctype *enctype_list; 255159d09a2SMark Phalan 256159d09a2SMark Phalan /* Per-plugin initialization/cleanup. The init function is called 257159d09a2SMark Phalan * by libkrb5 when the plugin is loaded, and the fini function is 258159d09a2SMark Phalan * called before the plugin is unloaded. Both are optional and 259159d09a2SMark Phalan * may be called multiple times in case the plugin is used in 260159d09a2SMark Phalan * multiple contexts. The returned context lives the lifetime of 261159d09a2SMark Phalan * the krb5_context */ 262159d09a2SMark Phalan preauth_client_plugin_init_proc init; 263159d09a2SMark Phalan preauth_client_plugin_fini_proc fini; 264159d09a2SMark Phalan 265159d09a2SMark Phalan /* A callback which returns flags indicating if the module is a "real" or 266159d09a2SMark Phalan * an "info" mechanism, and so on. This function is called for each entry 267159d09a2SMark Phalan * in the client_pa_type_list. */ 268159d09a2SMark Phalan preauth_client_get_flags_proc flags; 269159d09a2SMark Phalan 270159d09a2SMark Phalan /* Per-request initialization/cleanup. The request_init function is 271159d09a2SMark Phalan * called when beginning to process a get_init_creds request and the 272159d09a2SMark Phalan * request_fini function is called when processing of the request is 273159d09a2SMark Phalan * complete. This is optional. It may be called multiple times in 274159d09a2SMark Phalan * the lifetime of a krb5_context. */ 275159d09a2SMark Phalan preauth_client_request_init_proc request_init; 276159d09a2SMark Phalan preauth_client_request_fini_proc request_fini; 277159d09a2SMark Phalan 278159d09a2SMark Phalan /* Client function which processes server-supplied data in pa_data, 279159d09a2SMark Phalan * returns created data in out_pa_data, storing any of its own state in 280159d09a2SMark Phalan * client_context if data for the associated preauthentication type is 281159d09a2SMark Phalan * needed. It is also called after the AS-REP is received if the AS-REP 282159d09a2SMark Phalan * includes preauthentication data of the associated type. 283159d09a2SMark Phalan * NOTE! the encoded_previous_request will be NULL the first time this 284159d09a2SMark Phalan * function is called, because it is expected to only ever contain the data 285159d09a2SMark Phalan * obtained from a previous call to this function. */ 286159d09a2SMark Phalan preauth_client_process_proc process; 287159d09a2SMark Phalan 288159d09a2SMark Phalan /* Client function which can attempt to use e-data in the error response to 289159d09a2SMark Phalan * try to recover from the given error. If this function is not NULL, and 290159d09a2SMark Phalan * it stores data in out_pa_data which is different data from the contents 291159d09a2SMark Phalan * of in_pa_data, then the client library will retransmit the request. */ 292159d09a2SMark Phalan preauth_client_tryagain_proc tryagain; 293159d09a2SMark Phalan 294159d09a2SMark Phalan /* 295159d09a2SMark Phalan * Client function which receives krb5_get_init_creds_opt information. 296159d09a2SMark Phalan * The attr and value information supplied should be copied locally by 297159d09a2SMark Phalan * the module if it wishes to reference it after returning from this call. 298159d09a2SMark Phalan */ 299159d09a2SMark Phalan preauth_client_supply_gic_opts_proc gic_opts; 300159d09a2SMark Phalan 301159d09a2SMark Phalan } krb5plugin_preauth_client_ftable_v1; 302159d09a2SMark Phalan 303159d09a2SMark Phalan 304159d09a2SMark Phalan /*************************************************************************** 305159d09a2SMark Phalan * 306159d09a2SMark Phalan * Server-side preauthentication plugin interface definition. 307159d09a2SMark Phalan * 308159d09a2SMark Phalan ***************************************************************************/ 309159d09a2SMark Phalan 310159d09a2SMark Phalan /* 311159d09a2SMark Phalan * A server module's callback functions are allowed to request specific types 312159d09a2SMark Phalan * of information about the given client or server record or request, even 313159d09a2SMark Phalan * though the database records themselves are opaque to the module. 314159d09a2SMark Phalan */ 315159d09a2SMark Phalan enum krb5plugin_preauth_entry_request_type { 316159d09a2SMark Phalan /* The returned krb5_data item holds a DER-encoded X.509 certificate. */ 317159d09a2SMark Phalan krb5plugin_preauth_entry_request_certificate = 1, 318159d09a2SMark Phalan /* The returned krb5_data_item holds a krb5_deltat. */ 319159d09a2SMark Phalan krb5plugin_preauth_entry_max_time_skew = 2, 320159d09a2SMark Phalan /* The returned krb5_data_item holds an array of krb5_keyblock structures, 321159d09a2SMark Phalan * terminated by an entry with key type = 0. 322159d09a2SMark Phalan * Each keyblock should have its contents freed in turn, and then the data 323159d09a2SMark Phalan * item itself should be freed. */ 324159d09a2SMark Phalan krb5plugin_preauth_keys = 3, 325159d09a2SMark Phalan /* The returned krb5_data_item holds the request structure, re-encoded 326159d09a2SMark Phalan * using DER. Unless the client implementation is the same as the server 327159d09a2SMark Phalan * implementation, there's a good chance that the result will not match 328159d09a2SMark Phalan * what the client sent, so don't go creating any fatal errors if it 329159d09a2SMark Phalan * doesn't match up. */ 330159d09a2SMark Phalan krb5plugin_preauth_request_body = 4 331159d09a2SMark Phalan }; 332159d09a2SMark Phalan 333159d09a2SMark Phalan typedef krb5_error_code 334159d09a2SMark Phalan (*preauth_get_entry_data_proc)(krb5_context, 335159d09a2SMark Phalan krb5_kdc_req *, 336159d09a2SMark Phalan struct _krb5_db_entry_new *, 337159d09a2SMark Phalan krb5_int32 request_type, 338159d09a2SMark Phalan krb5_data **); 339159d09a2SMark Phalan 340159d09a2SMark Phalan /* Preauth plugin initialization function */ 341159d09a2SMark Phalan typedef krb5_error_code 342159d09a2SMark Phalan (*preauth_server_init_proc)(krb5_context context, 343159d09a2SMark Phalan void **plugin_context, 344159d09a2SMark Phalan const char** realmnames); 345159d09a2SMark Phalan 346159d09a2SMark Phalan /* Preauth plugin cleanup function */ 347159d09a2SMark Phalan typedef void 348159d09a2SMark Phalan (*preauth_server_fini_proc)(krb5_context context, void *plugin_context); 349159d09a2SMark Phalan 350159d09a2SMark Phalan /* Return the flags which the KDC should use for this module. This is a 351159d09a2SMark Phalan * callback instead of a static value because the module may or may not 352*55fea89dSDan Cross * wish to count itself as a hardware preauthentication module (in other 353159d09a2SMark Phalan * words, the flags may be affected by the configuration, for example if a 354159d09a2SMark Phalan * site administrator can force a particular preauthentication type to be 355159d09a2SMark Phalan * supported using only hardware). This function is called for each entry 356159d09a2SMark Phalan * entry in the server_pa_type_list. */ 357159d09a2SMark Phalan typedef int 358159d09a2SMark Phalan (*preauth_server_flags_proc)(krb5_context context, krb5_preauthtype patype); 359159d09a2SMark Phalan 360159d09a2SMark Phalan /* Get preauthentication data to send to the client as part of the "you 361159d09a2SMark Phalan * need to use preauthentication" error. The module doesn't need to 362159d09a2SMark Phalan * actually provide data if the protocol doesn't require it, but it should 363159d09a2SMark Phalan * return either zero or non-zero to control whether its padata type is 364159d09a2SMark Phalan * included in the list which is sent back to the client. Is not allowed 365159d09a2SMark Phalan * to create a context because we have no guarantee that the client will 366159d09a2SMark Phalan * ever call again (or that it will hit this server if it does), in which 367159d09a2SMark Phalan * case a context might otherwise hang around forever. */ 368159d09a2SMark Phalan typedef krb5_error_code 369159d09a2SMark Phalan (*preauth_server_edata_proc)(krb5_context, 370159d09a2SMark Phalan krb5_kdc_req *request, 371159d09a2SMark Phalan struct _krb5_db_entry_new *client, 372159d09a2SMark Phalan struct _krb5_db_entry_new *server, 373159d09a2SMark Phalan preauth_get_entry_data_proc, 374159d09a2SMark Phalan void *pa_module_context, 375159d09a2SMark Phalan krb5_pa_data *data); 376159d09a2SMark Phalan 377159d09a2SMark Phalan /* Verify preauthentication data sent by the client, setting the 378159d09a2SMark Phalan * TKT_FLG_PRE_AUTH or TKT_FLG_HW_AUTH flag in the enc_tkt_reply's "flags" 379159d09a2SMark Phalan * field as appropriate, and returning nonzero on failure. Can create 380159d09a2SMark Phalan * context data for consumption by the return_proc or freepa_proc below. */ 381159d09a2SMark Phalan typedef krb5_error_code 382159d09a2SMark Phalan (*preauth_server_verify_proc)(krb5_context context, 383159d09a2SMark Phalan struct _krb5_db_entry_new *client, 384159d09a2SMark Phalan krb5_data *req_pkt, 385159d09a2SMark Phalan krb5_kdc_req *request, 386159d09a2SMark Phalan krb5_enc_tkt_part *enc_tkt_reply, 387159d09a2SMark Phalan krb5_pa_data *data, 388159d09a2SMark Phalan preauth_get_entry_data_proc, 389159d09a2SMark Phalan void *pa_module_context, 390159d09a2SMark Phalan void **pa_request_context, 391159d09a2SMark Phalan krb5_data **e_data, 392159d09a2SMark Phalan krb5_authdata ***authz_data); 393159d09a2SMark Phalan 394159d09a2SMark Phalan /* Generate preauthentication response data to send to the client as part 395159d09a2SMark Phalan * of the AS-REP. If it needs to override the key which is used to encrypt 396159d09a2SMark Phalan * the response, it can do so. The module is expected (but not required, 397159d09a2SMark Phalan * if a preauth_server_free_reqcontext_proc is also provided) to free any 398159d09a2SMark Phalan * context data it saved in "pa_request_context". */ 399159d09a2SMark Phalan typedef krb5_error_code 400159d09a2SMark Phalan (*preauth_server_return_proc)(krb5_context context, 401159d09a2SMark Phalan krb5_pa_data * padata, 402159d09a2SMark Phalan struct _krb5_db_entry_new *client, 403159d09a2SMark Phalan krb5_data *req_pkt, 404159d09a2SMark Phalan krb5_kdc_req *request, 405159d09a2SMark Phalan krb5_kdc_rep *reply, 406159d09a2SMark Phalan struct _krb5_key_data *client_keys, 407159d09a2SMark Phalan krb5_keyblock *encrypting_key, 408159d09a2SMark Phalan krb5_pa_data **send_pa, 409159d09a2SMark Phalan preauth_get_entry_data_proc, 410159d09a2SMark Phalan void *pa_module_context, 411159d09a2SMark Phalan void **pa_request_context); 412159d09a2SMark Phalan 413159d09a2SMark Phalan /* Free up the server-side per-request context, in cases where 414159d09a2SMark Phalan * server_return_proc() didn't or for whatever reason was not called. 415159d09a2SMark Phalan * Can be NULL. */ 416159d09a2SMark Phalan typedef krb5_error_code 417159d09a2SMark Phalan (*preauth_server_free_reqcontext_proc)(krb5_context, 418159d09a2SMark Phalan void *pa_module_context, 419159d09a2SMark Phalan void **request_pa_context); 420159d09a2SMark Phalan 421159d09a2SMark Phalan /* 422159d09a2SMark Phalan * The function table / structure which a preauth server module must export as 423159d09a2SMark Phalan * "preauthentication_server_0". NOTE: replace "0" with "1" for the type and 424159d09a2SMark Phalan * variable names if this gets picked up by upstream. If the interfaces work 425159d09a2SMark Phalan * correctly, future versions of the table will add either more callbacks or 426159d09a2SMark Phalan * more arguments to callbacks, and in both cases we'll be able to wrap the v0 427159d09a2SMark Phalan * functions. 428159d09a2SMark Phalan */ 429159d09a2SMark Phalan typedef struct krb5plugin_preauth_server_ftable_v1 { 430159d09a2SMark Phalan /* Not-usually-visible name. */ 431159d09a2SMark Phalan char *name; 432159d09a2SMark Phalan 433159d09a2SMark Phalan /* Pointer to zero-terminated list of pa_types which this module can 434159d09a2SMark Phalan * provide services for. */ 435159d09a2SMark Phalan krb5_preauthtype *pa_type_list; 436159d09a2SMark Phalan 437159d09a2SMark Phalan /* Per-plugin initialization/cleanup. The init function is called by the 438159d09a2SMark Phalan * KDC when the plugin is loaded, and the fini function is called before 439159d09a2SMark Phalan * the plugin is unloaded. Both are optional. */ 440159d09a2SMark Phalan preauth_server_init_proc init_proc; 441159d09a2SMark Phalan preauth_server_fini_proc fini_proc; 442159d09a2SMark Phalan 443159d09a2SMark Phalan /* Return the flags which the KDC should use for this module. This is a 444159d09a2SMark Phalan * callback instead of a static value because the module may or may not 445159d09a2SMark Phalan * wish to count itself as a hardware preauthentication module (in other 446159d09a2SMark Phalan * words, the flags may be affected by the configuration, for example if a 447159d09a2SMark Phalan * site administrator can force a particular preauthentication type to be 448159d09a2SMark Phalan * supported using only hardware). This function is called for each entry 449159d09a2SMark Phalan * entry in the server_pa_type_list. */ 450159d09a2SMark Phalan preauth_server_flags_proc flags_proc; 451159d09a2SMark Phalan 452159d09a2SMark Phalan /* Get preauthentication data to send to the client as part of the "you 453159d09a2SMark Phalan * need to use preauthentication" error. The module doesn't need to 454159d09a2SMark Phalan * actually provide data if the protocol doesn't require it, but it should 455159d09a2SMark Phalan * return either zero or non-zero to control whether its padata type is 456159d09a2SMark Phalan * included in the list which is sent back to the client. Is not allowed 457159d09a2SMark Phalan * to create a context because we have no guarantee that the client will 458159d09a2SMark Phalan * ever call again (or that it will hit this server if it does), in which 459159d09a2SMark Phalan * case a context might otherwise hang around forever. */ 460159d09a2SMark Phalan preauth_server_edata_proc edata_proc; 461159d09a2SMark Phalan 462159d09a2SMark Phalan /* Verify preauthentication data sent by the client, setting the 463159d09a2SMark Phalan * TKT_FLG_PRE_AUTH or TKT_FLG_HW_AUTH flag in the enc_tkt_reply's "flags" 464159d09a2SMark Phalan * field as appropriate, and returning nonzero on failure. Can create 465159d09a2SMark Phalan * context data for consumption by the return_proc or freepa_proc below. */ 466159d09a2SMark Phalan preauth_server_verify_proc verify_proc; 467159d09a2SMark Phalan 468159d09a2SMark Phalan /* Generate preauthentication response data to send to the client as part 469159d09a2SMark Phalan * of the AS-REP. If it needs to override the key which is used to encrypt 470159d09a2SMark Phalan * the response, it can do so. The module is expected (but not required, 471159d09a2SMark Phalan * if a freepa_proc is also provided) to free any context data it saved in 472159d09a2SMark Phalan * "request_pa_context". */ 473159d09a2SMark Phalan preauth_server_return_proc return_proc; 474159d09a2SMark Phalan 475159d09a2SMark Phalan /* Free up the server-side per-request context, in cases where 476159d09a2SMark Phalan * server_return_proc() didn't or for whatever reason was not called. 477159d09a2SMark Phalan * Can be NULL. */ 478159d09a2SMark Phalan preauth_server_free_reqcontext_proc freepa_reqcontext_proc; 479159d09a2SMark Phalan 480159d09a2SMark Phalan } krb5plugin_preauth_server_ftable_v1; 481159d09a2SMark Phalan 482159d09a2SMark Phalan 483159d09a2SMark Phalan /* 484159d09a2SMark Phalan * This function allows a preauth plugin to obtain preauth 485159d09a2SMark Phalan * options. The preauth_data returned from this function 486159d09a2SMark Phalan * should be freed by calling krb5_get_init_creds_opt_free_pa(). 487159d09a2SMark Phalan * 488159d09a2SMark Phalan * The 'opt' pointer supplied to this function must have been 489159d09a2SMark Phalan * obtained using krb5_get_init_creds_opt_alloc() 490159d09a2SMark Phalan */ 491159d09a2SMark Phalan krb5_error_code KRB5_CALLCONV 492159d09a2SMark Phalan krb5_get_init_creds_opt_get_pa 493159d09a2SMark Phalan (krb5_context context, 494159d09a2SMark Phalan krb5_get_init_creds_opt *opt, 495159d09a2SMark Phalan int *num_preauth_data, 496159d09a2SMark Phalan krb5_gic_opt_pa_data **preauth_data); 497159d09a2SMark Phalan 498159d09a2SMark Phalan /* 499159d09a2SMark Phalan * This function frees the preauth_data that was returned by 500159d09a2SMark Phalan * krb5_get_init_creds_opt_get_pa(). 501159d09a2SMark Phalan */ 502159d09a2SMark Phalan void KRB5_CALLCONV 503159d09a2SMark Phalan krb5_get_init_creds_opt_free_pa 504159d09a2SMark Phalan (krb5_context context, 505159d09a2SMark Phalan int num_preauth_data, 506159d09a2SMark Phalan krb5_gic_opt_pa_data *preauth_data); 507159d09a2SMark Phalan 508159d09a2SMark Phalan #endif /* KRB5_PREAUTH_PLUGIN_H_INCLUDED */ 509