include/krb5/clpreauth_plugin.h

0001 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
0002 /*
0003  * Copyright (c) 2006 Red Hat, Inc.
0004  * Portions copyright (c) 2006, 2011 Massachusetts Institute of Technology
0005  * All Rights Reserved.
0006  *
0007  * Redistribution and use in source and binary forms, with or without
0008  * modification, are permitted provided that the following conditions are met:
0009  *
0010  *  * Redistributions of source code must retain the above copyright
0011  *    notice, this list of conditions and the following disclaimer.
0012  *  * Redistributions in binary form must reproduce the above copyright
0013  *    notice, this list of conditions and the following disclaimer in
0014  *    the documentation and/or other materials provided with the
0015  *    distribution.
0016  *  * Neither the name of Red Hat, Inc., nor the names of its
0017  *    contributors may be used to endorse or promote products derived
0018  *    from this software without specific prior written permission.
0019  *
0020  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
0021  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
0022  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
0023  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
0024  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
0025  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
0026  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
0027  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
0028  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
0029  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
0030  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
0031  */
0032
0033 /*
0034  * Declarations for clpreauth plugin module implementors.
0035  *
0036  * The clpreauth interface has a single supported major version, which is
0037  * 1.  Major version 1 has a current minor version of 2.  clpreauth modules
0038  * should define a function named clpreauth_<modulename>_initvt, matching
0039  * the signature:
0040  *
0041  *   krb5_error_code
0042  *   clpreauth_modname_initvt(krb5_context context, int maj_ver,
0043  *                            int min_ver, krb5_plugin_vtable vtable);
0044  * The initvt function should:
0045  *
0046  * - Check that the supplied maj_ver number is supported by the module, or
0047  *   return KRB5_PLUGIN_VER_NOTSUPP if it is not.
0048  *
0049  * - Cast the vtable pointer as appropriate for the interface and maj_ver:
0050  *     maj_ver == 1: Cast to krb5_clpreauth_vtable
0051  *
0052  * - Initialize the methods of the vtable, stopping as appropriate for the
0053  *   supplied min_ver.  Optional methods may be left uninitialized.
0054  *
0055  * Memory for the vtable is allocated by the caller, not by the module.
0056  */
0057
0058 #ifndef KRB5_CLPREAUTH_PLUGIN_H
0059 #define KRB5_CLPREAUTH_PLUGIN_H
0060
0061 #include <krb5/krb5.h>
0062 #include <krb5/plugin.h>
0063
0064 /* clpreauth mechanism property flags */
0065
0066 /* Provides a real answer which we can send back to the KDC.  The client
0067  * assumes that one real answer will be enough. */
0068 #define PA_REAL         0x00000001
0069
0070 /* Doesn't provide a real answer, but must be given a chance to run before any
0071  * REAL mechanism callbacks. */
0072 #define PA_INFO         0x00000002
0073
0074 /* Abstract type for a client request information handle. */
0075 typedef struct krb5_clpreauth_rock_st *krb5_clpreauth_rock;
0076
0077 /* Abstract types for module data and per-request module data. */
0078 typedef struct krb5_clpreauth_moddata_st *krb5_clpreauth_moddata;
0079 typedef struct krb5_clpreauth_modreq_st *krb5_clpreauth_modreq;
0080
0081 /* Before using a callback after version 1, modules must check the vers
0082  * field of the callback structure. */
0083 typedef struct krb5_clpreauth_callbacks_st {
0084     int vers;
0085
0086     /*
0087      * If an AS-REP has been received, return the enctype of the AS-REP
0088      * encrypted part.  Otherwise return the enctype chosen from etype-info, or
0089      * the first requested enctype if no etype-info was received.
0090      */
0091     krb5_enctype (*get_etype)(krb5_context context, krb5_clpreauth_rock rock);
0092
0093     /* Get a pointer to the FAST armor key, or NULL if the client is not using
0094      * FAST.  The returned pointer is an alias and should not be freed. */
0095     krb5_keyblock *(*fast_armor)(krb5_context context,
0096                                  krb5_clpreauth_rock rock);
0097
0098     /*
0099      * Get a pointer to the client-supplied reply key, possibly invoking the
0100      * prompter to ask for a password if this has not already been done.  The
0101      * returned pointer is an alias and should not be freed.
0102      */
0103     krb5_error_code (*get_as_key)(krb5_context context,
0104                                   krb5_clpreauth_rock rock,
0105                                   krb5_keyblock **keyblock);
0106
0107     /* Replace the reply key to be used to decrypt the AS response. */
0108     krb5_error_code (*set_as_key)(krb5_context context,
0109                                   krb5_clpreauth_rock rock,
0110                                   const krb5_keyblock *keyblock);
0111
0112     /* End of version 1 clpreauth callbacks. */
0113
0114     /*
0115      * Get the current time for use in a preauth response.  If
0116      * allow_unauth_time is true and the library has been configured to allow
0117      * it, the current time will be offset using unauthenticated timestamp
0118      * information received from the KDC in the preauth-required error, if one
0119      * has been received.  Otherwise, the timestamp in a preauth-required error
0120      * will only be used if it is protected by a FAST channel.  Only set
0121      * allow_unauth_time if using an unauthenticated time offset would not
0122      * create a security issue.
0123      */
0124     krb5_error_code (*get_preauth_time)(krb5_context context,
0125                                         krb5_clpreauth_rock rock,
0126                                         krb5_boolean allow_unauth_time,
0127                                         krb5_timestamp *time_out,
0128                                         krb5_int32 *usec_out);
0129
0130     /* Set a question to be answered by the responder and optionally provide
0131      * a challenge. */
0132     krb5_error_code (*ask_responder_question)(krb5_context context,
0133                                               krb5_clpreauth_rock rock,
0134                                               const char *question,
0135                                               const char *challenge);
0136
0137     /* Get an answer from the responder, or NULL if the question was
0138      * unanswered. */
0139     const char *(*get_responder_answer)(krb5_context context,
0140                                         krb5_clpreauth_rock rock,
0141                                         const char *question);
0142
0143     /* Indicate interest in the AS key through the responder interface. */
0144     void (*need_as_key)(krb5_context context, krb5_clpreauth_rock rock);
0145
0146     /*
0147      * Get a configuration/state item from an input ccache, which may allow it
0148      * to retrace the steps it took last time.  The returned data string is an
0149      * alias and should not be freed.
0150      */
0151     const char *(*get_cc_config)(krb5_context context,
0152                                  krb5_clpreauth_rock rock, const char *key);
0153
0154     /*
0155      * Set a configuration/state item which will be recorded to an output
0156      * ccache, if the calling application supplied one.  Both key and data
0157      * should be valid UTF-8 text.
0158      */
0159     krb5_error_code (*set_cc_config)(krb5_context context,
0160                                      krb5_clpreauth_rock rock,
0161                                      const char *key, const char *data);
0162
0163     /* End of version 2 clpreauth callbacks (added in 1.11). */
0164
0165     /*
0166      * Prevent further fallbacks to other preauth mechanisms if the KDC replies
0167      * with an error.  (The module itself can still respond to errors with its
0168      * tryagain method, or continue after KDC_ERR_MORE_PREAUTH_DATA_REQUIRED
0169      * errors with its process method.)  A module should invoke this callback
0170      * from the process method when it generates an authenticated request using
0171      * credentials; often this will be the first or only client message
0172      * generated by the mechanism.
0173      */
0174     void (*disable_fallback)(krb5_context context, krb5_clpreauth_rock rock);
0175
0176     /* End of version 3 clpreauth callbacks (added in 1.17). */
0177 } *krb5_clpreauth_callbacks;
0178
0179 /*
0180  * Optional: per-plugin initialization/cleanup.  The init function is called by
0181  * libkrb5 when the plugin is loaded, and the fini function is called before
0182  * the plugin is unloaded.  These may be called multiple times in case the
0183  * plugin is used in multiple contexts.  The returned context lives the
0184  * lifetime of the krb5_context.
0185  */
0186 typedef krb5_error_code
0187 (*krb5_clpreauth_init_fn)(krb5_context context,
0188                           krb5_clpreauth_moddata *moddata_out);
0189 typedef void
0190 (*krb5_clpreauth_fini_fn)(krb5_context context,
0191                           krb5_clpreauth_moddata moddata);
0192
0193 /*
0194  * Optional (mandatory before MIT krb5 1.12): pa_type will be a member of the
0195  * vtable's pa_type_list.  Return PA_REAL if pa_type is a real
0196  * preauthentication type or PA_INFO if it is an informational type.  If this
0197  * function is not defined in 1.12 or later, all pa_type values advertised by
0198  * the module will be assumed to be real.
0199  */
0200 typedef int
0201 (*krb5_clpreauth_get_flags_fn)(krb5_context context, krb5_preauthtype pa_type);
0202
0203 /*
0204  * Optional: per-request initialization/cleanup.  The request_init function is
0205  * called when beginning to process a get_init_creds request and the
0206  * request_fini function is called when processing of the request is complete.
0207  * This is optional.  It may be called multiple times in the lifetime of a
0208  * krb5_context.
0209  */
0210 typedef void
0211 (*krb5_clpreauth_request_init_fn)(krb5_context context,
0212                                   krb5_clpreauth_moddata moddata,
0213                                   krb5_clpreauth_modreq *modreq_out);
0214 typedef void
0215 (*krb5_clpreauth_request_fini_fn)(krb5_context context,
0216                                   krb5_clpreauth_moddata moddata,
0217                                   krb5_clpreauth_modreq modreq);
0218
0219 /*
0220  * Optional: process server-supplied data in pa_data and set responder
0221  * questions.
0222  *
0223  * encoded_previous_request may be NULL if there has been no previous request
0224  * in the AS exchange.
0225  */
0226 typedef krb5_error_code
0227 (*krb5_clpreauth_prep_questions_fn)(krb5_context context,
0228                                     krb5_clpreauth_moddata moddata,
0229                                     krb5_clpreauth_modreq modreq,
0230                                     krb5_get_init_creds_opt *opt,
0231                                     krb5_clpreauth_callbacks cb,
0232                                     krb5_clpreauth_rock rock,
0233                                     krb5_kdc_req *request,
0234                                     krb5_data *encoded_request_body,
0235                                     krb5_data *encoded_previous_request,
0236                                     krb5_pa_data *pa_data);
0237
0238 /*
0239  * Mandatory: process server-supplied data in pa_data and return created data
0240  * in pa_data_out.  Also called after the AS-REP is received if the AS-REP
0241  * includes preauthentication data of the associated type.
0242  *
0243  * as_key contains the client-supplied key if known, or an empty keyblock if
0244  * not.  If it is empty, the module may use gak_fct to fill it in.
0245  *
0246  * encoded_previous_request may be NULL if there has been no previous request
0247  * in the AS exchange.
0248  */
0249 typedef krb5_error_code
0250 (*krb5_clpreauth_process_fn)(krb5_context context,
0251                              krb5_clpreauth_moddata moddata,
0252                              krb5_clpreauth_modreq modreq,
0253                              krb5_get_init_creds_opt *opt,
0254                              krb5_clpreauth_callbacks cb,
0255                              krb5_clpreauth_rock rock,
0256                              krb5_kdc_req *request,
0257                              krb5_data *encoded_request_body,
0258                              krb5_data *encoded_previous_request,
0259                              krb5_pa_data *pa_data,
0260                              krb5_prompter_fct prompter, void *prompter_data,
0261                              krb5_pa_data ***pa_data_out);
0262
0263 /*
0264  * Optional: Attempt to use error and error_padata to try to recover from the
0265  * given error.  To work with both FAST and non-FAST errors, an implementation
0266  * should generally consult error_padata rather than decoding error->e_data.
0267  * For non-FAST errors, it contains the e_data decoded as either pa-data or
0268  * typed-data.
0269  *
0270  * If this function is provided, and it returns 0 and stores data in
0271  * pa_data_out, then the client library will retransmit the request.
0272  */
0273 typedef krb5_error_code
0274 (*krb5_clpreauth_tryagain_fn)(krb5_context context,
0275                               krb5_clpreauth_moddata moddata,
0276                               krb5_clpreauth_modreq modreq,
0277                               krb5_get_init_creds_opt *opt,
0278                               krb5_clpreauth_callbacks cb,
0279                               krb5_clpreauth_rock rock,
0280                               krb5_kdc_req *request,
0281                               krb5_data *encoded_request_body,
0282                               krb5_data *encoded_previous_request,
0283                               krb5_preauthtype pa_type,
0284                               krb5_error *error,
0285                               krb5_pa_data **error_padata,
0286                               krb5_prompter_fct prompter, void *prompter_data,
0287                               krb5_pa_data ***pa_data_out);
0288
0289 /*
0290  * Optional: receive krb5_get_init_creds_opt information.  The attr and value
0291  * information supplied should be copied into moddata by the module if it
0292  * wishes to reference it after returning from this call.
0293  */
0294 typedef krb5_error_code
0295 (*krb5_clpreauth_supply_gic_opts_fn)(krb5_context context,
0296                                      krb5_clpreauth_moddata moddata,
0297                                      krb5_get_init_creds_opt *opt,
0298                                      const char *attr, const char *value);
0299
0300 typedef struct krb5_clpreauth_vtable_st {
0301     /* Mandatory: name of module. */
0302     const char *name;
0303
0304     /* Mandatory: pointer to zero-terminated list of pa_types which this module
0305      * can provide services for. */
0306     krb5_preauthtype *pa_type_list;
0307
0308     /* Optional: pointer to zero-terminated list of enc_types which this module
0309      * claims to add support for. */
0310     krb5_enctype *enctype_list;
0311
0312     krb5_clpreauth_init_fn init;
0313     krb5_clpreauth_fini_fn fini;
0314     krb5_clpreauth_get_flags_fn flags;
0315     krb5_clpreauth_request_init_fn request_init;
0316     krb5_clpreauth_request_fini_fn request_fini;
0317     krb5_clpreauth_process_fn process;
0318     krb5_clpreauth_tryagain_fn tryagain;
0319     krb5_clpreauth_supply_gic_opts_fn gic_opts;
0320     /* Minor version 1 ends here. */
0321
0322     krb5_clpreauth_prep_questions_fn prep_questions;
0323     /* Minor version 2 ends here. */
0324 } *krb5_clpreauth_vtable;
0325
0326 /*
0327  * This function allows a clpreauth plugin to obtain preauth options.  The
0328  * preauth_data returned from this function should be freed by calling
0329  * krb5_get_init_creds_opt_free_pa().
0330  */
0331 krb5_error_code KRB5_CALLCONV
0332 krb5_get_init_creds_opt_get_pa(krb5_context context,
0333                                krb5_get_init_creds_opt *opt,
0334                                int *num_preauth_data,
0335                                krb5_gic_opt_pa_data **preauth_data);
0336
0337 /*
0338  * This function frees the preauth_data that was returned by
0339  * krb5_get_init_creds_opt_get_pa().
0340  */
0341 void KRB5_CALLCONV
0342 krb5_get_init_creds_opt_free_pa(krb5_context context,
0343                                 int num_preauth_data,
0344                                 krb5_gic_opt_pa_data *preauth_data);
0345
0346 #endif /* KRB5_CLPREAUTH_PLUGIN_H */