OpenCoverage

ui.h

Absolute File Name:/home/opencoverage/opencoverage/guest-scripts/openssl/src/include/openssl/ui.h
Source codeSwitch to Preprocessed file
LineSourceCount
1/*-
2 * Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.-
3 *-
4 * Licensed under the OpenSSL license (the "License"). You may not use-
5 * this file except in compliance with the License. You can obtain a copy-
6 * in the file LICENSE in the source distribution or at-
7 * https://www.openssl.org/source/license.html-
8 */-
9-
10#ifndef HEADER_UI_H-
11# define HEADER_UI_H-
12-
13# include <openssl/opensslconf.h>-
14-
15# if OPENSSL_API_COMPAT < 0x10100000L-
16# include <openssl/crypto.h>-
17# endif-
18# include <openssl/safestack.h>-
19# include <openssl/pem.h>-
20# include <openssl/ossl_typ.h>-
21# include <openssl/uierr.h>-
22-
23/* For compatibility reasons, the macro OPENSSL_NO_UI is currently retained */-
24# if OPENSSL_API_COMPAT < 0x10200000L-
25# ifdef OPENSSL_NO_UI_CONSOLE-
26# define OPENSSL_NO_UI-
27# endif-
28# endif-
29-
30# ifdef __cplusplus-
31extern "C" {-
32# endif-
33-
34/*-
35 * All the following functions return -1 or NULL on error and in some cases-
36 * (UI_process()) -2 if interrupted or in some other way cancelled. When-
37 * everything is fine, they return 0, a positive value or a non-NULL pointer,-
38 * all depending on their purpose.-
39 */-
40-
41/* Creators and destructor. */-
42UI *UI_new(void);-
43UI *UI_new_method(const UI_METHOD *method);-
44void UI_free(UI *ui);-
45-
46/*--
47 The following functions are used to add strings to be printed and prompt-
48 strings to prompt for data. The names are UI_{add,dup}_<function>_string-
49 and UI_{add,dup}_input_boolean.-
50-
51 UI_{add,dup}_<function>_string have the following meanings:-
52 add add a text or prompt string. The pointers given to these-
53 functions are used verbatim, no copying is done.-
54 dup make a copy of the text or prompt string, then add the copy-
55 to the collection of strings in the user interface.-
56 <function>-
57 The function is a name for the functionality that the given-
58 string shall be used for. It can be one of:-
59 input use the string as data prompt.-
60 verify use the string as verification prompt. This-
61 is used to verify a previous input.-
62 info use the string for informational output.-
63 error use the string for error output.-
64 Honestly, there's currently no difference between info and error for the-
65 moment.-
66-
67 UI_{add,dup}_input_boolean have the same semantics for "add" and "dup",-
68 and are typically used when one wants to prompt for a yes/no response.-
69-
70 All of the functions in this group take a UI and a prompt string.-
71 The string input and verify addition functions also take a flag argument,-
72 a buffer for the result to end up with, a minimum input size and a maximum-
73 input size (the result buffer MUST be large enough to be able to contain-
74 the maximum number of characters). Additionally, the verify addition-
75 functions takes another buffer to compare the result against.-
76 The boolean input functions take an action description string (which should-
77 be safe to ignore if the expected user action is obvious, for example with-
78 a dialog box with an OK button and a Cancel button), a string of acceptable-
79 characters to mean OK and to mean Cancel. The two last strings are checked-
80 to make sure they don't have common characters. Additionally, the same-
81 flag argument as for the string input is taken, as well as a result buffer.-
82 The result buffer is required to be at least one byte long. Depending on-
83 the answer, the first character from the OK or the Cancel character strings-
84 will be stored in the first byte of the result buffer. No NUL will be-
85 added, so the result is *not* a string.-
86-
87 On success, the all return an index of the added information. That index-
88 is useful when retrieving results with UI_get0_result(). */-
89int UI_add_input_string(UI *ui, const char *prompt, int flags,-
90 char *result_buf, int minsize, int maxsize);-
91int UI_dup_input_string(UI *ui, const char *prompt, int flags,-
92 char *result_buf, int minsize, int maxsize);-
93int UI_add_verify_string(UI *ui, const char *prompt, int flags,-
94 char *result_buf, int minsize, int maxsize,-
95 const char *test_buf);-
96int UI_dup_verify_string(UI *ui, const char *prompt, int flags,-
97 char *result_buf, int minsize, int maxsize,-
98 const char *test_buf);-
99int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc,-
100 const char *ok_chars, const char *cancel_chars,-
101 int flags, char *result_buf);-
102int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc,-
103 const char *ok_chars, const char *cancel_chars,-
104 int flags, char *result_buf);-
105int UI_add_info_string(UI *ui, const char *text);-
106int UI_dup_info_string(UI *ui, const char *text);-
107int UI_add_error_string(UI *ui, const char *text);-
108int UI_dup_error_string(UI *ui, const char *text);-
109-
110/* These are the possible flags. They can be or'ed together. */-
111/* Use to have echoing of input */-
112# define UI_INPUT_FLAG_ECHO 0x01-
113/*-
114 * Use a default password. Where that password is found is completely up to-
115 * the application, it might for example be in the user data set with-
116 * UI_add_user_data(). It is not recommended to have more than one input in-
117 * each UI being marked with this flag, or the application might get-
118 * confused.-
119 */-
120# define UI_INPUT_FLAG_DEFAULT_PWD 0x02-
121-
122/*--
123 * The user of these routines may want to define flags of their own. The core-
124 * UI won't look at those, but will pass them on to the method routines. They-
125 * must use higher bits so they don't get confused with the UI bits above.-
126 * UI_INPUT_FLAG_USER_BASE tells which is the lowest bit to use. A good-
127 * example of use is this:-
128 *-
129 * #define MY_UI_FLAG1 (0x01 << UI_INPUT_FLAG_USER_BASE)-
130 *-
131*/-
132# define UI_INPUT_FLAG_USER_BASE 16-
133-
134/*--
135 * The following function helps construct a prompt. object_desc is a-
136 * textual short description of the object, for example "pass phrase",-
137 * and object_name is the name of the object (might be a card name or-
138 * a file name.-
139 * The returned string shall always be allocated on the heap with-
140 * OPENSSL_malloc(), and need to be free'd with OPENSSL_free().-
141 *-
142 * If the ui_method doesn't contain a pointer to a user-defined prompt-
143 * constructor, a default string is built, looking like this:-
144 *-
145 * "Enter {object_desc} for {object_name}:"-
146 *-
147 * So, if object_desc has the value "pass phrase" and object_name has-
148 * the value "foo.key", the resulting string is:-
149 *-
150 * "Enter pass phrase for foo.key:"-
151*/-
152char *UI_construct_prompt(UI *ui_method,-
153 const char *object_desc, const char *object_name);-
154-
155/*-
156 * The following function is used to store a pointer to user-specific data.-
157 * Any previous such pointer will be returned and replaced.-
158 *-
159 * For callback purposes, this function makes a lot more sense than using-
160 * ex_data, since the latter requires that different parts of OpenSSL or-
161 * applications share the same ex_data index.-
162 *-
163 * Note that the UI_OpenSSL() method completely ignores the user data. Other-
164 * methods may not, however.-
165 */-
166void *UI_add_user_data(UI *ui, void *user_data);-
167/*-
168 * Alternatively, this function is used to duplicate the user data.-
169 * This uses the duplicator method function. The destroy function will-
170 * be used to free the user data in this case.-
171 */-
172int UI_dup_user_data(UI *ui, void *user_data);-
173/* We need a user data retrieving function as well. */-
174void *UI_get0_user_data(UI *ui);-
175-
176/* Return the result associated with a prompt given with the index i. */-
177const char *UI_get0_result(UI *ui, int i);-
178int UI_get_result_length(UI *ui, int i);-
179-
180/* When all strings have been added, process the whole thing. */-
181int UI_process(UI *ui);-
182-
183/*-
184 * Give a user interface parameterised control commands. This can be used to-
185 * send down an integer, a data pointer or a function pointer, as well as be-
186 * used to get information from a UI.-
187 */-
188int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f) (void));-
189-
190/* The commands */-
191/*-
192 * Use UI_CONTROL_PRINT_ERRORS with the value 1 to have UI_process print the-
193 * OpenSSL error stack before printing any info or added error messages and-
194 * before any prompting.-
195 */-
196# define UI_CTRL_PRINT_ERRORS 1-
197/*-
198 * Check if a UI_process() is possible to do again with the same instance of-
199 * a user interface. This makes UI_ctrl() return 1 if it is redoable, and 0-
200 * if not.-
201 */-
202# define UI_CTRL_IS_REDOABLE 2-
203-
204/* Some methods may use extra data */-
205# define UI_set_app_data(s,arg) UI_set_ex_data(s,0,arg)-
206# define UI_get_app_data(s) UI_get_ex_data(s,0)-
207-
208# define UI_get_ex_new_index(l, p, newf, dupf, freef) \-
209 CRYPTO_get_ex_new_index(CRYPTO_EX_INDEX_UI, l, p, newf, dupf, freef)-
210int UI_set_ex_data(UI *r, int idx, void *arg);-
211void *UI_get_ex_data(UI *r, int idx);-
212-
213/* Use specific methods instead of the built-in one */-
214void UI_set_default_method(const UI_METHOD *meth);-
215const UI_METHOD *UI_get_default_method(void);-
216const UI_METHOD *UI_get_method(UI *ui);-
217const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth);-
218-
219# ifndef OPENSSL_NO_UI_CONSOLE-
220-
221/* The method with all the built-in thingies */-
222UI_METHOD *UI_OpenSSL(void);-
223-
224# endif-
225-
226/*-
227 * NULL method. Literally does nothing, but may serve as a placeholder-
228 * to avoid internal default.-
229 */-
230const UI_METHOD *UI_null(void);-
231-
232/* ---------- For method writers ---------- */-
233/*--
234 A method contains a number of functions that implement the low level-
235 of the User Interface. The functions are:-
236-
237 an opener This function starts a session, maybe by opening-
238 a channel to a tty, or by opening a window.-
239 a writer This function is called to write a given string,-
240 maybe to the tty, maybe as a field label in a-
241 window.-
242 a flusher This function is called to flush everything that-
243 has been output so far. It can be used to actually-
244 display a dialog box after it has been built.-
245 a reader This function is called to read a given prompt,-
246 maybe from the tty, maybe from a field in a-
247 window. Note that it's called with all string-
248 structures, not only the prompt ones, so it must-
249 check such things itself.-
250 a closer This function closes the session, maybe by closing-
251 the channel to the tty, or closing the window.-
252-
253 All these functions are expected to return:-
254-
255 0 on error.-
256 1 on success.-
257 -1 on out-of-band events, for example if some prompting has-
258 been canceled (by pressing Ctrl-C, for example). This is-
259 only checked when returned by the flusher or the reader.-
260-
261 The way this is used, the opener is first called, then the writer for all-
262 strings, then the flusher, then the reader for all strings and finally the-
263 closer. Note that if you want to prompt from a terminal or other command-
264 line interface, the best is to have the reader also write the prompts-
265 instead of having the writer do it. If you want to prompt from a dialog-
266 box, the writer can be used to build up the contents of the box, and the-
267 flusher to actually display the box and run the event loop until all data-
268 has been given, after which the reader only grabs the given data and puts-
269 them back into the UI strings.-
270-
271 All method functions take a UI as argument. Additionally, the writer and-
272 the reader take a UI_STRING.-
273*/-
274-
275/*-
276 * The UI_STRING type is the data structure that contains all the needed info-
277 * about a string or a prompt, including test data for a verification prompt.-
278 */-
279typedef struct ui_string_st UI_STRING;-
280DEFINE_STACK_OF(UI_STRING)
never executed: end of block
never executed: end of block
executed 5 times by 1 test: end of block
Executed by:
  • libcrypto.so.1.1
