diff options
author | cvs2svn <admin@example.com> | 2007-03-01 16:29:10 +0000 |
---|---|---|
committer | cvs2svn <admin@example.com> | 2007-03-01 16:29:10 +0000 |
commit | d92cde8050488a0c87c357c4756a89026b6659ee (patch) | |
tree | 737670254ff24eff6f6dddb0b97cae8c0ba8c571 /src/lib/libcrypto/ui/ui.h | |
parent | 9c4b4ca341957016adebec4e1eb2446cf0261241 (diff) | |
download | openbsd-OPENBSD_4_1_BASE.tar.gz openbsd-OPENBSD_4_1_BASE.tar.bz2 openbsd-OPENBSD_4_1_BASE.zip |
This commit was manufactured by cvs2git to create tag 'OPENBSD_4_1_BASE'.OPENBSD_4_1_BASE
Diffstat (limited to 'src/lib/libcrypto/ui/ui.h')
-rw-r--r-- | src/lib/libcrypto/ui/ui.h | 387 |
1 files changed, 0 insertions, 387 deletions
diff --git a/src/lib/libcrypto/ui/ui.h b/src/lib/libcrypto/ui/ui.h deleted file mode 100644 index 735a2d988e..0000000000 --- a/src/lib/libcrypto/ui/ui.h +++ /dev/null | |||
@@ -1,387 +0,0 @@ | |||
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 | ||