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