doc/man3/UI_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 UI,
   6 UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string,
   7 UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean,
   8 UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string,
   9 UI_add_error_string, UI_dup_error_string, UI_construct_prompt,
  10 UI_add_user_data, UI_dup_user_data, UI_get0_user_data, UI_get0_result,
  11 UI_process, UI_ctrl, UI_set_default_method, UI_get_default_method,
  12 UI_get_method, UI_set_method, UI_OpenSSL, UI_null - user interface
  13
  14 =head1 SYNOPSIS
  15
  16  #include <openssl/ui.h>
  17
  18  typedef struct ui_st UI;
  19
  20  UI *UI_new(void);
  21  UI *UI_new_method(const UI_METHOD *method);
  22  void UI_free(UI *ui);
  23
  24  int UI_add_input_string(UI *ui, const char *prompt, int flags,
  25         char *result_buf, int minsize, int maxsize);
  26  int UI_dup_input_string(UI *ui, const char *prompt, int flags,
  27         char *result_buf, int minsize, int maxsize);
  28  int UI_add_verify_string(UI *ui, const char *prompt, int flags,
  29         char *result_buf, int minsize, int maxsize, const char *test_buf);
  30  int UI_dup_verify_string(UI *ui, const char *prompt, int flags,
  31         char *result_buf, int minsize, int maxsize, const char *test_buf);
  32  int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc,
  33         const char *ok_chars, const char *cancel_chars,
  34         int flags, char *result_buf);
  35  int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc,
  36         const char *ok_chars, const char *cancel_chars,
  37         int flags, char *result_buf);
  38  int UI_add_info_string(UI *ui, const char *text);
  39  int UI_dup_info_string(UI *ui, const char *text);
  40  int UI_add_error_string(UI *ui, const char *text);
  41  int UI_dup_error_string(UI *ui, const char *text);
  42
  43  char *UI_construct_prompt(UI *ui_method,
  44         const char *object_desc, const char *object_name);
  45
  46  void *UI_add_user_data(UI *ui, void *user_data);
  47  int UI_dup_user_data(UI *ui, void *user_data);
  48  void *UI_get0_user_data(UI *ui);
  49
  50  const char *UI_get0_result(UI *ui, int i);
  51
  52  int UI_process(UI *ui);
  53
  54  int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)());
  55
  56  void UI_set_default_method(const UI_METHOD *meth);
  57  const UI_METHOD *UI_get_default_method(void);
  58  const UI_METHOD *UI_get_method(UI *ui);
  59  const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth);
  60
  61  UI_METHOD *UI_OpenSSL(void);
  62  const UI_METHOD *UI_null(void);
  63
  64 =head1 DESCRIPTION
  65
  66 UI stands for User Interface, and is general purpose set of routines to
  67 prompt the user for text-based information.  Through user-written methods
  68 (see L<UI_create_method(3)>), prompting can be done in any way
  69 imaginable, be it plain text prompting, through dialog boxes or from a
  70 cell phone.
  71
  72 All the functions work through a context of the type UI.  This context
  73 contains all the information needed to prompt correctly as well as a
  74 reference to a UI_METHOD, which is an ordered vector of functions that
  75 carry out the actual prompting.
  76
  77 The first thing to do is to create a UI with UI_new() or UI_new_method(),
  78 then add information to it with the UI_add or UI_dup functions.  Also,
  79 user-defined random data can be passed down to the underlying method
  80 through calls to UI_add_user_data() or UI_dup_user_data().  The default
  81 UI method doesn't care about these data, but other methods might.  Finally,
  82 use UI_process() to actually perform the prompting and UI_get0_result()
  83 to find the result to the prompt.
  84
  85 A UI can contain more than one prompt, which are performed in the given
  86 sequence.  Each prompt gets an index number which is returned by the
  87 UI_add and UI_dup functions, and has to be used to get the corresponding
  88 result with UI_get0_result().
  89
  90 UI_process() can be called more than once on the same UI, thereby allowing
  91 a UI to have a long lifetime, but can just as well have a short lifetime.
  92
  93 The functions are as follows:
  94
  95 UI_new() creates a new UI using the default UI method.  When done with
  96 this UI, it should be freed using UI_free().
  97
  98 UI_new_method() creates a new UI using the given UI method.  When done with
  99 this UI, it should be freed using UI_free().
 100
 101 UI_OpenSSL() returns the built-in UI method (note: not necessarely the
 102 default one, since the default can be changed.  See further on).  This
 103 method is the most machine/OS dependent part of OpenSSL and normally
 104 generates the most problems when porting.
 105
 106 UI_null() returns a UI method that does nothing.  Its use is to avoid
 107 getting internal defaults for passed UI_METHOD pointers.
 108
 109 UI_free() removes a UI from memory, along with all other pieces of memory
 110 that's connected to it, like duplicated input strings, results and others.
 111 If B<ui> is NULL nothing is done.
 112
 113 UI_add_input_string() and UI_add_verify_string() add a prompt to the UI,
 114 as well as flags and a result buffer and the desired minimum and maximum
 115 sizes of the result, not counting the final NUL character.  The given
 116 information is used to prompt for information, for example a password,
 117 and to verify a password (i.e. having the user enter it twice and check
 118 that the same string was entered twice).  UI_add_verify_string() takes
 119 and extra argument that should be a pointer to the result buffer of the
 120 input string that it's supposed to verify, or verification will fail.
 121
 122 UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered
 123 in a boolean way, with a single character for yes and a different character
 124 for no.  A set of characters that can be used to cancel the prompt is given
 125 as well.  The prompt itself is divided in two, one part being the
 126 descriptive text (given through the I<prompt> argument) and one describing
 127 the possible answers (given through the I<action_desc> argument).
 128
 129 UI_add_info_string() and UI_add_error_string() add strings that are shown at
 130 the same time as the prompt for extra information or to show an error string.
 131 The difference between the two is only conceptual.  With the builtin method,
 132 there's no technical difference between them.  Other methods may make a
 133 difference between them, however.
 134
 135 The flags currently supported are B<UI_INPUT_FLAG_ECHO>, which is relevant for
 136 UI_add_input_string() and will have the users response be echoed (when
 137 prompting for a password, this flag should obviously not be used, and
 138 B<UI_INPUT_FLAG_DEFAULT_PWD>, which means that a default password of some
 139 sort will be used (completely depending on the application and the UI
 140 method).
 141
 142 UI_dup_input_string(), UI_dup_verify_string(), UI_dup_input_boolean(),
 143 UI_dup_info_string() and UI_dup_error_string() are basically the same
 144 as their UI_add counterparts, except that they make their own copies
 145 of all strings.
 146
 147 UI_construct_prompt() is a helper function that can be used to create
 148 a prompt from two pieces of information: an description and a name.
 149 The default constructor (if there is none provided by the method used)
 150 creates a string "Enter I<description> for I<name>:".  With the
 151 description "pass phrase" and the file name "foo.key", that becomes
 152 "Enter pass phrase for foo.key:".  Other methods may create whatever
 153 string and may include encodings that will be processed by the other
 154 method functions.
 155
 156 UI_add_user_data() adds a user data pointer for the method to use at any
 157 time.  The builtin UI method doesn't care about this info.  Note that several
 158 calls to this function doesn't add data, it replaces the previous blob
 159 with the one given as argument.
 160
 161 UI_dup_user_data() duplicates the user data and works as an alternative
 162 to UI_add_user_data() when the user data needs to be preserved for a longer
 163 duration, perhaps even the lifetime of the application.  The UI object takes
 164 ownership of this duplicate and will free it whenever it gets replaced or
 165 the UI is destroyed.  UI_dup_user_data() returns 0 on success, or -1 on memory
 166 allocation failure or if the method doesn't have a duplicator function.
 167
 168 UI_get0_user_data() retrieves the data that has last been given to the
 169 UI with UI_add_user_data() or UI_dup_user_data.
 170
 171 UI_get0_result() returns a pointer to the result buffer associated with
 172 the information indexed by I<i>.
 173
 174 UI_process() goes through the information given so far, does all the printing
 175 and prompting and returns the final status, which is -2 on out-of-band events
 176 (Interrupt, Cancel, ...), -1 on error and 0 on success.
 177
 178 UI_ctrl() adds extra control for the application author.  For now, it
 179 understands two commands: B<UI_CTRL_PRINT_ERRORS>, which makes UI_process()
 180 print the OpenSSL error stack as part of processing the UI, and
 181 B<UI_CTRL_IS_REDOABLE>, which returns a flag saying if the used UI can
 182 be used again or not.
 183
 184 UI_set_default_method() changes the default UI method to the one given.
 185 This function is not thread-safe and should not be called at the same time
 186 as other OpenSSL functions.
 187
 188 UI_get_default_method() returns a pointer to the current default UI method.
 189
 190 UI_get_method() returns the UI method associated with a given UI.
 191
 192 UI_set_method() changes the UI method associated with a given UI.
 193
 194 =head1 NOTES
 195
 196 The resulting strings that the built in method UI_OpenSSL() generate
 197 are assumed to be encoded according to the current locale or (for
 198 Windows) code page.
 199 For applications having different demands, these strings need to be
 200 converted appropriately by the caller.
 201 For Windows, if the OPENSSL_WIN32_UTF8 environment variable is set,
 202 the built-in method UI_OpenSSL() will produce UTF-8 encoded strings
 203 instead.
 204
 205 =head1 HISTORY
 206
 207 UI_dup_user_data()
 208 was added in OpenSSL 1.1.1.
 209
 210 =head1 COPYRIGHT
 211
 212 Copyright 2001-2017 The OpenSSL Project Authors. All Rights Reserved.
 213
 214 Licensed under the OpenSSL license (the "License").  You may not use
 215 this file except in compliance with the License.  You can obtain a copy
 216 in the file LICENSE in the source distribution or at
 217 L<https://www.openssl.org/source/license.html>.
 218
 219 =cut