[openssl-commits] [openssl] OpenSSL_1_1_0-stable update

[Richard Levitte]

The branch OpenSSL_1_1_0-stable has been updated
       via  b024891f7f84d657d1c9b1f0d364dc1c3c42f411 (commit)
      from  e242656cb1184a713911dd53206799bda02fe15b (commit)


- Log -----------------------------------------------------------------
commit b024891f7f84d657d1c9b1f0d364dc1c3c42f411
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)
    (cherry picked from commit 789d6dddecbc231f5c858d203aab318cf81676fd)

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

Summary of changes:
 doc/crypto/UI_new.pod | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/doc/crypto/UI_new.pod b/doc/crypto/UI_new.pod
index 037e8bf..5b98cf8 100644
--- a/doc/crypto/UI_new.pod
+++ b/doc/crypto/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.
@@ -168,6 +171,8 @@ B<UI_CTRL_IS_REDOABLE>, which returns a flag saying if the used UI can
 be used again or not.
 
 UI_set_default_method() changes the default UI method to the one given.
+This function is not thread-safe and should not be called at the same time
+as other OpenSSL functions.
 
 UI_get_default_method() returns a pointer to the current default UI method.
 
@@ -175,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