1 files changed, 384 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/ui_new.3 b/src/lib/libcrypto/man/ui_new.3
new file mode 100644
index 0000000000..d841c212d8
--- /dev/null
+++ b/src/lib/libcrypto/man/ui_new.3
@@ -0,0 +1,384 @@
+.Dd $Mdocdate: November 12 2015 $
+.Dt UI_NEW 3
+.Os
+.Sh NAME
+.Nm UI_new ,
+.Nm UI_new_method ,
+.Nm UI_free ,
+.Nm UI_add_input_string ,
+.Nm UI_dup_input_string ,
+.Nm UI_add_verify_string ,
+.Nm UI_dup_verify_string ,
+.Nm UI_add_input_boolean ,
+.Nm UI_dup_input_boolean ,
+.Nm UI_add_info_string ,
+.Nm UI_dup_info_string ,
+.Nm UI_add_error_string ,
+.Nm UI_dup_error_string ,
+.Nm UI_construct_prompt ,
+.Nm UI_add_user_data ,
+.Nm UI_get0_user_data ,
+.Nm UI_get0_result ,
+.Nm UI_process ,
+.Nm UI_ctrl ,
+.Nm UI_set_default_method ,
+.Nm UI_get_default_method ,
+.Nm UI_get_method ,
+.Nm UI_set_method ,
+.Nm UI_OpenSSL ,
+.Nm ERR_load_UI_strings
+.Nd New User Interface
+.Sh SYNOPSIS
+.In openssl/ui.h
+.Fd typedef struct ui_st UI;
+.Fd typedef struct ui_method_st UI_METHOD;
+.Ft UI *
+.Fn UI_new void
+.Ft UI *
+.Fo UI_new_method
+.Fa "const UI_METHOD *method"
+.Fc
+.Ft void
+.Fo UI_free
+.Fa "UI *ui"
+.Fc
+.Ft int
+.Fo UI_add_input_string
+.Fa "UI *ui"
+.Fa "const char *prompt"
+.Fa "int flags"
+.Fa "char *result_buf"
+.Fa "int minsize"
+.Fa "int maxsize"
+.Fc
+.Ft int
+.Fo UI_dup_input_string
+.Fa "UI *ui"
+.Fa "const char *prompt"
+.Fa "int flags"
+.Fa "char *result_buf"
+.Fa "int minsize"
+.Fa "int maxsize"
+.Fc
+.Ft int
+.Fo UI_add_verify_string
+.Fa "UI *ui"
+.Fa "const char *prompt"
+.Fa "int flags"
+.Fa "char *result_buf"
+.Fa "int minsize"
+.Fa "int maxsize"
+.Fa "const char *test_buf"
+.Fc
+.Ft int
+.Fo UI_dup_verify_string
+.Fa "UI *ui"
+.Fa "const char *prompt"
+.Fa "int flags"
+.Fa "char *result_buf"
+.Fa "int minsize"
+.Fa "int maxsize"
+.Fa "const char *test_buf"
+.Fc
+.Ft int
+.Fo UI_add_input_boolean
+.Fa "UI *ui"
+.Fa "const char *prompt"
+.Fa "const char *action_desc"
+.Fa "const char *ok_chars"
+.Fa "const char *cancel_chars"
+.Fa "int flags"
+.Fa "char *result_buf"
+.Fc
+.Ft int
+.Fo UI_dup_input_boolean
+.Fa "UI *ui"
+.Fa "const char *prompt"
+.Fa "const char *action_desc"
+.Fa "const char *ok_chars"
+.Fa "const char *cancel_chars"
+.Fa "int flags"
+.Fa "char *result_buf"
+.Fc
+.Ft int
+.Fo UI_add_info_string
+.Fa "UI *ui"
+.Fa "const char *text"
+.Fc
+.Ft int
+.Fo UI_dup_info_string
+.Fa "UI *ui"
+.Fa "const char *text"
+.Fc
+.Ft int
+.Fo UI_add_error_string
+.Fa "UI *ui"
+.Fa "const char *text"
+.Fc
+.Ft int
+.Fo UI_dup_error_string
+.Fa "UI *ui"
+.Fa "const char *text"
+.Fc
+.Fd /* These are the possible flags.  They can be OR'ed together. */
+.Fd #define UI_INPUT_FLAG_ECHO          0x01
+.Fd #define UI_INPUT_FLAG_DEFAULT_PWD   0x02
+.Ft char *
+.Fo UI_construct_prompt
+.Fa "UI *ui_method"
+.Fa "const char *object_desc"
+.Fa "const char *object_name"
+.Fc
+.Ft void *
+.Fo UI_add_user_data
+.Fa "UI *ui"
+.Fa "void *user_data"
+.Fc
+.Ft void *
+.Fo UI_get0_user_data
+.Fa "UI *ui"
+.Fc
+.Ft const char *
+.Fo UI_get0_result
+.Fa "UI *ui"
+.Fa "int i"
+.Fc
+.Ft int
+.Fo UI_process
+.Fa "UI *ui"
+.Fc
+.Ft int
+.Fo UI_ctrl
+.Fa "UI *ui"
+.Fa "int cmd"
+.Fa "long i"
+.Fa "void *p"
+.Fa "void (*f)()"
+.Fc
+.Fd #define UI_CTRL_PRINT_ERRORS                1
+.Fd #define UI_CTRL_IS_REDOABLE         2
+.Ft void
+.Fo UI_set_default_method
+.Fa "const UI_METHOD *meth"
+.Fc
+.Ft const UI_METHOD *
+.Fo UI_get_default_method
+.Fa void
+.Fc
+.Ft const UI_METHOD *
+.Fo UI_get_method
+.Fa "UI *ui"
+.Fc
+.Ft const UI_METHOD *
+.Fo UI_set_method
+.Fa "UI *ui"
+.Fa "const UI_METHOD *meth"
+.Fc
+.Ft UI_METHOD *
+.Fo UI_OpenSSL
+.Fa void
+.Fc
+.Sh DESCRIPTION
+UI stands for User Interface, and is general purpose set of routines
+to prompt the user for text-based information.
+Through user-written methods (see
+.Xr ui_create 3 Ns ),
+prompting can be done in any way imaginable, be it plain text prompting,
+through dialog boxes or from a cell phone.
+.Pp
+All the functions work through a context of the type
+.Vt UI .
+This context contains all the information needed to prompt correctly
+as well as a reference to a
+.Vt UI_METHOD ,
+which is an ordered vector of functions that carry out the actual
+prompting.
+.Pp
+The first thing to do is to create a
+.Vt UI
+with
+.Fn UI_new
+or
+.Fn UI_new_method ,
+then add information to it with the
+.Fn UI_add_*
+or
+.Fn UI_dup_*
+functions.
+Also, user-defined random data can be passed down to the underlying
+method through calls to
+.Fn UI_add_user_data .
+The default UI method doesn't care about these data, but other methods
+might.
+Finally, use
+.Fn UI_process
+to actually perform the prompting and
+.Fn UI_get0_result
+to find the result to the prompt.
+.Pp
+A
+.Vt UI
+can contain more than one prompt, which are performed in the given
+sequence.
+Each prompt gets an index number which is returned by the
+.Fn UI_add_*
+and
+.Fn UI_dup_*
+functions, and has to be used to get the corresponding result with
+.Fn UI_get0_result .
+.Pp
+The functions are as follows:
+.Pp
+.Fn UI_new
+creates a new
+.Vt UI
+using the default UI method.
+When done with this UI, it should be freed using
+.Fn UI_free .
+.Pp
+.Fn UI_new_method
+creates a new
+.Vt UI
+using the given UI method.
+When done with this UI, it should be freed using
+.Fn UI_free .
+.Pp
+.Fn UI_OpenSSL
+returns the built-in UI method (note: not the default one, since
+the default can be changed.
+See further on).
+This method is the most machine/OS dependent part of OpenSSL and
+normally generates the most problems when porting.
+.Pp
+.Fn UI_free
+removes
+.Fa ui
+from memory, along with all other pieces of memory that are connected
+to it, like duplicated input strings, results and others.
+.Pp
+.Fn UI_add_input_string
+and
+.Fn UI_add_verify_string
+add a prompt to
+.Fa ui ,
+as well as flags and a result buffer and the desired minimum and
+maximum sizes of the result.
+The given information is used to prompt for information, for example
+a password, and to verify a password (i.e. having the user enter
+it twice and check that the same string was entered twice).
+.Fn UI_add_verify_string
+takes and extra argument that should be a pointer to the result buffer
+of the input string that it's supposed to verify, or verification will
+fail.
+.Pp
+.Fn UI_add_input_boolean
+adds a prompt to
+.Fa ui
+that's supposed to be answered in a boolean way, with a single
+character for yes and a different character for no.
+A set of characters that can be used to cancel the prompt is given as
+well.
+The prompt itself is really divided in two, one part being the
+descriptive text (given through the
+.Fa prompt
+argument) and one describing the possible answers (given through the
+.Fa action_desc
+argument).
+.Pp
+.Fn UI_add_info_string
+and
+.Fn UI_add_error_string
+add strings that are shown at the same time as the prompt for extra
+information or to show an error string.
+The difference between the two is only conceptual.
+With the builtin method, there's no technical difference between them.
+Other methods may make a difference between them, however.
+.Pp
+The flags currently supported are
+.Dv UI_INPUT_FLAG_ECHO,
+which is relevant for
+.Fn UI_add_input_string
+and will have the users response be echoed (when prompting for a
+password, this flag should obviously not be used), and
+.Dv UI_INPUT_FLAG_DEFAULT_PWD ,
+which means that a default password of some sort will be used
+(completely depending on the application and the UI method).
+.Pp
+.Fn UI_dup_input_string ,
+.Fn UI_dup_verify_string ,
+.Fn UI_dup_input_boolean ,
+.Fn UI_dup_info_string ,
+and
+.Fn UI_dup_error_string
+are basically the same as their
+.Fn UI_add_*
+counterparts, except that they make their own copies of all strings.
+.Pp
+.Fn UI_construct_prompt
+is a helper function that can be used to create a prompt from two pieces
+of information: an description and a name.
+The default constructor (if there is none provided by the method used)
+creates a string "Enter
+.Em description
+for
+.Em name Ns :".
+With the description "pass phrase" and the file name "foo.key", that
+becomes "Enter pass phrase for foo.key:". Other methods may create
+whatever string and may include encodings that will be processed by the
+other method functions.
+.Pp
+.Fn UI_add_user_data
+adds a piece of memory for the method to use at any time.
+The builtin UI method doesn't care about this info.
+Note that several calls to this function doesn't add data, it replaces
+the previous blob with the one given as argument.
+.Pp
+.Fn UI_get0_user_data
+retrieves the data that has last been given to the
+.Fa ui
+with
+.Fn UI_add_user_data .
+.Pp
+.Fn UI_get0_result
+returns a pointer to the result buffer associated with the information
+indexed by
+.Fa i .
+.Pp
+.Fn UI_process
+goes through the information given so far, does all the printing and
+prompting and returns.
+.Pp
+.Fn UI_ctrl
+adds extra control for the application author.
+For now, it understands two commands:
+.Dv UI_CTRL_PRINT_ERRORS ,
+which makes
+.Fn UI_process
+print the OpenSSL error stack as part of processing the
+.Fa ui ,
+and
+.Dv UI_CTRL_IS_REDOABLE ,
+which returns a flag saying if the used
+.Fa ui
+can be used again or not.
+.Pp
+.Fn UI_set_default_method
+changes the default UI method to the one given.
+.Pp
+.Fn UI_get_default_method
+returns a pointer to the current default UI method.
+.Pp
+.Fn UI_get_method
+returns the UI method associated with a given
+.Fa ui .
+.Pp
+.Fn UI_set_method
+changes the UI method associated with a given
+.Fa ui .
+.Sh SEE ALSO
+.Xr des_read_pw 3
+.Sh HISTORY
+The UI section was first introduced in OpenSSL 0.9.7.
+.Sh AUTHORS
+.An Richard Levitte Aq Mt richard@levitte.org
+for the OpenSSL project.