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