docs: Added All OpenBSD Manuals

1 files changed, 530 insertions, 0 deletions

diff --git a/static/openbsd/man3/UI_new.3 b/static/openbsd/man3/UI_new.3
new file mode 100644
index 00000000..853219aa
--- /dev/null
+++ b/static/openbsd/man3/UI_new.3
@@ -0,0 +1,530 @@
+.\" $OpenBSD: UI_new.3,v 1.14 2025/06/08 22:40:30 schwarze Exp $
+.\" full merge up to: OpenSSL 78b19e90 Jan 11 00:12:01 2017 +0100
+.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
+.\"
+.\" This file was written by Richard Levitte <levitte@openssl.org>.
+.\" Copyright (c) 2001, 2016, 2017 The OpenSSL Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: June 8 2025 $
+.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 UI_null
+.Nd New User Interface
+.Sh SYNOPSIS
+.Lb libcrypto
+.In openssl/ui.h
+.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 const UI_METHOD *
+.Fo UI_OpenSSL
+.Fa void
+.Fc
+.Ft const UI_METHOD *
+.Fo UI_null
+.Fa void
+.Fc
+.Sh DESCRIPTION
+UI stands for User Interface, and is a general purpose set of routines
+to prompt the user for text-based information.
+Through user-written methods (see
+.Xr UI_create_method 3 ) ,
+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 necessarily 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_null
+returns a UI method that does nothing.
+Its use is to avoid getting internal defaults for passed
+.Vt UI_METHOD
+pointers.
+.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.
+If
+.Fa ui
+is a
+.Dv NULL
+pointer, no action occurs.
+.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, not counting the final NUL character.
+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 an 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: a 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 user data pointer 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 -
+the previous blob is replaced 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 the final status, which is -2 on out-of-band
+events (Interrupt, Cancel, ...), -1 on error, or 0 on success.
+.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.
+This function is not thread-safe and should not be called at the
+same time as other OpenSSL functions.
+.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 RETURN VALUES
+.Fn UI_new
+and
+.Fn UI_new_method
+return a valid
+.Vt UI
+structure or
+.Dv NULL
+if an error occurred.
+.Pp
+.Fn UI_add_input_string ,
+.Fn UI_dup_input_string ,
+.Fn UI_add_verify_string ,
+.Fn UI_dup_verify_string ,
+.Fn UI_add_input_boolean ,
+.Fn UI_dup_input_boolean ,
+.Fn UI_add_info_string ,
+.Fn UI_dup_info_string ,
+.Fn UI_add_error_string ,
+and
+.Fn UI_dup_error_string
+return a positive number on success or a number
+less than or equal to zero otherwise.
+.Pp
+.Fn UI_construct_prompt
+and
+.Fn UI_get0_result
+return a string or
+.Dv NULL
+if an error occurred.
+.Pp
+.Fn UI_add_user_data
+and
+.Fn UI_get0_user_data
+return a pointer to the user data that was contained in
+.Fa ui
+before the call.
+In particular,
+.Dv NULL
+is a valid return value.
+.Pp
+.Fn UI_process
+returns 0 on success or a negative value on error.
+.Pp
+.Fn UI_ctrl
+returns a mask on success or \-1 on error.
+.Pp
+.Fn UI_get_default_method ,
+.Fn UI_OpenSSL
+and
+.Fn UI_null
+always return a pointer to a valid
+.Vt UI_METHOD
+structure.
+.Pp
+.Fn UI_get_method
+and
+.Fn UI_set_method
+return a pointer to the
+.Vt UI_METHOD
+structure that is installed in
+.Fa ui
+after the call.
+The OpenSSL documentation says that they can fail and return
+.Dv NULL ,
+but currently, this can only happen when and after
+.Fn UI_set_method
+is called with an explicit
+.Dv NULL
+argument.
+.Sh SEE ALSO
+.Xr crypto 3 ,
+.Xr UI_create_method 3 ,
+.Xr UI_get_string_type 3
+.Sh HISTORY
+These functions first appeared in  OpenSSL 0.9.7
+and have been available since
+.Ox 3.2 .
+.Pp
+.Fn UI_null
+first appeared in OpenSSL 1.1.1 and has been available since
+.Ox 7.3 .
+.Sh AUTHORS
+.An Richard Levitte Aq Mt richard@levitte.org
+for the OpenSSL project.