never executed: end of block
executed 20 times by 1 test: return OPENSSL_sk_num((const OPENSSL_STACK *)sk);
Executed by:
  • libcrypto.so.1.1
executed 10 times by 1 test: return (UI_STRING *)OPENSSL_sk_value((const OPENSSL_STACK *)sk, idx);
Executed by:
  • libcrypto.so.1.1
never executed: return (struct stack_st_UI_STRING *)OPENSSL_sk_new((OPENSSL_sk_compfunc)compare);
executed 5 times by 1 test: return (struct stack_st_UI_STRING *)OPENSSL_sk_new_null();
Executed by:
  • libcrypto.so.1.1
never executed: return (struct stack_st_UI_STRING *)OPENSSL_sk_new_reserve((OPENSSL_sk_compfunc)compare, n);
never executed: return OPENSSL_sk_reserve((OPENSSL_STACK *)sk, n);
never executed: return (UI_STRING *)OPENSSL_sk_delete((OPENSSL_STACK *)sk, i);
never executed: return (UI_STRING *)OPENSSL_sk_delete_ptr((OPENSSL_STACK *)sk, (const void *)ptr);
executed 5 times by 1 test: return OPENSSL_sk_push((OPENSSL_STACK *)sk, (const void *)ptr);
Executed by:
  • libcrypto.so.1.1
