evp_rand: documentation

[openssl.git] / doc / man3 / UI_UTIL_read_pw.pod

diff --git a/doc/man3/UI_UTIL_read_pw.pod b/doc/man3/UI_UTIL_read_pw.pod
index f0b4a69e001f0bfb540d7e2723ef54bbcb916c03..9de8fe1ddc9778c2bdd6b45c9a271b9f8caf0673 100644 (file)
--- a/doc/man3/UI_UTIL_read_pw.pod
+++ b/doc/man3/UI_UTIL_read_pw.pod
@@ -3,7 +3,7 @@
 =head1 NAME
 
 UI_UTIL_read_pw_string, UI_UTIL_read_pw,
-*UI_UTIL_wrap_read_pem_callback - user interface utilities
+UI_UTIL_wrap_read_pem_callback - user interface utilities
 
 =head1 SYNOPSIS
 
@@ -13,8 +13,7 @@ UI_UTIL_read_pw_string, UI_UTIL_read_pw,
                             int verify);
  int UI_UTIL_read_pw(char *buf, char *buff, int size, const char *prompt,
                      int verify);
- UI_METHOD *UI_UTIL_wrap_read_pem_callback(pem_password_cb *cb, int
- rwflag);
+ UI_METHOD *UI_UTIL_wrap_read_pem_callback(pem_password_cb *cb, int rwflag);
 
 =head1 DESCRIPTION
 
@@ -22,7 +21,7 @@ UI_UTIL_read_pw_string() asks for a passphrase, using B<prompt> as a
 prompt, and stores it in B<buf>.
 The maximum allowed size is given with B<length>, including the
 terminating NUL byte.
-If B<verify> is non-zero, the password will be verified as well.
+If B<verify> is nonzero, the password will be verified as well.
 
 UI_UTIL_read_pw() does the same as UI_UTIL_read_pw_string(), the
 difference is that you can give it an external buffer B<buff> for the
@@ -35,11 +34,37 @@ passphrase entry without (0) or with (1) verification.
 When not used any more, the returned method should be freed with
 UI_destroy_method().
 
+=head1 NOTES
+
+UI_UTIL_read_pw_string() and UI_UTIL_read_pw() use default
+B<UI_METHOD>.
+See L<UI_get_default_method(3)> and friends for more information.
+
+The result from the B<UI_METHOD> created by
+UI_UTIL_wrap_read_pem_callback() will generate password strings in the
+encoding that the given password callback generates.
+The default password prompting functions (apart from
+UI_UTIL_read_pw_string() and UI_UTIL_read_pw(), there is
+PEM_def_callback(), EVP_read_pw_string() and EVP_read_pw_string_min())
+all use the default B<UI_METHOD>.
+
+=head1 RETURN VALUES
+
+UI_UTIL_read_pw_string() and UI_UTIL_read_pw() return 0 on success or a negative
+value on error.
+
+UI_UTIL_wrap_read_pem_callback() returns a valid B<UI_METHOD> structure or NULL
+if an error occurred.
+
+=head1 SEE ALSO
+
+L<UI_get_default_method(3)>
+
 =head1 COPYRIGHT
 
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.