1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string, 6*2175Sjp161948UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean, 7*2175Sjp161948UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string, 8*2175Sjp161948UI_add_error_string, UI_dup_error_string, UI_construct_prompt, 9*2175Sjp161948UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process, 10*2175Sjp161948UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method, 11*2175Sjp161948UI_set_method, UI_OpenSSL, ERR_load_UI_strings - New User Interface 12*2175Sjp161948 13*2175Sjp161948=head1 SYNOPSIS 14*2175Sjp161948 15*2175Sjp161948 #include <openssl/ui.h> 16*2175Sjp161948 17*2175Sjp161948 typedef struct ui_st UI; 18*2175Sjp161948 typedef struct ui_method_st UI_METHOD; 19*2175Sjp161948 20*2175Sjp161948 UI *UI_new(void); 21*2175Sjp161948 UI *UI_new_method(const UI_METHOD *method); 22*2175Sjp161948 void UI_free(UI *ui); 23*2175Sjp161948 24*2175Sjp161948 int UI_add_input_string(UI *ui, const char *prompt, int flags, 25*2175Sjp161948 char *result_buf, int minsize, int maxsize); 26*2175Sjp161948 int UI_dup_input_string(UI *ui, const char *prompt, int flags, 27*2175Sjp161948 char *result_buf, int minsize, int maxsize); 28*2175Sjp161948 int UI_add_verify_string(UI *ui, const char *prompt, int flags, 29*2175Sjp161948 char *result_buf, int minsize, int maxsize, const char *test_buf); 30*2175Sjp161948 int UI_dup_verify_string(UI *ui, const char *prompt, int flags, 31*2175Sjp161948 char *result_buf, int minsize, int maxsize, const char *test_buf); 32*2175Sjp161948 int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc, 33*2175Sjp161948 const char *ok_chars, const char *cancel_chars, 34*2175Sjp161948 int flags, char *result_buf); 35*2175Sjp161948 int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc, 36*2175Sjp161948 const char *ok_chars, const char *cancel_chars, 37*2175Sjp161948 int flags, char *result_buf); 38*2175Sjp161948 int UI_add_info_string(UI *ui, const char *text); 39*2175Sjp161948 int UI_dup_info_string(UI *ui, const char *text); 40*2175Sjp161948 int UI_add_error_string(UI *ui, const char *text); 41*2175Sjp161948 int UI_dup_error_string(UI *ui, const char *text); 42*2175Sjp161948 43*2175Sjp161948 /* These are the possible flags. They can be or'ed together. */ 44*2175Sjp161948 #define UI_INPUT_FLAG_ECHO 0x01 45*2175Sjp161948 #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 46*2175Sjp161948 47*2175Sjp161948 char *UI_construct_prompt(UI *ui_method, 48*2175Sjp161948 const char *object_desc, const char *object_name); 49*2175Sjp161948 50*2175Sjp161948 void *UI_add_user_data(UI *ui, void *user_data); 51*2175Sjp161948 void *UI_get0_user_data(UI *ui); 52*2175Sjp161948 53*2175Sjp161948 const char *UI_get0_result(UI *ui, int i); 54*2175Sjp161948 55*2175Sjp161948 int UI_process(UI *ui); 56*2175Sjp161948 57*2175Sjp161948 int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)()); 58*2175Sjp161948 #define UI_CTRL_PRINT_ERRORS 1 59*2175Sjp161948 #define UI_CTRL_IS_REDOABLE 2 60*2175Sjp161948 61*2175Sjp161948 void UI_set_default_method(const UI_METHOD *meth); 62*2175Sjp161948 const UI_METHOD *UI_get_default_method(void); 63*2175Sjp161948 const UI_METHOD *UI_get_method(UI *ui); 64*2175Sjp161948 const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth); 65*2175Sjp161948 66*2175Sjp161948 UI_METHOD *UI_OpenSSL(void); 67*2175Sjp161948 68*2175Sjp161948=head1 DESCRIPTION 69*2175Sjp161948 70*2175Sjp161948UI stands for User Interface, and is general purpose set of routines to 71*2175Sjp161948prompt the user for text-based information. Through user-written methods 72*2175Sjp161948(see L<ui_create(3)|ui_create(3)>), prompting can be done in any way 73*2175Sjp161948imaginable, be it plain text prompting, through dialog boxes or from a 74*2175Sjp161948cell phone. 75*2175Sjp161948 76*2175Sjp161948All the functions work through a context of the type UI. This context 77*2175Sjp161948contains all the information needed to prompt correctly as well as a 78*2175Sjp161948reference to a UI_METHOD, which is an ordered vector of functions that 79*2175Sjp161948carry out the actual prompting. 80*2175Sjp161948 81*2175Sjp161948The first thing to do is to create a UI with UI_new() or UI_new_method(), 82*2175Sjp161948then add information to it with the UI_add or UI_dup functions. Also, 83*2175Sjp161948user-defined random data can be passed down to the underlying method 84*2175Sjp161948through calls to UI_add_user_data. The default UI method doesn't care 85*2175Sjp161948about these data, but other methods might. Finally, use UI_process() 86*2175Sjp161948to actually perform the prompting and UI_get0_result() to find the result 87*2175Sjp161948to the prompt. 88*2175Sjp161948 89*2175Sjp161948A UI can contain more than one prompt, which are performed in the given 90*2175Sjp161948sequence. Each prompt gets an index number which is returned by the 91*2175Sjp161948UI_add and UI_dup functions, and has to be used to get the corresponding 92*2175Sjp161948result with UI_get0_result(). 93*2175Sjp161948 94*2175Sjp161948The functions are as follows: 95*2175Sjp161948 96*2175Sjp161948UI_new() creates a new UI using the default UI method. When done with 97*2175Sjp161948this UI, it should be freed using UI_free(). 98*2175Sjp161948 99*2175Sjp161948UI_new_method() creates a new UI using the given UI method. When done with 100*2175Sjp161948this UI, it should be freed using UI_free(). 101*2175Sjp161948 102*2175Sjp161948UI_OpenSSL() returns the built-in UI method (note: not the default one, 103*2175Sjp161948since the default can be changed. See further on). This method is the 104*2175Sjp161948most machine/OS dependent part of OpenSSL and normally generates the 105*2175Sjp161948most problems when porting. 106*2175Sjp161948 107*2175Sjp161948UI_free() removes a UI from memory, along with all other pieces of memory 108*2175Sjp161948that's connected to it, like duplicated input strings, results and others. 109*2175Sjp161948 110*2175Sjp161948UI_add_input_string() and UI_add_verify_string() add a prompt to the UI, 111*2175Sjp161948as well as flags and a result buffer and the desired minimum and maximum 112*2175Sjp161948sizes of the result. The given information is used to prompt for 113*2175Sjp161948information, for example a password, and to verify a password (i.e. having 114*2175Sjp161948the user enter it twice and check that the same string was entered twice). 115*2175Sjp161948UI_add_verify_string() takes and extra argument that should be a pointer 116*2175Sjp161948to the result buffer of the input string that it's supposed to verify, or 117*2175Sjp161948verification will fail. 118*2175Sjp161948 119*2175Sjp161948UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered 120*2175Sjp161948in a boolean way, with a single character for yes and a different character 121*2175Sjp161948for no. A set of characters that can be used to cancel the prompt is given 122*2175Sjp161948as well. The prompt itself is really divided in two, one part being the 123*2175Sjp161948descriptive text (given through the I<prompt> argument) and one describing 124*2175Sjp161948the possible answers (given through the I<action_desc> argument). 125*2175Sjp161948 126*2175Sjp161948UI_add_info_string() and UI_add_error_string() add strings that are shown at 127*2175Sjp161948the same time as the prompt for extra information or to show an error string. 128*2175Sjp161948The difference between the two is only conceptual. With the builtin method, 129*2175Sjp161948there's no technical difference between them. Other methods may make a 130*2175Sjp161948difference between them, however. 131*2175Sjp161948 132*2175Sjp161948The flags currently supported are UI_INPUT_FLAG_ECHO, which is relevant for 133*2175Sjp161948UI_add_input_string() and will have the users response be echoed (when 134*2175Sjp161948prompting for a password, this flag should obviously not be used, and 135*2175Sjp161948UI_INPUT_FLAG_DEFAULT_PWD, which means that a default password of some 136*2175Sjp161948sort will be used (completely depending on the application and the UI 137*2175Sjp161948method). 138*2175Sjp161948 139*2175Sjp161948UI_dup_input_string(), UI_dup_verify_string(), UI_dup_input_boolean(), 140*2175Sjp161948UI_dup_info_string() and UI_dup_error_string() are basically the same 141*2175Sjp161948as their UI_add counterparts, except that they make their own copies 142*2175Sjp161948of all strings. 143*2175Sjp161948 144*2175Sjp161948UI_construct_prompt() is a helper function that can be used to create 145*2175Sjp161948a prompt from two pieces of information: an description and a name. 146*2175Sjp161948The default constructor (if there is none provided by the method used) 147*2175Sjp161948creates a string "Enter I<description> for I<name>:". With the 148*2175Sjp161948description "pass phrase" and the file name "foo.key", that becomes 149*2175Sjp161948"Enter pass phrase for foo.key:". Other methods may create whatever 150*2175Sjp161948string and may include encodings that will be processed by the other 151*2175Sjp161948method functions. 152*2175Sjp161948 153*2175Sjp161948UI_add_user_data() adds a piece of memory for the method to use at any 154*2175Sjp161948time. The builtin UI method doesn't care about this info. Note that several 155*2175Sjp161948calls to this function doesn't add data, it replaces the previous blob 156*2175Sjp161948with the one given as argument. 157*2175Sjp161948 158*2175Sjp161948UI_get0_user_data() retrieves the data that has last been given to the 159*2175Sjp161948UI with UI_add_user_data(). 160*2175Sjp161948 161*2175Sjp161948UI_get0_result() returns a pointer to the result buffer associated with 162*2175Sjp161948the information indexed by I<i>. 163*2175Sjp161948 164*2175Sjp161948UI_process() goes through the information given so far, does all the printing 165*2175Sjp161948and prompting and returns. 166*2175Sjp161948 167*2175Sjp161948UI_ctrl() adds extra control for the application author. For now, it 168*2175Sjp161948understands two commands: UI_CTRL_PRINT_ERRORS, which makes UI_process() 169*2175Sjp161948print the OpenSSL error stack as part of processing the UI, and 170*2175Sjp161948UI_CTRL_IS_REDOABLE, which returns a flag saying if the used UI can 171*2175Sjp161948be used again or not. 172*2175Sjp161948 173*2175Sjp161948UI_set_default_method() changes the default UI method to the one given. 174*2175Sjp161948 175*2175Sjp161948UI_get_default_method() returns a pointer to the current default UI method. 176*2175Sjp161948 177*2175Sjp161948UI_get_method() returns the UI method associated with a given UI. 178*2175Sjp161948 179*2175Sjp161948UI_set_method() changes the UI method associated with a given UI. 180*2175Sjp161948 181*2175Sjp161948=head1 SEE ALSO 182*2175Sjp161948 183*2175Sjp161948L<ui_create(3)|ui_create(3)>, L<ui_compat(3)|ui_compat(3)> 184*2175Sjp161948 185*2175Sjp161948=head1 HISTORY 186*2175Sjp161948 187*2175Sjp161948The UI section was first introduced in OpenSSL 0.9.7. 188*2175Sjp161948 189*2175Sjp161948=head1 AUTHOR 190*2175Sjp161948 191*2175Sjp161948Richard Levitte (richard@levitte.org) for the OpenSSL project 192*2175Sjp161948(http://www.openssl.org). 193*2175Sjp161948 194*2175Sjp161948=cut 195