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