1/* 2 * Copyright 2008 Massachusetts Institute of Technology. 3 * All Rights Reserved. 4 * 5 * Export of this software from the United States of America may 6 * require a specific license from the United States Government. 7 * It is the responsibility of any person or organization contemplating 8 * export to obtain such a license before exporting. 9 * 10 * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and 11 * distribute this software and its documentation for any purpose and 12 * without fee is hereby granted, provided that the above copyright 13 * notice appear in all copies and that both that copyright notice and 14 * this permission notice appear in supporting documentation, and that 15 * the name of M.I.T. not be used in advertising or publicity pertaining 16 * to distribution of the software without specific, written prior 17 * permission. Furthermore if you modify this software you must label 18 * your software as modified software and not distribute it in such a 19 * fashion that it might be confused with the original M.I.T. software. 20 * M.I.T. makes no representations about the suitability of 21 * this software for any purpose. It is provided "as is" without express 22 * or implied warranty. 23 */ 24 25#ifndef KIM_UI_PLUGIN_H 26#define KIM_UI_PLUGIN_H 27 28#ifdef __cplusplus 29extern "C" { 30#endif 31 32/*! 33 * The type of prompt which needs to be displayed. 34 * This value determines what type of user interface is displayed. 35 * See \ref kim_options_custom_prompt_callback for more information. 36 */ 37typedef uint32_t kim_prompt_type; 38 39enum kim_prompt_type_enum { 40 kim_prompt_type_password = 0, 41 kim_prompt_type_preauth = 1 42}; 43 44/* 45 * Plugins for Controlling Identity Selection and Credential Acquisition 46 * 47 * In order to acquire credentials, Kerberos needs to obtain one or more secrets from the user. 48 * These secrets may be a certificate, password, SecurID pin, or information from a smart card. 49 * If obtaining the secret requires interaction with the user, the Kerberos libraries call a 50 * "prompter callback" to display a dialog or command line prompt to request information from 51 * the user. If you want to provide your own custom dialogs or command line prompts, 52 * the KIM APIs provide a plugin mechanism for replacing the default prompt ui with your own. 53 * 54 * The function table / structure which a KIM ui plugin module must export 55 * as "kim_ui_0". If the interfaces work correctly, future versions of the 56 * table will add either more callbacks or more arguments to callbacks, and 57 * in both cases we'll be able to wrap the v0 functions. 58 */ 59/* extern kim_ui_plugin_ftable_v0 kim_ui_0; */ 60 61 62typedef struct kim_ui_plugin_ftable_v0 { 63 int minor_version; /* currently 0 */ 64 65 /* Called before other calls to allow the UI to initialize. 66 * Return an error if you can't display your UI in this environment. 67 * To allow your plugin to be called from multiple threads, pass back 68 * state associated with this instance of your UI in out_context. 69 * The same context pointer will be provided to all plugin calls for 70 * this ui. */ 71 kim_error (*init) (void **out_context); 72 73 /* Present UI which allows the user to enter a new identity. 74 * This is typically called when the user selects a "new tickets" 75 * control or menu item from a ticket management utility. 76 * If this UI calls into KIM to get new credentials it may 77 * call auth_prompt below. 78 * If out_change_password is set to TRUE, KIM will call change_password 79 * on the identity and then call enter_identity again, allowing you 80 * to have a change password option on your UI. */ 81 kim_error (*enter_identity) (void *in_context, 82 kim_options io_options, 83 kim_identity *out_identity, 84 kim_boolean *out_change_password); 85 86 /* Present UI to select which identity to use. 87 * This is typically called the first time an application tries to use 88 * Kerberos and is used to establish a hints preference for the application. 89 * If this UI calls into KIM to get new credentials it may 90 * call auth_prompt below. 91 * If out_change_password is set to TRUE, KIM will call change_password 92 * on the identity and then call select_identity again, allowing you 93 * to have a change password option on your UI. */ 94 kim_error (*select_identity) (void *in_context, 95 kim_selection_hints io_hints, 96 kim_identity *out_identity, 97 kim_boolean *out_change_password); 98 99 /* Present UI to display authentication to the user */ 100 /* If in_allow_save_reply is FALSE do not display UI to allow the user 101 * to save their password. In this case the value of out_save_reply will 102 * be ignored. */ 103 kim_error (*auth_prompt) (void *in_context, 104 kim_identity in_identity, 105 kim_prompt_type in_type, 106 kim_boolean in_allow_save_reply, 107 kim_boolean in_hide_reply, 108 kim_string in_title, 109 kim_string in_message, 110 kim_string in_description, 111 char **out_reply, 112 kim_boolean *out_save_reply); 113 114 /* Prompt to change the identity's password. 115 * May be combined with an auth_prompt if additional auth is required, 116 * eg: SecurID pin. 117 * If in_old_password_expired is true, this callback is in response 118 * to an expired password error. If this is the case the same context 119 * which generated the error will be used for this callback. */ 120 kim_error (*change_password) (void *in_context, 121 kim_identity in_identity, 122 kim_boolean in_old_password_expired, 123 char **out_old_password, 124 char **out_new_password, 125 char **out_verify_password); 126 127 /* Display an error to the user; may be called after any of the prompts */ 128 kim_error (*handle_error) (void *in_context, 129 kim_identity in_identity, 130 kim_error in_error, 131 kim_string in_error_message, 132 kim_string in_error_description); 133 134 /* Free strings returned by the UI. Will be called once for each string 135 * returned from a plugin callback. If you have returned a string twice 136 * just make sure your free function checks for NULL and sets the pointer 137 * to NULL when done freeing memory. */ 138 void (*free_string) (void *in_context, 139 char **io_string); 140 141 /* Called after the last prompt (even on error) to allow the UI to 142 * free allocated resources associated with its context. */ 143 kim_error (*fini) (void *io_context); 144 145} kim_ui_plugin_ftable_v0; 146 147 148#ifdef __cplusplus 149} 150#endif 151 152#endif /* KIM_UI_PLUGIN_H */ 153