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