From 789d6dddecbc231f5c858d203aab318cf81676fd Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Tue, 23 May 2017 19:52:54 +0200 Subject: [PATCH] Clarify what character encoding is used in the returned UI strings Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/3532) --- 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 5c88001cc7..8d5ccc815b 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. +See L and friends for more information. + +The result from the B 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. + +=head1 SEE ALSO + +L + =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 c5ebfddc89..5b98cf8d0d 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 -- 2.25.1