Document EVP_read_pw_string_min(3)

Add detailed information on the return values of all the functions
in this page and remove the previous incorrect information.

tweaks & ok schwarze

1 files changed, 44 insertions, 6 deletions

diff --git a/lib/libcrypto/man/des_read_pw.3 b/lib/libcrypto/man/des_read_pw.3
index 8c63a65fd2f..55d36ef721e 100644
--- a/lib/libcrypto/man/des_read_pw.3
+++ b/lib/libcrypto/man/des_read_pw.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: des_read_pw.3,v 1.8 2018/03/27 17:35:50 schwarze Exp $
+.\"	$OpenBSD: des_read_pw.3,v 1.9 2020/06/15 15:25:46 tb 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
 .\"
@@ -50,13 +50,14 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 27 2018 $
+.Dd $Mdocdate: June 15 2020 $
 .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 ,
+.Nm EVP_read_pw_string_min
 .Nd compatibility user interface functions
 .Sh SYNOPSIS
 .In openssl/ui_compat.h
@@ -83,6 +84,14 @@
 .Fa "const char *prompt"
 .Fa "int verify"
 .Fc
+.Ft int
+.Fo EVP_read_pw_string_min
+.Fa "char *buf"
+.Fa "int min_length"
+.Fa "int length"
+.Fa "const char *prompt"
+.Fa "int verify"
+.Fc
 .Sh DESCRIPTION
 The DES library contained a few routines to prompt for passwords.
 These aren't necessarily dependent on DES, and have therefore become
@@ -107,8 +116,6 @@ The second password is stored in
 which must therefore also be at least
 .Fa length
 bytes.
-A return code of -1 indicates a system error, 1 failure due to use
-interaction, and 0 is success.
 .Pp
 .Fn des_read_pw_string
 is a variant of
@@ -126,8 +133,34 @@ uses
 .Dv BUFSIZ .
 .Pp
 .Fn EVP_read_pw_string
-is functionally similar to
+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.
+.Sh RETURN VALUES
+These functions return 0 on success and a negative value on failure.
+.Pp
+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
+.Xr UI_process 3
+fails.
+.Pp
+In addition,
+.Fa EVP_read_pw_string_min
+returns -1 if
+.Fa min_length
+is negative, if
+.Fa length
+is less than or equal to
+.Fa min_length ,
+or if the user entered a password shorter than
+.Fa min_length .
 .Sh SEE ALSO
 .Xr UI_new 3
 .Sh HISTORY
@@ -139,6 +172,11 @@ first appeared in SSLeay 0.5.1.
 first appeared in SSLeay 0.8.0.
 These functions have been available since
 .Ox 2.4 .
+.Pp
+.Fn EVP_read_pw_string_min
+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.