never executed: return OPENSSL_sk_unshift((OPENSSL_STACK *)sk, (const void *)ptr);
never executed: return (UI_STRING *)OPENSSL_sk_pop((OPENSSL_STACK *)sk);
never executed: return (UI_STRING *)OPENSSL_sk_shift((OPENSSL_STACK *)sk);
never executed: return OPENSSL_sk_insert((OPENSSL_STACK *)sk, (const void *)ptr, idx);
never executed: return (UI_STRING *)OPENSSL_sk_set((OPENSSL_STACK *)sk, idx, (const void *)ptr);
never executed: return OPENSSL_sk_find((OPENSSL_STACK *)sk, (const void *)ptr);
never executed: return OPENSSL_sk_find_ex((OPENSSL_STACK *)sk, (const void *)ptr);
never executed: return OPENSSL_sk_is_sorted((const OPENSSL_STACK *)sk);
never executed: return (struct stack_st_UI_STRING *)OPENSSL_sk_dup((const OPENSSL_STACK *)sk);
never executed: return (struct stack_st_UI_STRING *)OPENSSL_sk_deep_copy((const OPENSSL_STACK *)sk, (OPENSSL_sk_copyfunc)copyfunc, (OPENSSL_sk_freefunc)freefunc);
never executed: return (sk_UI_STRING_compfunc)OPENSSL_sk_set_cmp_func((OPENSSL_STACK *)sk, (OPENSSL_sk_compfunc)compare);
0-20
281-
282/*-
283 * The different types of strings that are currently supported. This is only-
284 * needed by method authors.-
285 */-
286enum UI_string_types {-
287 UIT_NONE = 0,-
288 UIT_PROMPT, /* Prompt for a string */-
289 UIT_VERIFY, /* Prompt for a string and verify */-
290 UIT_BOOLEAN, /* Prompt for a yes/no response */-
291 UIT_INFO, /* Send info to the user */-
292 UIT_ERROR /* Send an error message to the user */-
293};-
294-
295/* Create and manipulate methods */-
296UI_METHOD *UI_create_method(const char *name);-
297void UI_destroy_method(UI_METHOD *ui_method);-
298int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui));-
299int UI_method_set_writer(UI_METHOD *method,-
300 int (*writer) (UI *ui, UI_STRING *uis));-
301int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui));-
302int UI_method_set_reader(UI_METHOD *method,-
303 int (*reader) (UI *ui, UI_STRING *uis));-
304int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui));-
305int UI_method_set_data_duplicator(UI_METHOD *method,-
306 void *(*duplicator) (UI *ui, void *ui_data),-
307 void (*destructor)(UI *ui, void *ui_data));-
308int UI_method_set_prompt_constructor(UI_METHOD *method,-
309 char *(*prompt_constructor) (UI *ui,-
310 const char-
311 *object_desc,-
312 const char-
313 *object_name));-
314int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data);-
315int (*UI_method_get_opener(const UI_METHOD *method)) (UI *);-
316int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *);-
317int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *);-
318int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *);-
319int (*UI_method_get_closer(const UI_METHOD *method)) (UI *);-
320char *(*UI_method_get_prompt_constructor(const UI_METHOD *method))-
321 (UI *, const char *, const char *);-
322void *(*UI_method_get_data_duplicator(const UI_METHOD *method)) (UI *, void *);-
323void (*UI_method_get_data_destructor(const UI_METHOD *method)) (UI *, void *);-
324const void *UI_method_get_ex_data(const UI_METHOD *method, int idx);-
325-
326/*-
327 * The following functions are helpers for method writers to access relevant-
328 * data from a UI_STRING.-
329 */-
330-
331/* Return type of the UI_STRING */-
332enum UI_string_types UI_get_string_type(UI_STRING *uis);-
333/* Return input flags of the UI_STRING */-
334int UI_get_input_flags(UI_STRING *uis);-
335/* Return the actual string to output (the prompt, info or error) */-
336const char *UI_get0_output_string(UI_STRING *uis);-
337/*-
338 * Return the optional action string to output (the boolean prompt-
339 * instruction)-
340 */-
341const char *UI_get0_action_string(UI_STRING *uis);-
342/* Return the result of a prompt */-
343const char *UI_get0_result_string(UI_STRING *uis);-
344int UI_get_result_string_length(UI_STRING *uis);-
345/*-
346 * Return the string to test the result against. Only useful with verifies.-
347 */-
348const char *UI_get0_test_string(UI_STRING *uis);-
349/* Return the required minimum size of the result */-
350int UI_get_result_minsize(UI_STRING *uis);-
351/* Return the required maximum size of the result */-
352int UI_get_result_maxsize(UI_STRING *uis);-
353/* Set the result of a UI_STRING. */-
354int UI_set_result(UI *ui, UI_STRING *uis, const char *result);-
355int UI_set_result_ex(UI *ui, UI_STRING *uis, const char *result, int len);-
356-
357/* A couple of popular utility functions */-
358int UI_UTIL_read_pw_string(char *buf, int length, const char *prompt,-
359 int verify);-
360int UI_UTIL_read_pw(char *buf, char *buff, int size, const char *prompt,-
361 int verify);-
362UI_METHOD *UI_UTIL_wrap_read_pem_callback(pem_password_cb *cb, int rwflag);-
363-
364-
365# ifdef __cplusplus-
366}-
367# endif-
368#endif-
Source codeSwitch to Preprocessed file
Generated by Squish Coco 4.2.2