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