[openssl-commits] [openssl] master update

[Richard Levitte]

The branch master has been updated
       via  789d6dddecbc231f5c858d203aab318cf81676fd (commit)
      from  dd5918775aeed51f8a666d151c5bd007e91bc534 (commit)


- Log -----------------------------------------------------------------
commit 789d6dddecbc231f5c858d203aab318cf81676fd
Author: Richard Levitte <levitte at openssl.org>
Date:   Tue May 23 19:52:54 2017 +0200

    Clarify what character encoding is used in the returned UI strings
    
    Reviewed-by: Rich Salz <rsalz at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/3532)

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/UI_UTIL_read_pw.pod | 18 ++++++++++++++++++
 doc/man3/UI_new.pod          | 24 ++++++++++++++++--------
 2 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/doc/man3/UI_UTIL_read_pw.pod b/doc/man3/UI_UTIL_read_pw.pod
index 5c88001..8d5ccc8 100644
--- 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 c5ebfdd..5b98cf8 100644
--- 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