merge new UI documentation from OpenSSL

5 files changed, 651 insertions, 13 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 20d04f2484..eec7ad39b0 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.118 2017/03/25 22:21:21 schwarze Exp $
+# $OpenBSD: Makefile,v 1.119 2017/03/26 00:06:10 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -193,6 +193,9 @@ MAN=	\
         SMIME_write_PKCS7.3 \
         SXNET_new.3 \
         TS_REQ_new.3 \
+        UI_UTIL_read_pw.3 \
+        UI_create_method.3 \
+        UI_get_string_type.3 \
         UI_new.3 \
         X509V3_get_d2i.3 \
         X509_ALGOR_dup.3 \
diff --git a/src/lib/libcrypto/man/UI_UTIL_read_pw.3 b/src/lib/libcrypto/man/UI_UTIL_read_pw.3
new file mode 100644
index 0000000000..b2d69c455e
--- /dev/null
+++ b/src/lib/libcrypto/man/UI_UTIL_read_pw.3
@@ -0,0 +1,95 @@
+.\"     $OpenBSD: UI_UTIL_read_pw.3,v 1.1 2017/03/26 00:06:10 schwarze Exp $
+.\"     OpenSSL UI_UTIL_read_pw.pod 23103a52 Jan 12 15:17:42 2017 +0100
+.\"
+.\" This file was written by Richard Levitte <levitte@openssl.org>.
+.\" Copyright (c) 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: March 26 2017 $
+.Dt UI_UTIL_READ_PW 3
+.Os
+.Sh NAME
+.Nm UI_UTIL_read_pw ,
+.Nm UI_UTIL_read_pw_string
+.Nd get a password from the user
+.Sh SYNOPSIS
+.In openssl/ui.h
+.Ft int
+.Fo UI_UTIL_read_pw_string
+.Fa "char *buf"
+.Fa "int length"
+.Fa "const char *prompt"
+.Fa "int verify"
+.Fc
+.Ft int
+.Fo UI_UTIL_read_pw
+.Fa "char *buf"
+.Fa "char *buff"
+.Fa "int size"
+.Fa "const char *prompt"
+.Fa "int verify"
+.Fc
+.Sh DESCRIPTION
+.Fn UI_UTIL_read_pw_string
+asks for a passphrase, using
+.Fa prompt
+as a prompt, and stores it in
+.Fa buf .
+The maximum allowed size is given with
+.Fa length ,
+including the terminating NUL byte.
+If
+.Fa verify
+is non-zero, the password will be verified as well.
+.Pp
+.Fn UI_UTIL_read_pw
+does the same as
+.Fn UI_UTIL_read_pw_string ,
+but takes an external buffer
+.Fa buff
+for the verification passphrase.
+.Sh SEE ALSO
+.Xr UI_new 3
diff --git a/src/lib/libcrypto/man/UI_create_method.3 b/src/lib/libcrypto/man/UI_create_method.3
new file mode 100644
index 0000000000..a29a4bb930
--- /dev/null
+++ b/src/lib/libcrypto/man/UI_create_method.3
@@ -0,0 +1,262 @@
+.\"     $OpenBSD: UI_create_method.3,v 1.1 2017/03/26 00:06:10 schwarze Exp $
+.\"     OpenSSL UI_create_method.pod 8e3d46e5 Mar 11 10:51:04 2017 +0100
+.\"
+.\" This file was written by Richard Levitte <levitte@openssl.org>.
+.\" Copyright (c) 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: March 26 2017 $
+.Dt UI_CREATE_METHOD 3
+.Os
+.Sh NAME
+.Nm UI_create_method ,
+.Nm UI_destroy_method ,
+.Nm UI_method_set_opener ,
+.Nm UI_method_set_writer ,
+.Nm UI_method_set_flusher ,
+.Nm UI_method_set_reader ,
+.Nm UI_method_set_closer ,
+.Nm UI_method_set_prompt_constructor ,
+.Nm UI_method_get_opener ,
+.Nm UI_method_get_writer ,
+.Nm UI_method_get_flusher ,
+.Nm UI_method_get_reader ,
+.Nm UI_method_get_closer ,
+.Nm UI_method_get_prompt_constructor
+.Nd user interface method creation and destruction
+.Sh SYNOPSIS
+.In openssl/ui.h
+.Ft UI_METHOD *
+.Fo UI_create_method
+.Fa "char *name"
+.Fc
+.Ft void
+.Fo UI_destroy_method
+.Fa "UI_METHOD *ui_method"
+.Fc
+.Ft int
+.Fo UI_method_set_opener
+.Fa "UI_METHOD *method"
+.Fa "int (*opener)(UI *ui)"
+.Fc
+.Ft int
+.Fo UI_method_set_writer
+.Fa "UI_METHOD *method"
+.Fa "int (*writer)(UI *ui, UI_STRING *uis)"
+.Fc
+.Ft int
+.Fo UI_method_set_flusher
+.Fa "UI_METHOD *method"
+.Fa "int (*flusher)(UI *ui)"
+.Fc
+.Ft int
+.Fo UI_method_set_reader
+.Fa "UI_METHOD *method"
+.Fa "int (*reader)(UI *ui, UI_STRING *uis)"
+.Fc
+.Ft int
+.Fo UI_method_set_closer
+.Fa "UI_METHOD *method"
+.Fa "int (*closer)(UI *ui)"
+.Fc
+.Ft int
+.Fo UI_method_set_prompt_constructor
+.Fa "UI_METHOD *method"
+.Fa "char *(*prompt_constructor)(UI *ui, const char *object_desc,\
+ const char *object_name)"
+.Fc
+.Ft int
+.Fo "(*UI_method_get_opener(const UI_METHOD *method))"
+.Fa "UI *";
+.Fc
+.Ft int
+.Fo "(*UI_method_get_writer(const UI_METHOD *method))"
+.Fa "UI *"
+.Fa "UI_STRING *"
+.Fc
+.Ft int
+.Fo "(*UI_method_get_flusher(const UI_METHOD *method))"
+.Fa "UI *"
+.Fc
+.Ft int
+.Fo "(*UI_method_get_reader(const UI_METHOD *method))"
+.Fa "UI *"
+.Fa "UI_STRING *"
+.Fc
+.Ft int
+.Fo "(*UI_method_get_closer(const UI_METHOD *method))"
+.Fa "UI *"
+.Fc
+.Ft char *
+.Fo "(*UI_method_get_prompt_constructor(UI_METHOD *method))"
+.Fa "UI *"
+.Fa "const char *"
+.Fa "const char *"
+.Fc
+.Sh DESCRIPTION
+A method contains a few functions that implement the low level of the
+User Interface.
+These functions are:
+.Bl -tag -width Ds
+.It an opener
+This function takes a reference to a UI and starts a session, for
+example by opening a channel to a tty, or by creating a dialog box.
+.It a writer
+This function takes a reference to a UI and a UI String, and writes the
+string where appropriate, maybe to the tty, maybe added as a field label
+in a dialog box.
+Note that this gets fed all strings associated with a UI, one after the
+other, so care must be taken which ones it actually uses.
+.It a flusher
+This function takes a reference to a UI, and flushes everything that has
+been output so far.
+For example, if the method builds up a dialog box, this can be used to
+actually display it and accepting input ended with a pressed button.
+.It a reader
+This function takes a reference to a UI and a UI string and reads off
+the given prompt, maybe from the tty, maybe from a field in a dialog
+box.
+Note that this gets fed all strings associated with a UI, one after the
+other, so care must be taken which ones it actually uses.
+.It a closer
+This function takes a reference to a UI, and closes the session, maybe
+by closing the channel to the tty, maybe by destroying a dialog box.
+.El
+.Pp
+All of these functions are expected to return 0 on error, 1 on success,
+or -1 on out-off-band events, for example if some prompting has been
+cancelled (by pressing Ctrl-C, for example).
+Only the flusher or the reader are expected to return -1. If returned by
+another of the functions, it's treated as if 0 was returned.
+.Pp
+Regarding the writer and the reader, don't assume the former should only
+write and don't assume the latter should only read.
+This depends on the needs of the method.
+.Pp
+For example, a typical tty reader wouldn't write the prompts in the
+write, but would rather do so in the reader, because of the sequential
+nature of prompting on a tty.
+This is how the
+.Xr UI_OpenSSL 3
+method does it.
+.Pp
+In contrast, a method that builds up a dialog box would add all prompt
+text in the writer, have all input read in the flusher and store the
+results in some temporary buffer, and finally have the reader just fetch
+those results.
+.Pp
+The central function that uses these method functions is
+.Xr UI_process 3 ,
+and it does it in five steps:
+.Bl -enum
+.It
+Open the session using the opener function if that one is defined.
+If an error occurs, jump to 5.
+.It
+For every UI String associated with the UI, call the writer function if
+that one is defined.
+If an error occurs, jump to 5.
+.It
+Flush everything using the flusher function if that one is defined.
+If an error occurs, jump to 5.
+.It
+For every UI String associated with the UI, call the reader function if
+that one is defined.
+If an error occurs, jump to 5.
+.It
+Close the session using the closer function if that one is defined.
+.El
+.Pp
+.Fn UI_create_method
+creates a new UI method with a given
+.Fa name .
+.Pp
+.Fn UI_destroy_method
+destroys the given
+.Fa ui_method .
+.Pp
+.Fn UI_method_set_opener ,
+.Fn UI_method_set_writer ,
+.Fn UI_method_set_flusher ,
+.Fn UI_method_set_reader
+and
+.Fn UI_method_set_closer
+set one of the five main methods to the given function pointer.
+.Pp
+.Fn UI_method_set_prompt_constructor
+sets the prompt constructor, see
+.Xr UI_construct_prompt 3 .
+.Sh RETURN VALUES
+.Fn UI_create_method
+returns a
+.Vt UI_METHOD
+pointer on success or
+.Dv NULL
+on error.
+.Pp
+.Fn UI_method_set_opener ,
+.Fn UI_method_set_writer ,
+.Fn UI_method_set_flusher ,
+.Fn UI_method_set_reader ,
+.Fn UI_method_set_closer ,
+and
+.Fn UI_method_set_prompt_constructor
+return 0 on success or -1 if the given method is
+.Dv NULL .
+.Pp
+.Fn UI_method_get_opener ,
+.Fn UI_method_get_writer ,
+.Fn UI_method_get_flusher ,
+.Fn UI_method_get_reader ,
+.Fn UI_method_get_closer ,
+and
+.Fn UI_method_get_prompt_constructor
+return the requested function pointer if it is set in the method,
+or otherwise
+.Dv NULL .
+.Sh SEE ALSO
+.Xr UI_get_string_type 3 ,
+.Xr UI_new 3
diff --git a/src/lib/libcrypto/man/UI_get_string_type.3 b/src/lib/libcrypto/man/UI_get_string_type.3
new file mode 100644
index 0000000000..d7cceadc75
--- /dev/null
+++ b/src/lib/libcrypto/man/UI_get_string_type.3
@@ -0,0 +1,277 @@
+.\"     $OpenBSD: UI_get_string_type.3,v 1.1 2017/03/26 00:06:10 schwarze Exp $
+.\"     OpenSSL UI_STRING.pod 2ca2e917 Mar 20 16:25:22 2017 -0400
+.\"
+.\" This file was written by Richard Levitte <levitte@openssl.org>
+.\" Copyright (c) 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: March 26 2017 $
+.Dt UI_GET_STRING_TYPE 3
+.Os
+.Sh NAME
+.Nm UI_get_string_type ,
+.Nm UI_get_input_flags ,
+.Nm UI_get0_output_string ,
+.Nm UI_get0_action_string ,
+.Nm UI_get0_result_string ,
+.Nm UI_get0_test_string ,
+.Nm UI_get_result_minsize ,
+.Nm UI_get_result_maxsize ,
+.Nm UI_set_result
+.Nd OpenSSL user interface string parsing
+.Sh SYNOPSIS
+.In openssl/ui.h
+.Bd -literal
+enum UI_string_types {
+        UIT_NONE = 0,
+        UIT_PROMPT,     /* Prompt for a string */
+        UIT_VERIFY,     /* Prompt for a string and verify */
+        UIT_BOOLEAN,    /* Prompt for a yes/no response */
+        UIT_INFO,       /* Send info to the user */
+        UIT_ERROR       /* Send an error message to the user */
+};
+.Ed
+.Pp
+.Ft enum UI_string_types
+.Fo UI_get_string_type
+.Fa "UI_STRING *uis"
+.Fc
+.Ft int
+.Fo UI_get_input_flags
+.Fa "UI_STRING *uis"
+.Fc
+.Ft const char *
+.Fo UI_get0_output_string
+.Fa "UI_STRING *uis"
+.Fc
+.Ft const char *
+.Fo UI_get0_action_string
+.Fa "UI_STRING *uis"
+.Fc
+.Ft const char *
+.Fo UI_get0_result_string
+.Fa "UI_STRING *uis"
+.Fc
+.Ft const char *
+.Fo UI_get0_test_string
+.Fa "UI_STRING *uis"
+.Fc
+.Ft int
+.Fo UI_get_result_minsize
+.Fa "UI_STRING *uis"
+.Fc
+.Ft int
+.Fo UI_get_result_maxsize
+.Fa "UI_STRING *uis"
+.Fc
+.Ft int
+.Fo UI_set_result
+.Fa "UI *ui"
+.Fa "UI_STRING *uis"
+.Fa "const char *result"
+.Fc
+.Sh DESCRIPTION
+A
+.Vt UI_STRING
+gets created internally and added to a
+.Vt UI
+object whenever one of the functions
+.Xr UI_add_input_string 3 ,
+.Xr UI_dup_input_string 3 ,
+.Xr UI_add_verify_string 3 ,
+.Xr UI_dup_verify_string 3 ,
+.Xr UI_add_input_boolean 3 ,
+.Xr UI_dup_input_boolean 3 ,
+.Xr UI_add_info_string 3 ,
+.Xr UI_dup_info_string 3 ,
+.Xr UI_add_error_string 3
+or
+.Xr UI_dup_error_string 3
+is called.
+For a
+.Vt UI_METHOD
+user, there's no need to know more.
+For a
+.Vt UI_METHOD
+creator, it is of interest to fetch text from these
+.Vt UI_STRING
+objects as well as adding results to some of them.
+.Pp
+.Fn UI_get_string_type
+is used to retrieve the type of the given
+.Vt UI_STRING .
+.Pp
+.Fn UI_get_input_flags
+is used to retrieve the flags associated with the given
+.Vt UI_STRING .
+.Pp
+.Fn UI_get0_output_string
+is used to retrieve the actual string to output (prompt, info, error, ...).
+.Pp
+.Fn UI_get0_action_string
+is used to retrieve the action description associated with a
+.Dv UIT_BOOLEAN
+type
+.Vt UI_STRING .
+See
+.Xr UI_add_input_boolean 3 .
+.Pp
+.Fn UI_get0_result_string
+is used to retrieve the result of a prompt.
+This is only useful for
+.Dv UIT_PROMPT
+and
+.Dv UIT_VERIFY
+type strings.
+.Pp
+.Fn UI_get0_test_string
+is used to retrieve the string to compare the prompt result with.
+This is only useful for
+.Dv UIT_VERIFY
+type strings.
+.Pp
+.Fn UI_get_result_minsize
+and
+.Fn UI_get_result_maxsize
+are used to retrieve the minimum and maximum required size of the
+result.
+This is only useful for
+.Dv UIT_PROMPT
+and
+.Dv UIT_VERIFY
+type strings.
+.Pp
+.Fn UI_set_result
+is used to set the result value of a prompt.
+For
+.Sy UIT_PROMPT
+and
+.Sy UIT_VERIFY
+type UI strings, this sets the result retrievable with
+.Fn UI_get0_result_string
+by copying the contents of
+.Fa result
+if its length fits the minimum and maximum size requirements.
+For
+.Dv UIT_BOOLEAN
+type UI strings, this sets the first character of the result retrievable
+with
+.Fn UI_get0_result_string
+to the first of the
+.Fa ok_chars
+given with
+.Xr UI_add_input_boolean 3
+or
+.Xr UI_dup_input_boolean 3
+if the
+.Fa result
+matched any of them, or the first of the
+.Fa cancel_chars
+if the
+.Fa result
+matched any of them, otherwise it's set to the NUL char.
+See
+.Xr UI_add_input_boolean 3
+for more information on
+.Fa ok_chars
+and
+.Fa cancel_chars .
+.Sh RETURN VALUES
+.Fn UI_get_string_type
+returns the UI string type.
+.Pp
+.Fn UI_get_input_flags
+returns the UI string flags.
+.Pp
+.Fn UI_get0_output_string
+returns the UI string output string.
+.Pp
+.Fn UI_get0_action_string
+returns the UI string action description string for
+.Dv UIT_BOOLEAN
+type UI strings, or
+.Dv NULL
+for any other type.
+.Pp
+.Fn UI_get0_result_string
+returns the UI string action description string for
+.Dv UIT_PROMPT
+and
+.Dv UIT_VERIFY
+type UI strings, or
+.Dv NULL
+for any other type.
+.Pp
+.Fn UI_get0_test_string
+returns the UI string action description string for
+.Dv UIT_VERIFY
+type UI strings, or
+.Dv NULL
+for any other type.
+.Pp
+.Fn UI_get_result_minsize
+returns the minimum allowed result size for the UI string for
+.Dv UIT_PROMPT
+and
+.Dv UIT_VERIFY
+type strings, or -1 for any other type.
+.Pp
+.Fn UI_get_result_maxsize
+returns the minimum allowed result size for the UI string for for
+.Dv UIT_PROMPT
+and
+.Dv UIT_VERIFY
+type strings, or -1 for any other type.
+.Pp
+.Fn UI_set_result
+returns 0 on success or when the UI string is of any type other than
+.Dv UIT_PROMPT ,
+.Dv UIT_VERIFY ,
+or
+.Dv UIT_BOOLEAN ,
+or -1 on error.
+.Sh SEE ALSO
+.Xr UI_new 3
diff --git a/src/lib/libcrypto/man/UI_new.3 b/src/lib/libcrypto/man/UI_new.3
index 0974b00b02..2b0ce5b557 100644
--- a/src/lib/libcrypto/man/UI_new.3
+++ b/src/lib/libcrypto/man/UI_new.3
@@ -1,8 +1,9 @@
-.\"     $OpenBSD: UI_new.3,v 1.5 2017/01/06 18:46:38 schwarze Exp $
-.\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
+.\"     $OpenBSD: UI_new.3,v 1.6 2017/03/26 00:06:10 schwarze Exp $
+.\"     OpenSSL UI_new.pod 5469600e Mar 11 00:51:53 2017 +0100
+.\"     OpenSSL UI_new.pod 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file was written by Richard Levitte <levitte@openssl.org>.
-.\" Copyright (c) 2001, 2016 The OpenSSL Project.  All rights reserved.
+.\" 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
@@ -48,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: January 6 2017 $
+.Dd $Mdocdate: March 26 2017 $
 .Dt UI_NEW 3
 .Os
 .Sh NAME
@@ -228,12 +229,8 @@
 .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 the functions
-.Fn UI_create_method
-and
-.Fn UI_method_set_*
-declared in
-.In openssl/ui.h ) ,
+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
@@ -402,7 +399,8 @@ indexed by
 .Pp
 .Fn UI_process
 goes through the information given so far, does all the printing and
-prompting and returns.
+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.
@@ -432,7 +430,10 @@ returns the UI method associated with a given
 changes the UI method associated with a given
 .Fa ui .
 .Sh SEE ALSO
-.Xr des_read_pw 3
+.Xr des_read_pw 3 ,
+.Xr UI_create_method 3 ,
+.Xr UI_get_string_type 3 ,
+.Xr UI_UTIL_read_pw 3
 .Sh HISTORY
 The UI section was first introduced in OpenSSL 0.9.7.
 .Sh AUTHORS