2N/A/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */ 2N/A * Copyright (c) 2006 Red Hat, Inc. 2N/A * Portions copyright (c) 2006 Massachusetts Institute of Technology 2N/A * All Rights Reserved. 2N/A * Redistribution and use in source and binary forms, with or without 2N/A * modification, are permitted provided that the following conditions are met: 2N/A * * Redistributions of source code must retain the above copyright 2N/A * notice, this list of conditions and the following disclaimer. 2N/A * * Redistributions in binary form must reproduce the above copyright 2N/A * notice, this list of conditions and the following disclaimer in 2N/A * the documentation and/or other materials provided with the 2N/A * * Neither the name of Red Hat, Inc., nor the names of its 2N/A * contributors may be used to endorse or promote products derived 2N/A * from this software without specific prior written permission. 2N/A * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 2N/A * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 2N/A * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 2N/A * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 2N/A * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 2N/A * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 2N/A * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 2N/A * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 2N/A * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 2N/A * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 2N/A * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 2N/A * Preauthentication plugin definitions for Kerberos 5. 2N/A * While arguments of these types are passed-in, for the most part a preauth 2N/A * module can treat them as opaque. If we need keying data, we can ask for 2N/A * Preauth mechanism property flags, unified from previous definitions in the 2N/A * KDC and libkrb5 sources. 2N/A/* Provides a real answer which we can send back to the KDC (client-only). The 2N/A * client assumes that one real answer will be enough. */ 2N/A/* Doesn't provide a real answer, but must be given a chance to run before any 2N/A * REAL mechanism callbacks (client-only). */ 2N/A/* Causes the KDC to include this mechanism in a list of supported preauth 2N/A * types if the user's DB entry flags the user as requiring hardware-based 2N/A * preauthentication (server-only). */ 2N/A/* Causes the KDC to include this mechanism in a list of supported preauth 2N/A * types if the user's DB entry flags the user as requiring preauthentication, 2N/A * and to fail preauthentication if we can't verify the client data. The 2N/A * flipside of PA_SUFFICIENT (server-only). */ 2N/A/* Causes the KDC to include this mechanism in a list of supported preauth 2N/A * types if the user's DB entry flags the user as requiring preauthentication, 2N/A * and to mark preauthentication as successful if we can verify the client 2N/A * data. The flipside of PA_REQUIRED (server-only). */ 2N/A/* Marks this preauthentication mechanism as one which changes the key which is 2N/A * used for encrypting the response to the client. Modules which have this 2N/A * flag have their server_return_proc called before modules which do not, and 2N/A * are passed over if a previously-called module has modified the encrypting 2N/A * key (server-only). */ 2N/A/* Causes the KDC to check with this preauthentication module even if the 2N/A * client has no entry in the realm database. If the module returns a success 2N/A * code, continue processing and assume that its return_padata callback will 2N/A * supply us with a key for encrypting the AS reply (server-only). */ 2N/A/* #define PA_VIRTUAL (0x00000040 | PA_REPLACES_KEY) */ 2N/A/* Not really a padata type, so don't include it in any list of preauth types 2N/A * which gets sent over the wire. */ 2N/A/*************************************************************************** 2N/A * Client-side preauthentication plugin interface definition. 2N/A ***************************************************************************/ 2N/A * A callback which will obtain the user's long-term AS key by prompting the 2N/A * user for the password, then salting it properly, and so on. For the moment, 2N/A * it's identical to the get_as_key callback used inside of libkrb5, but we 2N/A * define a new typedef here instead of making the existing one public to 2N/A * isolate ourselves from potential future changes. 2N/A * A client module's callback functions are allowed to request various 2N/A * information to enable it to process a request. 2N/A /* The returned krb5_data item holds the enctype expected to be used to encrypt the 2N/A * encrypted portion of the AS_REP packet. When handling a 2N/A * PREAUTH_REQUIRED error, this typically comes from etype-info2. 2N/A * When handling an AS reply, it is initialized from the AS reply itself.*/ 2N/A /* Free the data returned from krb5plugin_preauth_client_req_get_etype */ 2N/A /* The returned krb5_data contains the FAST armor key in a 2N/A * krb5_keyblock. Returns success with a NULL data item in the 2N/A * krb5_data if the client library supports FAST but is not using it.*/ 2N/A /* Frees return from KRB5PLUGIN_PREAUTH_CLIENT_FAST_ARMOR. It is 2N/A * acceptable to set data to NULL and free the keyblock using 2N/A * krb5_free_keyblock; in that case, this frees the krb5_data 2N/A * by libkrb5 when the plugin is loaded, and the fini function is 2N/A * called before the plugin is unloaded. Both are optional and 2N/A * may be called multiple times in case the plugin is used in 2N/A * multiple contexts. The returned context lives the lifetime of 2N/A * the krb5_context */ 2N/A/* A callback which returns flags indicating if the module is a "real" or 2N/A * an "info" mechanism, and so on. This function is called for each entry 2N/A * in the client_pa_type_list. */ 2N/A * called when beginning to process a get_init_creds request and the 2N/A * request_fini function is called when processing of the request is 2N/A * complete. This is optional. It may be called multiple times in 2N/A * the lifetime of a krb5_context. */ 2N/A/* Client function which processes server-supplied data in pa_data, 2N/A * returns created data in out_pa_data, storing any of its own state in 2N/A * client_context if data for the associated preauthentication type is 2N/A * needed. It is also called after the AS-REP is received if the AS-REP 2N/A * includes preauthentication data of the associated type. 2N/A * NOTE! the encoded_previous_request will be NULL the first time this 2N/A * function is called, because it is expected to only ever contain the data 2N/A * obtained from a previous call to this function. */ 2N/A/* Client function which can attempt to use e-data in the error response to 2N/A * try to recover from the given error. If this function is not NULL, and 2N/A * it stores data in out_pa_data which is different data from the contents 2N/A * of in_pa_data, then the client library will retransmit the request. */ 2N/A * Client function which receives krb5_get_init_creds_opt information. 2N/A * The attr and value information supplied should be copied locally by 2N/A * the module if it wishes to reference it after returning from this call. 2N/A * The function table / structure which a preauth client module must export as 2N/A * "preauthentication_client_0". If the interfaces work correctly, future 2N/A * versions of the table will add either more callbacks or more arguments to 2N/A * callbacks, and in both cases we'll be able to wrap the v0 functions. 2N/A /* Not-usually-visible name. */ 2N/A /* Pointer to zero-terminated list of pa_types which this module can 2N/A * provide services for. */ 2N/A /* Pointer to zero-terminated list of enc_types which this module claims 2N/A * to add support for. */ 2N/A * by libkrb5 when the plugin is loaded, and the fini function is 2N/A * called before the plugin is unloaded. Both are optional and 2N/A * may be called multiple times in case the plugin is used in 2N/A * multiple contexts. The returned context lives the lifetime of 2N/A * the krb5_context */ 2N/A /* A callback which returns flags indicating if the module is a "real" or 2N/A * an "info" mechanism, and so on. This function is called for each entry 2N/A * in the client_pa_type_list. */ 2N/A * called when beginning to process a get_init_creds request and the 2N/A * request_fini function is called when processing of the request is 2N/A * complete. This is optional. It may be called multiple times in 2N/A * the lifetime of a krb5_context. */ 2N/A /* Client function which processes server-supplied data in pa_data, 2N/A * returns created data in out_pa_data, storing any of its own state in 2N/A * client_context if data for the associated preauthentication type is 2N/A * needed. It is also called after the AS-REP is received if the AS-REP 2N/A * includes preauthentication data of the associated type. 2N/A * NOTE! the encoded_previous_request will be NULL the first time this 2N/A * function is called, because it is expected to only ever contain the data 2N/A * obtained from a previous call to this function. */ 2N/A /* Client function which can attempt to use e-data in the error response to 2N/A * try to recover from the given error. If this function is not NULL, and 2N/A * it stores data in out_pa_data which is different data from the contents 2N/A * of in_pa_data, then the client library will retransmit the request. */ 2N/A * Client function which receives krb5_get_init_creds_opt information. 2N/A * The attr and value information supplied should be copied locally by 2N/A * the module if it wishes to reference it after returning from this call. 2N/A/*************************************************************************** 2N/A * Server-side preauthentication plugin interface definition. 2N/A ***************************************************************************/ 2N/A * A server module's callback functions are allowed to request specific types 2N/A * of information about the given client or server record or request, even 2N/A * though the database records themselves are opaque to the module. 2N/A /* The returned krb5_data item holds a DER-encoded X.509 certificate. */ 2N/A /* The returned krb5_data_item holds a krb5_deltat. */ 2N/A /* The returned krb5_data_item holds an array of krb5_keyblock structures, 2N/A * terminated by an entry with key type = 0. 2N/A * Each keyblock should have its contents freed in turn, and then the data 2N/A * item itself should be freed. */ 2N/A /* The returned krb5_data_item holds the request structure, re-encoded 2N/A * using DER. Unless the client implementation is the same as the server 2N/A * implementation, there's a good chance that the result will not match 2N/A * what the client sent, so don't go creating any fatal errors if it 2N/A * doesn't match up. */ 2N/A /* The returned krb5_data contains a krb5_keyblock with the FAST 2N/A armor key. The data member is NULL if this method is not part 2N/A /* Frees a fast armor key; it is acceptable to set data to NULL 2N/A and free the keyblock using krb5_free_keyblock; in that case, 2N/A this function simply frees the data*/ 2N/A/* Preauth plugin initialization function */ 2N/A/* Preauth plugin cleanup function */ 2N/A/* Return the flags which the KDC should use for this module. This is a 2N/A * callback instead of a static value because the module may or may not 2N/A * wish to count itself as a hardware preauthentication module (in other 2N/A * words, the flags may be affected by the configuration, for example if a 2N/A * site administrator can force a particular preauthentication type to be 2N/A * supported using only hardware). This function is called for each entry 2N/A * entry in the server_pa_type_list. */ 2N/A/* Get preauthentication data to send to the client as part of the "you 2N/A * need to use preauthentication" error. The module doesn't need to 2N/A * actually provide data if the protocol doesn't require it, but it should 2N/A * return either zero or non-zero to control whether its padata type is 2N/A * included in the list which is sent back to the client. Is not allowed 2N/A * to create a context because we have no guarantee that the client will 2N/A * ever call again (or that it will hit this server if it does), in which 2N/A * case a context might otherwise hang around forever. */ 2N/A/* Verify preauthentication data sent by the client, setting the 2N/A * TKT_FLG_PRE_AUTH or TKT_FLG_HW_AUTH flag in the enc_tkt_reply's "flags" 2N/A * field as appropriate, and returning nonzero on failure. Can create 2N/A * context data for consumption by the return_proc or freepa_proc below. */ 2N/A/* Generate preauthentication response data to send to the client as part 2N/A * of the AS-REP. If it needs to override the key which is used to encrypt 2N/A * the response, it can do so. The module is expected (but not required, 2N/A * if a preauth_server_free_reqcontext_proc is also provided) to free any 2N/A * context data it saved in "pa_request_context". */ 2N/A/* Free up the server-side per-request context, in cases where 2N/A * server_return_proc() didn't or for whatever reason was not called. 2N/A * The function table / structure which a preauth server module must export as 2N/A * "preauthentication_server_0". NOTE: replace "0" with "1" for the type and 2N/A * variable names if this gets picked up by upstream. If the interfaces work 2N/A * correctly, future versions of the table will add either more callbacks or 2N/A * more arguments to callbacks, and in both cases we'll be able to wrap the v0 2N/A /* Not-usually-visible name. */ 2N/A /* Pointer to zero-terminated list of pa_types which this module can 2N/A * provide services for. */ 2N/A * KDC when the plugin is loaded, and the fini function is called before 2N/A * the plugin is unloaded. Both are optional. */ 2N/A /* Return the flags which the KDC should use for this module. This is a 2N/A * callback instead of a static value because the module may or may not 2N/A * wish to count itself as a hardware preauthentication module (in other 2N/A * words, the flags may be affected by the configuration, for example if a 2N/A * site administrator can force a particular preauthentication type to be 2N/A * supported using only hardware). This function is called for each entry 2N/A * entry in the server_pa_type_list. */ 2N/A /* Get preauthentication data to send to the client as part of the "you 2N/A * need to use preauthentication" error. The module doesn't need to 2N/A * actually provide data if the protocol doesn't require it, but it should 2N/A * return either zero or non-zero to control whether its padata type is 2N/A * included in the list which is sent back to the client. Is not allowed 2N/A * to create a context because we have no guarantee that the client will 2N/A * ever call again (or that it will hit this server if it does), in which 2N/A * case a context might otherwise hang around forever. */ 2N/A /* Verify preauthentication data sent by the client, setting the 2N/A * TKT_FLG_PRE_AUTH or TKT_FLG_HW_AUTH flag in the enc_tkt_reply's "flags" 2N/A * field as appropriate, and returning nonzero on failure. Can create 2N/A * context data for consumption by the return_proc or freepa_proc below. */ 2N/A /* Generate preauthentication response data to send to the client as part 2N/A * of the AS-REP. If it needs to override the key which is used to encrypt 2N/A * the response, it can do so. The module is expected (but not required, 2N/A * if a freepa_proc is also provided) to free any context data it saved in 2N/A * "request_pa_context". */ 2N/A /* Free up the server-side per-request context, in cases where 2N/A * server_return_proc() didn't or for whatever reason was not called. 2N/A * This function allows a preauth plugin to obtain preauth 2N/A * options. The preauth_data returned from this function 2N/A * should be freed by calling krb5_get_init_creds_opt_free_pa(). 2N/A * The 'opt' pointer supplied to this function must have been 2N/A * obtained using krb5_get_init_creds_opt_alloc() 2N/A * This function frees the preauth_data that was returned by 2N/A * krb5_get_init_creds_opt_get_pa(). 2N/A#
endif /* KRB5_PREAUTH_PLUGIN_H_INCLUDED */