Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/krb5/clpreauth_plugin.h @ 69:33d812a61356

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