Document the deprecated functions EVP_set_pw_prompt(3) and

EVP_get_pw_prompt(3) because some software out there still uses them.

While here, also improve the description of EVP_read_pw_string(3).

Delete documentation for des_read_pw(3) and des_read_pw_string(3).
They couldn't be used in LibreSSL since at least 2016 because they
were never in Symbols.list, and in 2022, jsing@ also removed them
from <openssl/ui_compat.h>.

Delete the misleading AUTHORS section.  Richard Levitte did not
write the original implementation of these functions, and the
compatibility wrapper around the UI_process(3) API that he did
write is not notable enough to be mentioned so prominently.

1 files changed, 86 insertions, 71 deletions

diff --git a/src/lib/libcrypto/man/des_read_pw.3 b/src/lib/libcrypto/man/des_read_pw.3
index 30ae099dc6..41f8553de1 100644
--- a/src/lib/libcrypto/man/des_read_pw.3
+++ b/src/lib/libcrypto/man/des_read_pw.3
@@ -1,10 +1,26 @@
-.\"     $OpenBSD: des_read_pw.3,v 1.10 2020/06/19 17:17:13 schwarze Exp $
-.\"     OpenSSL doc/crypto/ui_compat.pod May 14 11:28:00 2006 +0000
-.\"     OpenSSL doc/crypto/des.pod 2a9aca32 Oct 25 08:44:10 2001 +0000
+.\" $OpenBSD: des_read_pw.3,v 1.11 2023/09/10 13:58:46 schwarze Exp $
+.\" full merge up to: OpenSSL doc/crypto/des.pod
+.\" 53934822 Jun 9 16:39:19 2016 -0400
 .\"
-.\" This file was written by Ulf Moeller <ulf@openssl.org> and
-.\" Richard Levitte <levitte@openssl.org>.
-.\" Copyright (c) 2000, 2001 The OpenSSL Project.  All rights reserved.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Ulf Moeller <ulf@openssl.org>.
+.\" Copyright (c) 2000 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
@@ -50,32 +66,16 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 19 2020 $
+.Dd $Mdocdate: September 10 2023 $
 .Dt DES_READ_PW 3
 .Os
 .Sh NAME
-.Nm des_read_pw ,
-.Nm des_read_pw_string ,
 .Nm EVP_read_pw_string ,
-.Nm EVP_read_pw_string_min
+.Nm EVP_read_pw_string_min ,
+.Nm EVP_set_pw_prompt ,
+.Nm EVP_get_pw_prompt
 .Nd compatibility user interface functions
 .Sh SYNOPSIS
-.In openssl/ui_compat.h
-.Ft int
-.Fo des_read_pw
-.Fa "char *buf"
-.Fa "char *buff"
-.Fa "int length"
-.Fa "const char *prompt"
-.Fa "int verify"
-.Fc
-.Ft int
-.Fo des_read_pw_string
-.Fa "char *buf"
-.Fa "int length"
-.Fa "const char *prompt"
-.Fa "int verify"
-.Fc
 .In openssl/evp.h
 .Ft int
 .Fo EVP_read_pw_string
@@ -92,73 +92,86 @@
 .Fa "const char *prompt"
 .Fa "int verify"
 .Fc
+.Ft void
+.Fo EVP_set_pw_prompt
+.Fa "const char *default_prompt"
+.Fc
+.Ft char *
+.Fn EVP_get_pw_prompt void
 .Sh DESCRIPTION
 These functions are deprecated.
 Use
 .Xr UI_UTIL_read_pw 3
 instead.
 .Pp
-The DES library contained a few routines to prompt for passwords.
-These aren't necessarily dependent on DES, and have therefore become
-part of the UI compatibility library.
-.Pp
-.Fn des_read_pw
-writes the string specified by
+.Fn EVP_read_pw_string
+writes the
 .Fa prompt
