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