1 /* crypto/ui/ui.h -*- mode:C; c-file-style: "eay" -*- */ |
|
2 /* Written by Richard Levitte (richard@levitte.org) for the OpenSSL |
|
3 * project 2001. |
|
4 */ |
|
5 /* ==================================================================== |
|
6 * Copyright (c) 2001 The OpenSSL Project. All rights reserved. |
|
7 * |
|
8 * Redistribution and use in source and binary forms, with or without |
|
9 * modification, are permitted provided that the following conditions |
|
10 * are met: |
|
11 * |
|
12 * 1. Redistributions of source code must retain the above copyright |
|
13 * notice, this list of conditions and the following disclaimer. |
|
14 * |
|
15 * 2. Redistributions in binary form must reproduce the above copyright |
|
16 * notice, this list of conditions and the following disclaimer in |
|
17 * the documentation and/or other materials provided with the |
|
18 * distribution. |
|
19 * |
|
20 * 3. All advertising materials mentioning features or use of this |
|
21 * software must display the following acknowledgment: |
|
22 * "This product includes software developed by the OpenSSL Project |
|
23 * for use in the OpenSSL Toolkit. (http://www.openssl.org/)" |
|
24 * |
|
25 * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to |
|
26 * endorse or promote products derived from this software without |
|
27 * prior written permission. For written permission, please contact |
|
28 * openssl-core@openssl.org. |
|
29 * |
|
30 * 5. Products derived from this software may not be called "OpenSSL" |
|
31 * nor may "OpenSSL" appear in their names without prior written |
|
32 * permission of the OpenSSL Project. |
|
33 * |
|
34 * 6. Redistributions of any form whatsoever must retain the following |
|
35 * acknowledgment: |
|
36 * "This product includes software developed by the OpenSSL Project |
|
37 * for use in the OpenSSL Toolkit (http://www.openssl.org/)" |
|
38 * |
|
39 * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY |
|
40 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
|
41 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
|
42 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR |
|
43 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
|
44 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
|
45 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
|
46 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
|
47 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, |
|
48 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
|
49 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED |
|
50 * OF THE POSSIBILITY OF SUCH DAMAGE. |
|
51 * ==================================================================== |
|
52 * |
|
53 * This product includes cryptographic software written by Eric Young |
|
54 * (eay@cryptsoft.com). This product includes software written by Tim |
|
55 * Hudson (tjh@cryptsoft.com). |
|
56 * |
|
57 */ |
|
58 |
|
59 #ifndef HEADER_UI_H |
|
60 #define HEADER_UI_H |
|
61 |
|
62 #include <openssl/crypto.h> |
|
63 #include <openssl/safestack.h> |
|
64 |
|
65 #ifdef __cplusplus |
|
66 extern "C" { |
|
67 #endif |
|
68 |
|
69 /* The UI type is a holder for a specific user interface session. It can |
|
70 contain an illimited number of informational or error strings as well |
|
71 as things to prompt for, both passwords (noecho mode) and others (echo |
|
72 mode), and verification of the same. All of these are called strings, |
|
73 and are further described below. */ |
|
74 typedef struct ui_st UI; |
|
75 |
|
76 /* All instances of UI have a reference to a method structure, which is a |
|
77 ordered vector of functions that implement the lower level things to do. |
|
78 There is an instruction on the implementation further down, in the section |
|
79 for method implementors. */ |
|
80 typedef struct ui_method_st UI_METHOD; |
|
81 |
|
82 |
|
83 /* All the following functions return -1 or NULL on error and in some cases |
|
84 (UI_process()) -2 if interrupted or in some other way cancelled. |
|
85 When everything is fine, they return 0, a positive value or a non-NULL |
|
86 pointer, all depending on their purpose. */ |
|
87 |
|
88 /* Creators and destructor. */ |
|
89 UI *UI_new(void); |
|
90 UI *UI_new_method(const UI_METHOD *method); |
|
91 void UI_free(UI *ui); |
|
92 |
|
93 /* The following functions are used to add strings to be printed and prompt |
|
94 strings to prompt for data. The names are UI_{add,dup}_<function>_string |
|
95 and UI_{add,dup}_input_boolean. |
|
96 |
|
97 UI_{add,dup}_<function>_string have the following meanings: |
|
98 add add a text or prompt string. The pointers given to these |
|
99 functions are used verbatim, no copying is done. |
|
100 dup make a copy of the text or prompt string, then add the copy |
|
101 to the collection of strings in the user interface. |
|
102 <function> |
|
103 The function is a name for the functionality that the given |
|
104 string shall be used for. It can be one of: |
|
105 input use the string as data prompt. |
|
106 verify use the string as verification prompt. This |
|
107 is used to verify a previous input. |
|
108 info use the string for informational output. |
|
109 error use the string for error output. |
|
110 Honestly, there's currently no difference between info and error for the |
|
111 moment. |
|
112 |
|
113 UI_{add,dup}_input_boolean have the same semantics for "add" and "dup", |
|
114 and are typically used when one wants to prompt for a yes/no response. |
|
115 |
|
116 |
|
117 All of the functions in this group take a UI and a prompt string. |
|
118 The string input and verify addition functions also take a flag argument, |
|
119 a buffer for the result to end up with, a minimum input size and a maximum |
|
120 input size (the result buffer MUST be large enough to be able to contain |
|
121 the maximum number of characters). Additionally, the verify addition |
|
122 functions takes another buffer to compare the result against. |
|
123 The boolean input functions take an action description string (which should |
|
124 be safe to ignore if the expected user action is obvious, for example with |
|
125 a dialog box with an OK button and a Cancel button), a string of acceptable |
|
126 characters to mean OK and to mean Cancel. The two last strings are checked |
|
127 to make sure they don't have common characters. Additionally, the same |
|
128 flag argument as for the string input is taken, as well as a result buffer. |
|
129 The result buffer is required to be at least one byte long. Depending on |
|
130 the answer, the first character from the OK or the Cancel character strings |
|
131 will be stored in the first byte of the result buffer. No NUL will be |
|
132 added, so the result is *not* a string. |
|
133 |
|
134 On success, the all return an index of the added information. That index |
|
135 is usefull when retrieving results with UI_get0_result(). */ |
|
136 int UI_add_input_string(UI *ui, const char *prompt, int flags, |
|
137 char *result_buf, int minsize, int maxsize); |
|
138 int UI_dup_input_string(UI *ui, const char *prompt, int flags, |
|
139 char *result_buf, int minsize, int maxsize); |
|
140 int UI_add_verify_string(UI *ui, const char *prompt, int flags, |
|
141 char *result_buf, int minsize, int maxsize, const char *test_buf); |
|
142 int UI_dup_verify_string(UI *ui, const char *prompt, int flags, |
|
143 char *result_buf, int minsize, int maxsize, const char *test_buf); |
|
144 int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc, |
|
145 const char *ok_chars, const char *cancel_chars, |
|
146 int flags, char *result_buf); |
|
147 int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc, |
|
148 const char *ok_chars, const char *cancel_chars, |
|
149 int flags, char *result_buf); |
|
150 int UI_add_info_string(UI *ui, const char *text); |
|
151 int UI_dup_info_string(UI *ui, const char *text); |
|
152 int UI_add_error_string(UI *ui, const char *text); |
|
153 int UI_dup_error_string(UI *ui, const char *text); |
|
154 |
|
155 /* These are the possible flags. They can be or'ed together. */ |
|
156 /* Use to have echoing of input */ |
|
157 #define UI_INPUT_FLAG_ECHO 0x01 |
|
158 /* Use a default password. Where that password is found is completely |
|
159 up to the application, it might for example be in the user data set |
|
160 with UI_add_user_data(). It is not recommended to have more than |
|
161 one input in each UI being marked with this flag, or the application |
|
162 might get confused. */ |
|
163 #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 |
|
164 |
|
165 /* The user of these routines may want to define flags of their own. The core |
|
166 UI won't look at those, but will pass them on to the method routines. They |
|
167 must use higher bits so they don't get confused with the UI bits above. |
|
168 UI_INPUT_FLAG_USER_BASE tells which is the lowest bit to use. A good |
|
169 example of use is this: |
|
170 |
|
171 #define MY_UI_FLAG1 (0x01 << UI_INPUT_FLAG_USER_BASE) |
|
172 |
|
173 */ |
|
174 #define UI_INPUT_FLAG_USER_BASE 16 |
|
175 |
|
176 |
|
177 /* The following function helps construct a prompt. object_desc is a |
|
178 textual short description of the object, for example "pass phrase", |
|
179 and object_name is the name of the object (might be a card name or |
|
180 a file name. |
|
181 The returned string shall always be allocated on the heap with |
|
182 OPENSSL_malloc(), and need to be free'd with OPENSSL_free(). |
|
183 |
|
184 If the ui_method doesn't contain a pointer to a user-defined prompt |
|
185 constructor, a default string is built, looking like this: |
|
186 |
|
187 "Enter {object_desc} for {object_name}:" |
|
188 |
|
189 So, if object_desc has the value "pass phrase" and object_name has |
|
190 the value "foo.key", the resulting string is: |
|
191 |
|
192 "Enter pass phrase for foo.key:" |
|
193 */ |
|
194 char *UI_construct_prompt(UI *ui_method, |
|
195 const char *object_desc, const char *object_name); |
|
196 |
|
197 |
|
198 /* The following function is used to store a pointer to user-specific data. |
|
199 Any previous such pointer will be returned and replaced. |
|
200 |
|
201 For callback purposes, this function makes a lot more sense than using |
|
202 ex_data, since the latter requires that different parts of OpenSSL or |
|
203 applications share the same ex_data index. |
|
204 |
|
205 Note that the UI_OpenSSL() method completely ignores the user data. |
|
206 Other methods may not, however. */ |
|
207 void *UI_add_user_data(UI *ui, void *user_data); |
|
208 /* We need a user data retrieving function as well. */ |
|
209 void *UI_get0_user_data(UI *ui); |
|
210 |
|
211 /* Return the result associated with a prompt given with the index i. */ |
|
212 const char *UI_get0_result(UI *ui, int i); |
|
213 |
|
214 /* When all strings have been added, process the whole thing. */ |
|
215 int UI_process(UI *ui); |
|
216 |
|
217 /* Give a user interface parametrised control commands. This can be used to |
|
218 send down an integer, a data pointer or a function pointer, as well as |
|
219 be used to get information from a UI. */ |
|
220 int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)()); |
|
221 |
|
222 /* The commands */ |
|
223 /* Use UI_CONTROL_PRINT_ERRORS with the value 1 to have UI_process print the |
|
224 OpenSSL error stack before printing any info or added error messages and |
|
225 before any prompting. */ |
|
226 #define UI_CTRL_PRINT_ERRORS 1 |
|
227 /* Check if a UI_process() is possible to do again with the same instance of |
|
228 a user interface. This makes UI_ctrl() return 1 if it is redoable, and 0 |
|
229 if not. */ |
|
230 #define UI_CTRL_IS_REDOABLE 2 |
|
231 |
|
232 |
|
233 /* Some methods may use extra data */ |
|
234 #define UI_set_app_data(s,arg) UI_set_ex_data(s,0,arg) |
|
235 #define UI_get_app_data(s) UI_get_ex_data(s,0) |
|
236 int UI_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, |
|
237 CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); |
|
238 int UI_set_ex_data(UI *r,int idx,void *arg); |
|
239 void *UI_get_ex_data(UI *r, int idx); |
|
240 |
|
241 /* Use specific methods instead of the built-in one */ |
|
242 void UI_set_default_method(const UI_METHOD *meth); |
|
243 const UI_METHOD *UI_get_default_method(void); |
|
244 const UI_METHOD *UI_get_method(UI *ui); |
|
245 const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth); |
|
246 |
|
247 /* The method with all the built-in thingies */ |
|
248 UI_METHOD *UI_OpenSSL(void); |
|
249 |
|
250 |
|
251 /* ---------- For method writers ---------- */ |
|
252 /* A method contains a number of functions that implement the low level |
|
253 of the User Interface. The functions are: |
|
254 |
|
255 an opener This function starts a session, maybe by opening |
|
256 a channel to a tty, or by opening a window. |
|
257 a writer This function is called to write a given string, |
|
258 maybe to the tty, maybe as a field label in a |
|
259 window. |
|
260 a flusher This function is called to flush everything that |
|
261 has been output so far. It can be used to actually |
|
262 display a dialog box after it has been built. |
|
263 a reader This function is called to read a given prompt, |
|
264 maybe from the tty, maybe from a field in a |
|
265 window. Note that it's called wth all string |
|
266 structures, not only the prompt ones, so it must |
|
267 check such things itself. |
|
268 a closer This function closes the session, maybe by closing |
|
269 the channel to the tty, or closing the window. |
|
270 |
|
271 All these functions are expected to return: |
|
272 |
|
273 0 on error. |
|
274 1 on success. |
|
275 -1 on out-of-band events, for example if some prompting has |
|
276 been canceled (by pressing Ctrl-C, for example). This is |
|
277 only checked when returned by the flusher or the reader. |
|
278 |
|
279 The way this is used, the opener is first called, then the writer for all |
|
280 strings, then the flusher, then the reader for all strings and finally the |
|
281 closer. Note that if you want to prompt from a terminal or other command |
|
282 line interface, the best is to have the reader also write the prompts |
|
283 instead of having the writer do it. If you want to prompt from a dialog |
|
284 box, the writer can be used to build up the contents of the box, and the |
|
285 flusher to actually display the box and run the event loop until all data |
|
286 has been given, after which the reader only grabs the given data and puts |
|
287 them back into the UI strings. |
|
288 |
|
289 All method functions take a UI as argument. Additionally, the writer and |
|
290 the reader take a UI_STRING. |
|
291 */ |
|
292 |
|
293 /* The UI_STRING type is the data structure that contains all the needed info |
|
294 about a string or a prompt, including test data for a verification prompt. |
|
295 */ |
|
296 DECLARE_STACK_OF(UI_STRING) |
|
297 typedef struct ui_string_st UI_STRING; |
|
298 |
|
299 /* The different types of strings that are currently supported. |
|
300 This is only needed by method authors. */ |
|
301 enum UI_string_types |
|
302 { |
|
303 UIT_NONE=0, |
|
304 UIT_PROMPT, /* Prompt for a string */ |
|
305 UIT_VERIFY, /* Prompt for a string and verify */ |
|
306 UIT_BOOLEAN, /* Prompt for a yes/no response */ |
|
307 UIT_INFO, /* Send info to the user */ |
|
308 UIT_ERROR /* Send an error message to the user */ |
|
309 }; |
|
310 |
|
311 /* Create and manipulate methods */ |
|
312 UI_METHOD *UI_create_method(char *name); |
|
313 void UI_destroy_method(UI_METHOD *ui_method); |
|
314 int UI_method_set_opener(UI_METHOD *method, int (*opener)(UI *ui)); |
|
315 int UI_method_set_writer(UI_METHOD *method, int (*writer)(UI *ui, UI_STRING *uis)); |
|
316 int UI_method_set_flusher(UI_METHOD *method, int (*flusher)(UI *ui)); |
|
317 int UI_method_set_reader(UI_METHOD *method, int (*reader)(UI *ui, UI_STRING *uis)); |
|
318 int UI_method_set_closer(UI_METHOD *method, int (*closer)(UI *ui)); |
|
319 int (*UI_method_get_opener(UI_METHOD *method))(UI*); |
|
320 int (*UI_method_get_writer(UI_METHOD *method))(UI*,UI_STRING*); |
|
321 int (*UI_method_get_flusher(UI_METHOD *method))(UI*); |
|
322 int (*UI_method_get_reader(UI_METHOD *method))(UI*,UI_STRING*); |
|
323 int (*UI_method_get_closer(UI_METHOD *method))(UI*); |
|
324 |
|
325 /* The following functions are helpers for method writers to access relevant |
|
326 data from a UI_STRING. */ |
|
327 |
|
328 /* Return type of the UI_STRING */ |
|
329 enum UI_string_types UI_get_string_type(UI_STRING *uis); |
|
330 /* Return input flags of the UI_STRING */ |
|
331 int UI_get_input_flags(UI_STRING *uis); |
|
332 /* Return the actual string to output (the prompt, info or error) */ |
|
333 const char *UI_get0_output_string(UI_STRING *uis); |
|
334 /* Return the optional action string to output (the boolean promtp instruction) */ |
|
335 const char *UI_get0_action_string(UI_STRING *uis); |
|
336 /* Return the result of a prompt */ |
|
337 const char *UI_get0_result_string(UI_STRING *uis); |
|
338 /* Return the string to test the result against. Only useful with verifies. */ |
|
339 const char *UI_get0_test_string(UI_STRING *uis); |
|
340 /* Return the required minimum size of the result */ |
|
341 int UI_get_result_minsize(UI_STRING *uis); |
|
342 /* Return the required maximum size of the result */ |
|
343 int UI_get_result_maxsize(UI_STRING *uis); |
|
344 /* Set the result of a UI_STRING. */ |
|
345 int UI_set_result(UI *ui, UI_STRING *uis, const char *result); |
|
346 |
|
347 |
|
348 /* A couple of popular utility functions */ |
|
349 int UI_UTIL_read_pw_string(char *buf,int length,const char *prompt,int verify); |
|
350 int UI_UTIL_read_pw(char *buf,char *buff,int size,const char *prompt,int verify); |
|
351 |
|
352 |
|
353 /* BEGIN ERROR CODES */ |
|
354 /* The following lines are auto generated by the script mkerr.pl. Any changes |
|
355 * made after this point may be overwritten when the script is next run. |
|
356 */ |
|
357 void ERR_load_UI_strings(void); |
|
358 |
|
359 /* Error codes for the UI functions. */ |
|
360 |
|
361 /* Function codes. */ |
|
362 #define UI_F_GENERAL_ALLOCATE_BOOLEAN 108 |
|
363 #define UI_F_GENERAL_ALLOCATE_PROMPT 109 |
|
364 #define UI_F_GENERAL_ALLOCATE_STRING 100 |
|
365 #define UI_F_UI_CTRL 111 |
|
366 #define UI_F_UI_DUP_ERROR_STRING 101 |
|
367 #define UI_F_UI_DUP_INFO_STRING 102 |
|
368 #define UI_F_UI_DUP_INPUT_BOOLEAN 110 |
|
369 #define UI_F_UI_DUP_INPUT_STRING 103 |
|
370 #define UI_F_UI_DUP_VERIFY_STRING 106 |
|
371 #define UI_F_UI_GET0_RESULT 107 |
|
372 #define UI_F_UI_NEW_METHOD 104 |
|
373 #define UI_F_UI_SET_RESULT 105 |
|
374 |
|
375 /* Reason codes. */ |
|
376 #define UI_R_COMMON_OK_AND_CANCEL_CHARACTERS 104 |
|
377 #define UI_R_INDEX_TOO_LARGE 102 |
|
378 #define UI_R_INDEX_TOO_SMALL 103 |
|
379 #define UI_R_NO_RESULT_BUFFER 105 |
|
380 #define UI_R_RESULT_TOO_LARGE 100 |
|
381 #define UI_R_RESULT_TOO_SMALL 101 |
|
382 #define UI_R_UNKNOWN_CONTROL_COMMAND 106 |
|
383 |
|
384 #ifdef __cplusplus |
|
385 } |
|
386 #endif |
|
387 #endif |
|
388 |
|