1 ui.h |
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 © Portions copyright (c) 2006 Nokia Corporation. All rights reserved. |
|
60 */ |
|
61 |
|
62 #ifndef HEADER_UI_H |
|
63 #define HEADER_UI_H |
|
64 |
|
65 #if (defined(__SYMBIAN32__) && !defined(SYMBIAN)) |
|
66 #define SYMBIAN |
|
67 #endif |
|
68 |
|
69 #ifdef SYMBIAN |
|
70 #include <e32def.h> |
|
71 #endif |
|
72 #ifndef OPENSSL_NO_DEPRECATED |
|
73 #include <openssl/crypto.h> |
|
74 #endif |
|
75 #include <openssl/safestack.h> |
|
76 #include <openssl/ossl_typ.h> |
|
77 |
|
78 #ifdef __cplusplus |
|
79 extern "C" { |
|
80 #endif |
|
81 |
|
82 /* Declared already in ossl_typ.h */ |
|
83 /* typedef struct ui_st UI; */ |
|
84 /* typedef struct ui_method_st UI_METHOD; */ |
|
85 |
|
86 |
|
87 /* All the following functions return -1 or NULL on error and in some cases |
|
88 (UI_process()) -2 if interrupted or in some other way cancelled. |
|
89 When everything is fine, they return 0, a positive value or a non-NULL |
|
90 pointer, all depending on their purpose. */ |
|
91 |
|
92 /* Creators and destructor. */ |
|
93 IMPORT_C UI *UI_new(void); |
|
94 IMPORT_C UI *UI_new_method(const UI_METHOD *method); |
|
95 IMPORT_C void UI_free(UI *ui); |
|
96 |
|
97 /* The following functions are used to add strings to be printed and prompt |
|
98 strings to prompt for data. The names are UI_{add,dup}_<function>_string |
|
99 and UI_{add,dup}_input_boolean. |
|
100 |
|
101 UI_{add,dup}_<function>_string have the following meanings: |
|
102 add add a text or prompt string. The pointers given to these |
|
103 functions are used verbatim, no copying is done. |
|
104 dup make a copy of the text or prompt string, then add the copy |
|
105 to the collection of strings in the user interface. |
|
106 <function> |
|
107 The function is a name for the functionality that the given |
|
108 string shall be used for. It can be one of: |
|
109 input use the string as data prompt. |
|
110 verify use the string as verification prompt. This |
|
111 is used to verify a previous input. |
|
112 info use the string for informational output. |
|
113 error use the string for error output. |
|
114 Honestly, there's currently no difference between info and error for the |
|
115 moment. |
|
116 |
|
117 UI_{add,dup}_input_boolean have the same semantics for "add" and "dup", |
|
118 and are typically used when one wants to prompt for a yes/no response. |
|
119 |
|
120 |
|
121 All of the functions in this group take a UI and a prompt string. |
|
122 The string input and verify addition functions also take a flag argument, |
|
123 a buffer for the result to end up with, a minimum input size and a maximum |
|
124 input size (the result buffer MUST be large enough to be able to contain |
|
125 the maximum number of characters). Additionally, the verify addition |
|
126 functions takes another buffer to compare the result against. |
|
127 The boolean input functions take an action description string (which should |
|
128 be safe to ignore if the expected user action is obvious, for example with |
|
129 a dialog box with an OK button and a Cancel button), a string of acceptable |
|
130 characters to mean OK and to mean Cancel. The two last strings are checked |
|
131 to make sure they don't have common characters. Additionally, the same |
|
132 flag argument as for the string input is taken, as well as a result buffer. |
|
133 The result buffer is required to be at least one byte long. Depending on |
|
134 the answer, the first character from the OK or the Cancel character strings |
|
135 will be stored in the first byte of the result buffer. No NUL will be |
|
136 added, so the result is *not* a string. |
|
137 |
|
138 On success, the all return an index of the added information. That index |
|
139 is usefull when retrieving results with UI_get0_result(). */ |
|
140 IMPORT_C int UI_add_input_string(UI *ui, const char *prompt, int flags, |
|
141 char *result_buf, int minsize, int maxsize); |
|
142 IMPORT_C int UI_dup_input_string(UI *ui, const char *prompt, int flags, |
|
143 char *result_buf, int minsize, int maxsize); |
|
144 IMPORT_C int UI_add_verify_string(UI *ui, const char *prompt, int flags, |
|
145 char *result_buf, int minsize, int maxsize, const char *test_buf); |
|
146 IMPORT_C int UI_dup_verify_string(UI *ui, const char *prompt, int flags, |
|
147 char *result_buf, int minsize, int maxsize, const char *test_buf); |
|
148 IMPORT_C int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc, |
|
149 const char *ok_chars, const char *cancel_chars, |
|
150 int flags, char *result_buf); |
|
151 IMPORT_C int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc, |
|
152 const char *ok_chars, const char *cancel_chars, |
|
153 int flags, char *result_buf); |
|
154 IMPORT_C int UI_add_info_string(UI *ui, const char *text); |
|
155 IMPORT_C int UI_dup_info_string(UI *ui, const char *text); |
|
156 IMPORT_C int UI_add_error_string(UI *ui, const char *text); |
|
157 IMPORT_C int UI_dup_error_string(UI *ui, const char *text); |
|
158 |
|
159 /* These are the possible flags. They can be or'ed together. */ |
|
160 /* Use to have echoing of input */ |
|
161 #define UI_INPUT_FLAG_ECHO 0x01 |
|
162 /* Use a default password. Where that password is found is completely |
|
163 up to the application, it might for example be in the user data set |
|
164 with UI_add_user_data(). It is not recommended to have more than |
|
165 one input in each UI being marked with this flag, or the application |
|
166 might get confused. */ |
|
167 #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 |
|
168 |
|
169 /* The user of these routines may want to define flags of their own. The core |
|
170 UI won't look at those, but will pass them on to the method routines. They |
|
171 must use higher bits so they don't get confused with the UI bits above. |
|
172 UI_INPUT_FLAG_USER_BASE tells which is the lowest bit to use. A good |
|
173 example of use is this: |
|
174 |
|
175 #define MY_UI_FLAG1 (0x01 << UI_INPUT_FLAG_USER_BASE) |
|
176 |
|
177 */ |
|
178 #define UI_INPUT_FLAG_USER_BASE 16 |
|
179 |
|
180 |
|
181 /* The following function helps construct a prompt. object_desc is a |
|
182 textual short description of the object, for example "pass phrase", |
|
183 and object_name is the name of the object (might be a card name or |
|
184 a file name. |
|
185 The returned string shall always be allocated on the heap with |
|
186 OPENSSL_malloc(), and need to be free'd with OPENSSL_free(). |
|
187 |
|
188 If the ui_method doesn't contain a pointer to a user-defined prompt |
|
189 constructor, a default string is built, looking like this: |
|
190 |
|
191 "Enter {object_desc} for {object_name}:" |
|
192 |
|
193 So, if object_desc has the value "pass phrase" and object_name has |
|
194 the value "foo.key", the resulting string is: |
|
195 |
|
196 "Enter pass phrase for foo.key:" |
|
197 */ |
|
198 IMPORT_C char *UI_construct_prompt(UI *ui_method, |
|
199 const char *object_desc, const char *object_name); |
|
200 |
|
201 |
|
202 /* The following function is used to store a pointer to user-specific data. |
|
203 Any previous such pointer will be returned and replaced. |
|
204 |
|
205 For callback purposes, this function makes a lot more sense than using |
|
206 ex_data, since the latter requires that different parts of OpenSSL or |
|
207 applications share the same ex_data index. |
|
208 |
|
209 Note that the UI_OpenSSL() method completely ignores the user data. |
|
210 Other methods may not, however. */ |
|
211 IMPORT_C void *UI_add_user_data(UI *ui, void *user_data); |
|
212 /* We need a user data retrieving function as well. */ |
|
213 IMPORT_C void *UI_get0_user_data(UI *ui); |
|
214 |
|
215 /* Return the result associated with a prompt given with the index i. */ |
|
216 IMPORT_C const char *UI_get0_result(UI *ui, int i); |
|
217 |
|
218 /* When all strings have been added, process the whole thing. */ |
|
219 IMPORT_C int UI_process(UI *ui); |
|
220 |
|
221 /* Give a user interface parametrised control commands. This can be used to |
|
222 send down an integer, a data pointer or a function pointer, as well as |
|
223 be used to get information from a UI. */ |
|
224 IMPORT_C int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)(void)); |
|
225 |
|
226 /* The commands */ |
|
227 /* Use UI_CONTROL_PRINT_ERRORS with the value 1 to have UI_process print the |
|
228 OpenSSL error stack before printing any info or added error messages and |
|
229 before any prompting. */ |
|
230 #define UI_CTRL_PRINT_ERRORS 1 |
|
231 /* Check if a UI_process() is possible to do again with the same instance of |
|
232 a user interface. This makes UI_ctrl() return 1 if it is redoable, and 0 |
|
233 if not. */ |
|
234 #define UI_CTRL_IS_REDOABLE 2 |
|
235 |
|
236 |
|
237 /* Some methods may use extra data */ |
|
238 #define UI_set_app_data(s,arg) UI_set_ex_data(s,0,arg) |
|
239 #define UI_get_app_data(s) UI_get_ex_data(s,0) |
|
240 IMPORT_C int UI_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, |
|
241 CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); |
|
242 IMPORT_C int UI_set_ex_data(UI *r,int idx,void *arg); |
|
243 IMPORT_C void *UI_get_ex_data(UI *r, int idx); |
|
244 |
|
245 /* Use specific methods instead of the built-in one */ |
|
246 IMPORT_C void UI_set_default_method(const UI_METHOD *meth); |
|
247 IMPORT_C const UI_METHOD *UI_get_default_method(void); |
|
248 IMPORT_C const UI_METHOD *UI_get_method(UI *ui); |
|
249 IMPORT_C const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth); |
|
250 |
|
251 /* The method with all the built-in thingies */ |
|
252 IMPORT_C UI_METHOD *UI_OpenSSL(void); |
|
253 |
|
254 |
|
255 /* ---------- For method writers ---------- */ |
|
256 /* A method contains a number of functions that implement the low level |
|
257 of the User Interface. The functions are: |
|
258 |
|
259 an opener This function starts a session, maybe by opening |
|
260 a channel to a tty, or by opening a window. |
|
261 a writer This function is called to write a given string, |
|
262 maybe to the tty, maybe as a field label in a |
|
263 window. |
|
264 a flusher This function is called to flush everything that |
|
265 has been output so far. It can be used to actually |
|
266 display a dialog box after it has been built. |
|
267 a reader This function is called to read a given prompt, |
|
268 maybe from the tty, maybe from a field in a |
|
269 window. Note that it's called wth all string |
|
270 structures, not only the prompt ones, so it must |
|
271 check such things itself. |
|
272 a closer This function closes the session, maybe by closing |
|
273 the channel to the tty, or closing the window. |
|
274 |
|
275 All these functions are expected to return: |
|
276 |
|
277 0 on error. |
|
278 1 on success. |
|
279 -1 on out-of-band events, for example if some prompting has |
|
280 been canceled (by pressing Ctrl-C, for example). This is |
|
281 only checked when returned by the flusher or the reader. |
|
282 |
|
283 The way this is used, the opener is first called, then the writer for all |
|
284 strings, then the flusher, then the reader for all strings and finally the |
|
285 closer. Note that if you want to prompt from a terminal or other command |
|
286 line interface, the best is to have the reader also write the prompts |
|
287 instead of having the writer do it. If you want to prompt from a dialog |
|
288 box, the writer can be used to build up the contents of the box, and the |
|
289 flusher to actually display the box and run the event loop until all data |
|
290 has been given, after which the reader only grabs the given data and puts |
|
291 them back into the UI strings. |
|
292 |
|
293 All method functions take a UI as argument. Additionally, the writer and |
|
294 the reader take a UI_STRING. |
|
295 */ |
|
296 |
|
297 /* The UI_STRING type is the data structure that contains all the needed info |
|
298 about a string or a prompt, including test data for a verification prompt. |
|
299 */ |
|
300 DECLARE_STACK_OF(UI_STRING) |
|
301 typedef struct ui_string_st UI_STRING; |
|
302 |
|
303 /* The different types of strings that are currently supported. |
|
304 This is only needed by method authors. */ |
|
305 enum UI_string_types |
|
306 { |
|
307 UIT_NONE=0, |
|
308 UIT_PROMPT, /* Prompt for a string */ |
|
309 UIT_VERIFY, /* Prompt for a string and verify */ |
|
310 UIT_BOOLEAN, /* Prompt for a yes/no response */ |
|
311 UIT_INFO, /* Send info to the user */ |
|
312 UIT_ERROR /* Send an error message to the user */ |
|
313 }; |
|
314 |
|
315 /* Create and manipulate methods */ |
|
316 IMPORT_C UI_METHOD *UI_create_method(char *name); |
|
317 IMPORT_C void UI_destroy_method(UI_METHOD *ui_method); |
|
318 IMPORT_C int UI_method_set_opener(UI_METHOD *method, int (*opener)(UI *ui)); |
|
319 IMPORT_C int UI_method_set_writer(UI_METHOD *method, int (*writer)(UI *ui, UI_STRING *uis)); |
|
320 IMPORT_C int UI_method_set_flusher(UI_METHOD *method, int (*flusher)(UI *ui)); |
|
321 IMPORT_C int UI_method_set_reader(UI_METHOD *method, int (*reader)(UI *ui, UI_STRING *uis)); |
|
322 IMPORT_C int UI_method_set_closer(UI_METHOD *method, int (*closer)(UI *ui)); |
|
323 IMPORT_C int (*UI_method_get_opener(UI_METHOD *method))(UI*); |
|
324 IMPORT_C int (*UI_method_get_writer(UI_METHOD *method))(UI*,UI_STRING*); |
|
325 IMPORT_C int (*UI_method_get_flusher(UI_METHOD *method))(UI*); |
|
326 IMPORT_C int (*UI_method_get_reader(UI_METHOD *method))(UI*,UI_STRING*); |
|
327 IMPORT_C int (*UI_method_get_closer(UI_METHOD *method))(UI*); |
|
328 |
|
329 /* The following functions are helpers for method writers to access relevant |
|
330 data from a UI_STRING. */ |
|
331 |
|
332 /* Return type of the UI_STRING */ |
|
333 IMPORT_C enum UI_string_types UI_get_string_type(UI_STRING *uis); |
|
334 /* Return input flags of the UI_STRING */ |
|
335 IMPORT_C int UI_get_input_flags(UI_STRING *uis); |
|
336 /* Return the actual string to output (the prompt, info or error) */ |
|
337 IMPORT_C const char *UI_get0_output_string(UI_STRING *uis); |
|
338 /* Return the optional action string to output (the boolean promtp instruction) */ |
|
339 IMPORT_C const char *UI_get0_action_string(UI_STRING *uis); |
|
340 /* Return the result of a prompt */ |
|
341 IMPORT_C const char *UI_get0_result_string(UI_STRING *uis); |
|
342 /* Return the string to test the result against. Only useful with verifies. */ |
|
343 IMPORT_C const char *UI_get0_test_string(UI_STRING *uis); |
|
344 /* Return the required minimum size of the result */ |
|
345 IMPORT_C int UI_get_result_minsize(UI_STRING *uis); |
|
346 /* Return the required maximum size of the result */ |
|
347 IMPORT_C int UI_get_result_maxsize(UI_STRING *uis); |
|
348 /* Set the result of a UI_STRING. */ |
|
349 IMPORT_C int UI_set_result(UI *ui, UI_STRING *uis, const char *result); |
|
350 |
|
351 |
|
352 /* A couple of popular utility functions */ |
|
353 IMPORT_C int UI_UTIL_read_pw_string(char *buf,int length,const char *prompt,int verify); |
|
354 IMPORT_C int UI_UTIL_read_pw(char *buf,char *buff,int size,const char *prompt,int verify); |
|
355 |
|
356 |
|
357 /* BEGIN ERROR CODES */ |
|
358 /* The following lines are auto generated by the script mkerr.pl. Any changes |
|
359 * made after this point may be overwritten when the script is next run. |
|
360 */ |
|
361 IMPORT_C void ERR_load_UI_strings(void); |
|
362 |
|
363 /* Error codes for the UI functions. */ |
|
364 |
|
365 /* Function codes. */ |
|
366 #define UI_F_GENERAL_ALLOCATE_BOOLEAN 108 |
|
367 #define UI_F_GENERAL_ALLOCATE_PROMPT 109 |
|
368 #define UI_F_GENERAL_ALLOCATE_STRING 100 |
|
369 #define UI_F_UI_CTRL 111 |
|
370 #define UI_F_UI_DUP_ERROR_STRING 101 |
|
371 #define UI_F_UI_DUP_INFO_STRING 102 |
|
372 #define UI_F_UI_DUP_INPUT_BOOLEAN 110 |
|
373 #define UI_F_UI_DUP_INPUT_STRING 103 |
|
374 #define UI_F_UI_DUP_VERIFY_STRING 106 |
|
375 #define UI_F_UI_GET0_RESULT 107 |
|
376 #define UI_F_UI_NEW_METHOD 104 |
|
377 #define UI_F_UI_SET_RESULT 105 |
|
378 |
|
379 /* Reason codes. */ |
|
380 #define UI_R_COMMON_OK_AND_CANCEL_CHARACTERS 104 |
|
381 #define UI_R_INDEX_TOO_LARGE 102 |
|
382 #define UI_R_INDEX_TOO_SMALL 103 |
|
383 #define UI_R_NO_RESULT_BUFFER 105 |
|
384 #define UI_R_RESULT_TOO_LARGE 100 |
|
385 #define UI_R_RESULT_TOO_SMALL 101 |
|
386 #define UI_R_UNKNOWN_CONTROL_COMMAND 106 |
|
387 |
|
388 #ifdef __cplusplus |
|
389 } |
|
390 #endif |
|
391 #endif |