From b024891f7f84d657d1c9b1f0d364dc1c3c42f411 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Tue, 23 May 2017 19:52:54 +0200 Subject: Clarify what character encoding is used in the returned UI strings Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/3532) (cherry picked from commit 789d6dddecbc231f5c858d203aab318cf81676fd) --- doc/crypto/UI_new.pod | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/crypto/UI_new.pod b/doc/crypto/UI_new.pod index 037e8bf10e..5b98cf8d0d 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, 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 -- cgit v1.2.3