1.\" $OpenBSD: UI_new.3,v 1.9 2019/06/10 09:49:48 schwarze Exp $ 2.\" full merge up to: OpenSSL 78b19e90 Jan 11 00:12:01 2017 +0100 3.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 4.\" 5.\" This file was written by Richard Levitte <levitte@openssl.org>. 6.\" Copyright (c) 2001, 2016, 2017 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: June 10 2019 $ 53.Dt UI_NEW 3 54.Os 55.Sh NAME 56.Nm UI_new , 57.Nm UI_new_method , 58.Nm UI_free , 59.Nm UI_add_input_string , 60.Nm UI_dup_input_string , 61.Nm UI_add_verify_string , 62.Nm UI_dup_verify_string , 63.Nm UI_add_input_boolean , 64.Nm UI_dup_input_boolean , 65.Nm UI_add_info_string , 66.Nm UI_dup_info_string , 67.Nm UI_add_error_string , 68.Nm UI_dup_error_string , 69.Nm UI_construct_prompt , 70.Nm UI_add_user_data , 71.Nm UI_get0_user_data , 72.Nm UI_get0_result , 73.Nm UI_process , 74.Nm UI_ctrl , 75.Nm UI_set_default_method , 76.Nm UI_get_default_method , 77.Nm UI_get_method , 78.Nm UI_set_method , 79.Nm UI_OpenSSL 80.Nd New User Interface 81.Sh SYNOPSIS 82.In openssl/ui.h 83.Ft UI * 84.Fn UI_new void 85.Ft UI * 86.Fo UI_new_method 87.Fa "const UI_METHOD *method" 88.Fc 89.Ft void 90.Fo UI_free 91.Fa "UI *ui" 92.Fc 93.Ft int 94.Fo UI_add_input_string 95.Fa "UI *ui" 96.Fa "const char *prompt" 97.Fa "int flags" 98.Fa "char *result_buf" 99.Fa "int minsize" 100.Fa "int maxsize" 101.Fc 102.Ft int 103.Fo UI_dup_input_string 104.Fa "UI *ui" 105.Fa "const char *prompt" 106.Fa "int flags" 107.Fa "char *result_buf" 108.Fa "int minsize" 109.Fa "int maxsize" 110.Fc 111.Ft int 112.Fo UI_add_verify_string 113.Fa "UI *ui" 114.Fa "const char *prompt" 115.Fa "int flags" 116.Fa "char *result_buf" 117.Fa "int minsize" 118.Fa "int maxsize" 119.Fa "const char *test_buf" 120.Fc 121.Ft int 122.Fo UI_dup_verify_string 123.Fa "UI *ui" 124.Fa "const char *prompt" 125.Fa "int flags" 126.Fa "char *result_buf" 127.Fa "int minsize" 128.Fa "int maxsize" 129.Fa "const char *test_buf" 130.Fc 131.Ft int 132.Fo UI_add_input_boolean 133.Fa "UI *ui" 134.Fa "const char *prompt" 135.Fa "const char *action_desc" 136.Fa "const char *ok_chars" 137.Fa "const char *cancel_chars" 138.Fa "int flags" 139.Fa "char *result_buf" 140.Fc 141.Ft int 142.Fo UI_dup_input_boolean 143.Fa "UI *ui" 144.Fa "const char *prompt" 145.Fa "const char *action_desc" 146.Fa "const char *ok_chars" 147.Fa "const char *cancel_chars" 148.Fa "int flags" 149.Fa "char *result_buf" 150.Fc 151.Ft int 152.Fo UI_add_info_string 153.Fa "UI *ui" 154.Fa "const char *text" 155.Fc 156.Ft int 157.Fo UI_dup_info_string 158.Fa "UI *ui" 159.Fa "const char *text" 160.Fc 161.Ft int 162.Fo UI_add_error_string 163.Fa "UI *ui" 164.Fa "const char *text" 165.Fc 166.Ft int 167.Fo UI_dup_error_string 168.Fa "UI *ui" 169.Fa "const char *text" 170.Fc 171.Fd /* These are the possible flags. They can be OR'ed together. */ 172.Fd #define UI_INPUT_FLAG_ECHO 0x01 173.Fd #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 174.Ft char * 175.Fo UI_construct_prompt 176.Fa "UI *ui_method" 177.Fa "const char *object_desc" 178.Fa "const char *object_name" 179.Fc 180.Ft void * 181.Fo UI_add_user_data 182.Fa "UI *ui" 183.Fa "void *user_data" 184.Fc 185.Ft void * 186.Fo UI_get0_user_data 187.Fa "UI *ui" 188.Fc 189.Ft const char * 190.Fo UI_get0_result 191.Fa "UI *ui" 192.Fa "int i" 193.Fc 194.Ft int 195.Fo UI_process 196.Fa "UI *ui" 197.Fc 198.Ft int 199.Fo UI_ctrl 200.Fa "UI *ui" 201.Fa "int cmd" 202.Fa "long i" 203.Fa "void *p" 204.Fa "void (*f)()" 205.Fc 206.Fd #define UI_CTRL_PRINT_ERRORS 1 207.Fd #define UI_CTRL_IS_REDOABLE 2 208.Ft void 209.Fo UI_set_default_method 210.Fa "const UI_METHOD *meth" 211.Fc 212.Ft const UI_METHOD * 213.Fo UI_get_default_method 214.Fa void 215.Fc 216.Ft const UI_METHOD * 217.Fo UI_get_method 218.Fa "UI *ui" 219.Fc 220.Ft const UI_METHOD * 221.Fo UI_set_method 222.Fa "UI *ui" 223.Fa "const UI_METHOD *meth" 224.Fc 225.Ft UI_METHOD * 226.Fo UI_OpenSSL 227.Fa void 228.Fc 229.Sh DESCRIPTION 230UI stands for User Interface, and is a general purpose set of routines 231to prompt the user for text-based information. 232Through user-written methods (see 233.Xr UI_create_method 3 ) , 234prompting can be done in any way imaginable, be it plain text prompting, 235through dialog boxes or from a cell phone. 236.Pp 237All the functions work through a context of the type 238.Vt UI . 239This context contains all the information needed to prompt correctly 240as well as a reference to a 241.Vt UI_METHOD , 242which is an ordered vector of functions that carry out the actual 243prompting. 244.Pp 245The first thing to do is to create a 246.Vt UI 247with 248.Fn UI_new 249or 250.Fn UI_new_method , 251then add information to it with the 252.Fn UI_add_* 253or 254.Fn UI_dup_* 255functions. 256Also, user-defined random data can be passed down to the underlying 257method through calls to 258.Fn UI_add_user_data . 259The default UI method doesn't care about these data, but other methods 260might. 261Finally, use 262.Fn UI_process 263to actually perform the prompting and 264.Fn UI_get0_result 265to find the result to the prompt. 266.Pp 267A 268.Vt UI 269can contain more than one prompt, which are performed in the given 270sequence. 271Each prompt gets an index number which is returned by the 272.Fn UI_add_* 273and 274.Fn UI_dup_* 275functions, and has to be used to get the corresponding result with 276.Fn UI_get0_result . 277.Pp 278The functions are as follows: 279.Pp 280.Fn UI_new 281creates a new 282.Vt UI 283using the default UI method. 284When done with this UI, it should be freed using 285.Fn UI_free . 286.Pp 287.Fn UI_new_method 288creates a new 289.Vt UI 290using the given UI method. 291When done with this UI, it should be freed using 292.Fn UI_free . 293.Pp 294.Fn UI_OpenSSL 295returns the built-in UI method (note: not necessarily the default one, 296since the default can be changed. 297See further on). 298This method is the most machine/OS dependent part of OpenSSL and 299normally generates the most problems when porting. 300.Pp 301.Fn UI_free 302removes 303.Fa ui 304from memory, along with all other pieces of memory that are connected 305to it, like duplicated input strings, results and others. 306If 307.Fa ui 308is a 309.Dv NULL 310pointer, no action occurs. 311.Pp 312.Fn UI_add_input_string 313and 314.Fn UI_add_verify_string 315add a prompt to 316.Fa ui , 317as well as flags and a result buffer and the desired minimum and 318maximum sizes of the result, not counting the final NUL character. 319The given information is used to prompt for information, for example 320a password, and to verify a password (i.e. having the user enter 321it twice and check that the same string was entered twice). 322.Fn UI_add_verify_string 323takes an extra argument that should be a pointer to the result buffer 324of the input string that it's supposed to verify, or verification will 325fail. 326.Pp 327.Fn UI_add_input_boolean 328adds a prompt to 329.Fa ui 330that's supposed to be answered in a boolean way, with a single 331character for yes and a different character for no. 332A set of characters that can be used to cancel the prompt is given as 333well. 334The prompt itself is really divided in two, one part being the 335descriptive text (given through the 336.Fa prompt 337argument) and one describing the possible answers (given through the 338.Fa action_desc 339argument). 340.Pp 341.Fn UI_add_info_string 342and 343.Fn UI_add_error_string 344add strings that are shown at the same time as the prompt for extra 345information or to show an error string. 346The difference between the two is only conceptual. 347With the builtin method, there's no technical difference between them. 348Other methods may make a difference between them, however. 349.Pp 350The flags currently supported are 351.Dv UI_INPUT_FLAG_ECHO , 352which is relevant for 353.Fn UI_add_input_string 354and will have the users response be echoed (when prompting for a 355password, this flag should obviously not be used), and 356.Dv UI_INPUT_FLAG_DEFAULT_PWD , 357which means that a default password of some sort will be used 358(completely depending on the application and the UI method). 359.Pp 360.Fn UI_dup_input_string , 361.Fn UI_dup_verify_string , 362.Fn UI_dup_input_boolean , 363.Fn UI_dup_info_string , 364and 365.Fn UI_dup_error_string 366are basically the same as their 367.Fn UI_add_* 368counterparts, except that they make their own copies of all strings. 369.Pp 370.Fn UI_construct_prompt 371is a helper function that can be used to create a prompt from two pieces 372of information: a description and a name. 373The default constructor (if there is none provided by the method used) 374creates a string "Enter 375.Em description 376for 377.Em name Ns :". 378With the description "pass phrase" and the file name "foo.key", that 379becomes "Enter pass phrase for foo.key:". Other methods may create 380whatever string and may include encodings that will be processed by the 381other method functions. 382.Pp 383.Fn UI_add_user_data 384adds a user data pointer for the method to use at any time. 385The builtin UI method doesn't care about this info. 386Note that several calls to this function doesn't add data - 387the previous blob is replaced with the one given as argument. 388.Pp 389.Fn UI_get0_user_data 390retrieves the data that has last been given to the 391.Fa ui 392with 393.Fn UI_add_user_data . 394.Pp 395.Fn UI_get0_result 396returns a pointer to the result buffer associated with the information 397indexed by 398.Fa i . 399.Pp 400.Fn UI_process 401goes through the information given so far, does all the printing and 402prompting and returns the final status, which is -2 on out-of-band 403events (Interrupt, Cancel, ...), -1 on error, or 0 on success. 404.Pp 405.Fn UI_ctrl 406adds extra control for the application author. 407For now, it understands two commands: 408.Dv UI_CTRL_PRINT_ERRORS , 409which makes 410.Fn UI_process 411print the OpenSSL error stack as part of processing the 412.Fa ui , 413and 414.Dv UI_CTRL_IS_REDOABLE , 415which returns a flag saying if the used 416.Fa ui 417can be used again or not. 418.Pp 419.Fn UI_set_default_method 420changes the default UI method to the one given. 421This function is not thread-safe and should not be called at the 422same time as other OpenSSL functions. 423.Pp 424.Fn UI_get_default_method 425returns a pointer to the current default UI method. 426.Pp 427.Fn UI_get_method 428returns the UI method associated with a given 429.Fa ui . 430.Pp 431.Fn UI_set_method 432changes the UI method associated with a given 433.Fa ui . 434.Sh RETURN VALUES 435.Fn UI_new 436and 437.Fn UI_new_method 438return a valid 439.Vt UI 440structure or 441.Dv NULL 442if an error occurred. 443.Pp 444.Fn UI_add_input_string , 445.Fn UI_dup_input_string , 446.Fn UI_add_verify_string , 447.Fn UI_dup_verify_string , 448.Fn UI_add_input_boolean , 449.Fn UI_dup_input_boolean , 450.Fn UI_add_info_string , 451.Fn UI_dup_info_string , 452.Fn UI_add_error_string , 453and 454.Fn UI_dup_error_string 455return a positive number on success or a number 456less than or equal to zero otherwise. 457.Pp 458.Fn UI_construct_prompt 459and 460.Fn UI_get0_result 461return a string or 462.Dv NULL 463if an error occurred. 464.Pp 465.Fn UI_add_user_data 466and 467.Fn UI_get0_user_data 468return a pointer to the user data that was contained in 469.Fa ui 470before the call. 471In particular, 472.Dv NULL 473is a valid return value. 474.Pp 475.Fn UI_process 476returns 0 on success or a negative value on error. 477.Pp 478.Fn UI_ctrl 479returns a mask on success or \-1 on error. 480.Pp 481.Fn UI_get_default_method 482and 483.Fn UI_OpenSSL 484always return a pointer to a valid 485.Vt UI_METHOD 486structure. 487.Pp 488.Fn UI_get_method 489and 490.Fn UI_set_method 491return a pointer to the 492.Vt UI_METHOD 493structure that is installed in 494.Fa ui 495after the call. 496The OpenSSL documentation says that they can fail and return 497.Dv NULL , 498but currently, this can only happen when and after 499.Fn UI_set_method 500is called with an explicit 501.Dv NULL 502argument. 503.Sh SEE ALSO 504.Xr crypto 3 , 505.Xr des_read_pw 3 , 506.Xr UI_create_method 3 , 507.Xr UI_get_string_type 3 , 508.Xr UI_UTIL_read_pw 3 509.Sh HISTORY 510These functions first appeared in OpenSSL 0.9.7 511and have been available since 512.Ox 3.2 . 513.Sh AUTHORS 514.An Richard Levitte Aq Mt richard@levitte.org 515for the OpenSSL project. 516