-to standard output, turns echo off, and reads an input string from the
-terminal.
+to
+.Pa /dev/tty ,
+or, if that could not be opened, to standard output, turns echo off,
+and reads an input string from
+.Pa /dev/tty ,
+or, if that could not be opened, from standard input.
 The string is returned in
 .Fa buf ,
 which must have space for at least
 .Fa length
 bytes.
+If the
+.Fa length
+argument exceeds
+.Dv BUFSIZ ,
+.Dv BUFSIZ
+is used instead.
 If
 .Fa verify
 is set, the user is asked for the password twice and unless the two
 copies match, an error is returned.
-The second password is stored in
-.Fa buff ,
-which must therefore also be at least
-.Fa length
-bytes.
 .Pp
-.Fn des_read_pw_string
-is a variant of
-.Fn des_read_pw
-that provides a buffer if
-.Fa verify
-is set.
-It is available in the MIT Kerberos library as well.
-If
-.Fa length
-exceeds
-.Dv BUFSIZ ,
-.Fn des_read_pw_string
-uses
-.Dv BUFSIZ .
-.Pp
-.Fn EVP_read_pw_string
-and
-.Fn EVP_read_pw_string_min
-are functionally similar to
-.Fn des_read_pw_string .
 .Fn EVP_read_pw_string_min
 additionally checks that the password is at least
 .Fa min_length
 bytes long.
+.Pp
+.Fn EVP_set_pw_prompt
+sets a default prompt to a copy of
+.Fa default_prompt ,
+or clears the default prompt if the
+.Fa default_prompt
+argument is
+.Dv NULL
+or an empty string.
+If the
+.Fa default_prompt
+argument is longer than 79 bytes,
+the copy is silently truncated to a string length of 79 bytes.
+.Pp
+As long as a default prompt is set,
+.Fn EVP_read_pw_string
+and
+.Fn EVP_read_pw_string_min
+can be called with a
+.Fa prompt
+argument of
+.Dv NULL ,
+in which case the default prompt is used instead.
 .Sh RETURN VALUES
-These functions return 0 on success and a negative value on failure.
+.Fn EVP_read_pw_string
+and
+.Fn EVP_read_pw_string_min
+return 0 on success or a negative value on failure.
 .Pp
-They return -1 if
+They return \-1 if
 .Fa length
 is less than or equal to zero or on memory allocation failure.
-They return -1 or -2 if the internal call to
+They return \-1 or \-2 if the internal call to
 .Xr UI_process 3
 fails.
 .Pp
 In addition,
 .Fa EVP_read_pw_string_min
-returns -1 if
+returns \-1 if
 .Fa min_length
 is negative, if
 .Fa length
@@ -166,16 +179,21 @@ is less than or equal to
 .Fa min_length ,
 or if the user entered a password shorter than
 .Fa min_length .
+.Pp
+.Fn EVP_get_pw_prompt
+returns an internal pointer to static memory containing the default prompt, or
+.Dv NULL
+if no default prompt is set.
 .Sh SEE ALSO
 .Xr UI_new 3 ,
 .Xr UI_UTIL_read_pw 3
 .Sh HISTORY
-.Fn des_read_pw_string
-appeared in SSLeay 0.4 or earlier.
 .Fn EVP_read_pw_string
-first appeared in SSLeay 0.5.1.
-.Fn des_read_pw
-first appeared in SSLeay 0.8.0.
+first appeared in SSLeay 0.5.1 and
+.Fn EVP_set_pw_prompt
+and
+.Fn EVP_get_pw_prompt
+in SSLeay 0.6.0.
 These functions have been available since
 .Ox 2.4 .
 .Pp
@@ -183,6 +201,3 @@ These functions have been available since
 first appeared in OpenSSL 1.0.0
 and has been available since
 .Ox 4.9 .
-.Sh AUTHORS
-.An Richard Levitte Aq Mt richard@levitte.org
-for the OpenSSL project.