Clarify what character encoding is used in the returned UI strings

Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3532)

diff --git a/doc/man3/UI_UTIL_read_pw.pod b/doc/man3/UI_UTIL_read_pw.pod
index 5c88001cc7f419166b57b9b04ff2305d1f8685bd..8d5ccc815be1f6445b74fcb9d0a522ce06c97742 100644 (file)
--- a/doc/man3/UI_UTIL_read_pw.pod
+++ b/doc/man3/UI_UTIL_read_pw.pod
@@ -34,6 +34,24 @@ 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 SEE ALSO
+
+L<UI_get_default_method(3)>
+
 =head1 COPYRIGHT
 
 Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/doc/man3/UI_new.pod b/doc/man3/UI_new.pod
index c5ebfddc89ac913362aad62b774a760f1a5df745..5b98cf8d0d20adce6cf72973f5ce0d838e61f859 100644 (file)
--- a/doc/man3/UI_new.pod
+++ b/doc/man3/UI_new.pod
@@ -94,10 +94,13 @@ this UI, it should be freed using UI_free().
 UI_new_method() creates a new UI using the given UI method.  When done with
 this UI, it should be freed using UI_free().
 
-UI_OpenSSL() returns the built-in UI method (note: not 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.
+UI_OpenSSL() returns the built-in UI method (note: not necessarely 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.
+
+UI_null() returns a UI method that does nothing.  Its use is to avoid
+getting internal defaults for passed UI_METHOD pointers.
 
 UI_free() removes a UI from memory, along with all other pieces of memory
 that's connected to it, like duplicated input strings, results and others.
@@ -177,11 +180,16 @@ UI_get_method() returns the UI method associated with a given UI.
 
 UI_set_method() changes the UI method associated with a given UI.
 
-UI_OpenSSL() is the default OpenSSL UI method for prompting
-passphrases on the command line.
+=head1 NOTES
 
-UI_null() is a UI method that does nothing.  Its use is to avoid
-getting internal defaults for passed UI_METHOD pointers.
+The resulting strings that the built in method UI_OpenSSL() generate
+are assumed to be encoded according to the current locale or (for
+Windows) code page.
+For applications having different demands, these strings need to be
+converted appropriately by the caller.
+For Windows, if the OPENSSL_WIN32_UTF8 environment variable is set,
+the built-in method UI_OpenSSL() will produce UTF-8 encoded strings
+instead.
 
 =head1 COPYRIGHT