1.\" $OpenBSD: UI_new.3,v 1.12 2024/08/24 07:48:37 tb 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: August 24 2024 $ 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.Nm UI_null 81.Nd New User Interface 82.Sh SYNOPSIS 83.In openssl/ui.h 84.Ft UI * 85.Fn UI_new void 86.Ft UI * 87.Fo UI_new_method 88.Fa "const UI_METHOD *method" 89.Fc 90.Ft void 91.Fo UI_free 92.Fa "UI *ui" 93.Fc 94.Ft int 95.Fo UI_add_input_string 96.Fa "UI *ui" 97.Fa "const char *prompt" 98.Fa "int flags" 99.Fa "char *result_buf" 100.Fa "int minsize" 101.Fa "int maxsize" 102.Fc 103.Ft int 104.Fo UI_dup_input_string 105.Fa "UI *ui" 106.Fa "const char *prompt" 107.Fa "int flags" 108.Fa "char *result_buf" 109.Fa "int minsize" 110.Fa "int maxsize" 111.Fc 112.Ft int 113.Fo UI_add_verify_string 114.Fa "UI *ui" 115.Fa "const char *prompt" 116.Fa "int flags" 117.Fa "char *result_buf" 118.Fa "int minsize" 119.Fa "int maxsize" 120.Fa "const char *test_buf" 121.Fc 122.Ft int 123.Fo UI_dup_verify_string 124.Fa "UI *ui" 125.Fa "const char *prompt" 126.Fa "int flags" 127.Fa "char *result_buf" 128.Fa "int minsize" 129.Fa "int maxsize" 130.Fa "const char *test_buf" 131.Fc 132.Ft int 133.Fo UI_add_input_boolean 134.Fa "UI *ui" 135.Fa "const char *prompt" 136.Fa "const char *action_desc" 137.Fa "const char *ok_chars" 138.Fa "const char *cancel_chars" 139.Fa "int flags" 140.Fa "char *result_buf" 141.Fc 142.Ft int 143.Fo UI_dup_input_boolean 144.Fa "UI *ui" 145.Fa "const char *prompt" 146.Fa "const char *action_desc" 147.Fa "const char *ok_chars" 148.Fa "const char *cancel_chars" 149.Fa "int flags" 150.Fa "char *result_buf" 151.Fc 152.Ft int 153.Fo UI_add_info_string 154.Fa "UI *ui" 155.Fa "const char *text" 156.Fc 157.Ft int 158.Fo UI_dup_info_string 159.Fa "UI *ui" 160.Fa "const char *text" 161.Fc 162.Ft int 163.Fo UI_add_error_string 164.Fa "UI *ui" 165.Fa "const char *text" 166.Fc 167.Ft int 168.Fo UI_dup_error_string 169.Fa "UI *ui" 170.Fa "const char *text" 171.Fc 172.Fd /* These are the possible flags. They can be OR'ed together. */ 173.Fd #define UI_INPUT_FLAG_ECHO 0x01 174.Fd #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 175.Ft char * 176.Fo UI_construct_prompt 177.Fa "UI *ui_method" 178.Fa "const char *object_desc" 179.Fa "const char *object_name" 180.Fc 181.Ft void * 182.Fo UI_add_user_data 183.Fa "UI *ui" 184.Fa "void *user_data" 185.Fc 186.Ft void * 187.Fo UI_get0_user_data 188.Fa "UI *ui" 189.Fc 190.Ft const char * 191.Fo UI_get0_result 192.Fa "UI *ui" 193.Fa "int i" 194.Fc 195.Ft int 196.Fo UI_process 197.Fa "UI *ui" 198.Fc 199.Ft int 200.Fo UI_ctrl 201.Fa "UI *ui" 202.Fa "int cmd" 203.Fa "long i" 204.Fa "void *p" 205.Fa "void (*f)()" 206.Fc 207.Fd #define UI_CTRL_PRINT_ERRORS 1 208.Fd #define UI_CTRL_IS_REDOABLE 2 209.Ft void 210.Fo UI_set_default_method 211.Fa "const UI_METHOD *meth" 212.Fc 213.Ft const UI_METHOD * 214.Fo UI_get_default_method 215.Fa void 216.Fc 217.Ft const UI_METHOD * 218.Fo UI_get_method 219.Fa "UI *ui" 220.Fc 221.Ft const UI_METHOD * 222.Fo UI_set_method 223.Fa "UI *ui" 224.Fa "const UI_METHOD *meth" 225.Fc 226.Ft UI_METHOD * 227.Fo UI_OpenSSL 228.Fa void 229.Fc 230.Ft const UI_METHOD * 231.Fo UI_null 232.Fa void 233.Fc 234.Sh DESCRIPTION 235UI stands for User Interface, and is a general purpose set of routines 236to prompt the user for text-based information. 237Through user-written methods (see 238.Xr UI_create_method 3 ) , 239prompting can be done in any way imaginable, be it plain text prompting, 240through dialog boxes or from a cell phone. 241.Pp 242All the functions work through a context of the type 243.Vt UI . 244This context contains all the information needed to prompt correctly 245as well as a reference to a 246.Vt UI_METHOD , 247which is an ordered vector of functions that carry out the actual 248prompting. 249.Pp 250The first thing to do is to create a 251.Vt UI 252with 253.Fn UI_new 254or 255.Fn UI_new_method , 256then add information to it with the 257.Fn UI_add_* 258or 259.Fn UI_dup_* 260functions. 261Also, user-defined random data can be passed down to the underlying 262method through calls to 263.Fn UI_add_user_data . 264The default UI method doesn't care about these data, but other methods 265might. 266Finally, use 267.Fn UI_process 268to actually perform the prompting and 269.Fn UI_get0_result 270to find the result to the prompt. 271.Pp 272A 273.Vt UI 274can contain more than one prompt, which are performed in the given 275sequence. 276Each prompt gets an index number which is returned by the 277.Fn UI_add_* 278and 279.Fn UI_dup_* 280functions, and has to be used to get the corresponding result with 281.Fn UI_get0_result . 282.Pp 283The functions are as follows: 284.Pp 285.Fn UI_new 286creates a new 287.Vt UI 288using the default UI method. 289When done with this UI, it should be freed using 290.Fn UI_free . 291.Pp 292.Fn UI_new_method 293creates a new 294.Vt UI 295using the given UI method. 296When done with this UI, it should be freed using 297.Fn UI_free . 298.Pp 299.Fn UI_OpenSSL 300returns the built-in UI method (note: not necessarily the default one, 301since the default can be changed. 302See further on). 303This method is the most machine/OS dependent part of OpenSSL and 304normally generates the most problems when porting. 305.Pp 306.Fn UI_null 307returns a UI method that does nothing. 308Its use is to avoid getting internal defaults for passed 309.Vt UI_METHOD 310pointers. 311.Pp 312.Fn UI_free 313removes 314.Fa ui 315from memory, along with all other pieces of memory that are connected 316to it, like duplicated input strings, results and others. 317If 318.Fa ui 319is a 320.Dv NULL 321pointer, no action occurs. 322.Pp 323.Fn UI_add_input_string 324and 325.Fn UI_add_verify_string 326add a prompt to 327.Fa ui , 328as well as flags and a result buffer and the desired minimum and 329maximum sizes of the result, not counting the final NUL character. 330The given information is used to prompt for information, for example 331a password, and to verify a password (i.e. having the user enter 332it twice and check that the same string was entered twice). 333.Fn UI_add_verify_string 334takes an extra argument that should be a pointer to the result buffer 335of the input string that it's supposed to verify, or verification will 336fail. 337.Pp 338.Fn UI_add_input_boolean 339adds a prompt to 340.Fa ui 341that's supposed to be answered in a boolean way, with a single 342character for yes and a different character for no. 343A set of characters that can be used to cancel the prompt is given as 344well. 345The prompt itself is really divided in two, one part being the 346descriptive text (given through the 347.Fa prompt 348argument) and one describing the possible answers (given through the 349.Fa action_desc 350argument). 351.Pp 352.Fn UI_add_info_string 353and 354.Fn UI_add_error_string 355add strings that are shown at the same time as the prompt for extra 356information or to show an error string. 357The difference between the two is only conceptual. 358With the builtin method, there's no technical difference between them. 359Other methods may make a difference between them, however. 360.Pp 361The flags currently supported are 362.Dv UI_INPUT_FLAG_ECHO , 363which is relevant for 364.Fn UI_add_input_string 365and will have the users response be echoed (when prompting for a 366password, this flag should obviously not be used), and 367.Dv UI_INPUT_FLAG_DEFAULT_PWD , 368which means that a default password of some sort will be used 369(completely depending on the application and the UI method). 370.Pp 371.Fn UI_dup_input_string , 372.Fn UI_dup_verify_string , 373.Fn UI_dup_input_boolean , 374.Fn UI_dup_info_string , 375and 376.Fn UI_dup_error_string 377are basically the same as their 378.Fn UI_add_* 379counterparts, except that they make their own copies of all strings. 380.Pp 381.Fn UI_construct_prompt 382is a helper function that can be used to create a prompt from two pieces 383of information: a description and a name. 384The default constructor (if there is none provided by the method used) 385creates a string "Enter 386.Em description 387for 388.Em name Ns :". 389With the description "pass phrase" and the file name "foo.key", that 390becomes "Enter pass phrase for foo.key:". Other methods may create 391whatever string and may include encodings that will be processed by the 392other method functions. 393.Pp 394.Fn UI_add_user_data 395adds a user data pointer for the method to use at any time. 396The builtin UI method doesn't care about this info. 397Note that several calls to this function doesn't add data - 398the previous blob is replaced with the one given as argument. 399.Pp 400.Fn UI_get0_user_data 401retrieves the data that has last been given to the 402.Fa ui 403with 404.Fn UI_add_user_data . 405.Pp 406.Fn UI_get0_result 407returns a pointer to the result buffer associated with the information 408indexed by 409.Fa i . 410.Pp 411.Fn UI_process 412goes through the information given so far, does all the printing and 413prompting and returns the final status, which is -2 on out-of-band 414events (Interrupt, Cancel, ...), -1 on error, or 0 on success. 415.Pp 416.Fn UI_ctrl 417adds extra control for the application author. 418For now, it understands two commands: 419.Dv UI_CTRL_PRINT_ERRORS , 420which makes 421.Fn UI_process 422print the OpenSSL error stack as part of processing the 423.Fa ui , 424and 425.Dv UI_CTRL_IS_REDOABLE , 426which returns a flag saying if the used 427.Fa ui 428can be used again or not. 429.Pp 430.Fn UI_set_default_method 431changes the default UI method to the one given. 432This function is not thread-safe and should not be called at the 433same time as other OpenSSL functions. 434.Pp 435.Fn UI_get_default_method 436returns a pointer to the current default UI method. 437.Pp 438.Fn UI_get_method 439returns the UI method associated with a given 440.Fa ui . 441.Pp 442.Fn UI_set_method 443changes the UI method associated with a given 444.Fa ui . 445.Sh RETURN VALUES 446.Fn UI_new 447and 448.Fn UI_new_method 449return a valid 450.Vt UI 451structure or 452.Dv NULL 453if an error occurred. 454.Pp 455.Fn UI_add_input_string , 456.Fn UI_dup_input_string , 457.Fn UI_add_verify_string , 458.Fn UI_dup_verify_string , 459.Fn UI_add_input_boolean , 460.Fn UI_dup_input_boolean , 461.Fn UI_add_info_string , 462.Fn UI_dup_info_string , 463.Fn UI_add_error_string , 464and 465.Fn UI_dup_error_string 466return a positive number on success or a number 467less than or equal to zero otherwise. 468.Pp 469.Fn UI_construct_prompt 470and 471.Fn UI_get0_result 472return a string or 473.Dv NULL 474if an error occurred. 475.Pp 476.Fn UI_add_user_data 477and 478.Fn UI_get0_user_data 479return a pointer to the user data that was contained in 480.Fa ui 481before the call. 482In particular, 483.Dv NULL 484is a valid return value. 485.Pp 486.Fn UI_process 487returns 0 on success or a negative value on error. 488.Pp 489.Fn UI_ctrl 490returns a mask on success or \-1 on error. 491.Pp 492.Fn UI_get_default_method , 493.Fn UI_OpenSSL 494and 495.Fn UI_null 496always return a pointer to a valid 497.Vt UI_METHOD 498structure. 499.Pp 500.Fn UI_get_method 501and 502.Fn UI_set_method 503return a pointer to the 504.Vt UI_METHOD 505structure that is installed in 506.Fa ui 507after the call. 508The OpenSSL documentation says that they can fail and return 509.Dv NULL , 510but currently, this can only happen when and after 511.Fn UI_set_method 512is called with an explicit 513.Dv NULL 514argument. 515.Sh SEE ALSO 516.Xr crypto 3 , 517.Xr UI_create_method 3 , 518.Xr UI_get_string_type 3 519.Sh HISTORY 520These functions first appeared in OpenSSL 0.9.7 521and have been available since 522.Ox 3.2 . 523.Pp 524.Fn UI_null 525first appeared in OpenSSL 1.1.1 and has been available since 526.Ox 7.3 . 527.Sh AUTHORS 528.An Richard Levitte Aq Mt richard@levitte.org 529for the OpenSSL project. 530