diff options
author | Richard Levitte <levitte@openssl.org> | 2017-07-01 12:39:51 +0200 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2017-09-08 20:06:06 +0200 |
commit | 4e049e2c3658ee2bc6e63e696a3779d2f9eed377 (patch) | |
tree | 3991cd2f4d5fb0d64b515dcc5bcc8a12443454e7 /doc | |
parent | a8c5ed812d1537728807059b4182d358bb2ca7c1 (diff) |
Add UI functions to set result with explicit length and to retrieve the length
This allows completely arbitrary passphrases to be entered, including
NUL bytes.
Reviewed-by: Ben Kaduk <kaduk@mit.edu>
(Merged from https://github.com/openssl/openssl/pull/3821)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/UI_STRING.pod | 23 | ||||
-rw-r--r-- | doc/man3/UI_new.pod | 9 |
2 files changed, 25 insertions, 7 deletions
diff --git a/doc/man3/UI_STRING.pod b/doc/man3/UI_STRING.pod index 340d9b2ae2..5a464a37a5 100644 --- a/doc/man3/UI_STRING.pod +++ b/doc/man3/UI_STRING.pod @@ -4,9 +4,9 @@ UI_STRING, UI_string_types, UI_get_string_type, UI_get_input_flags, UI_get0_output_string, -UI_get0_action_string, UI_get0_result_string, +UI_get0_action_string, UI_get0_result_string, UI_get_result_string_length, UI_get0_test_string, UI_get_result_minsize, -UI_get_result_maxsize, UI_set_result +UI_get_result_maxsize, UI_set_result, UI_set_result_ex - User interface string parsing =head1 SYNOPSIS @@ -29,10 +29,12 @@ UI_get_result_maxsize, UI_set_result const char *UI_get0_output_string(UI_STRING *uis); const char *UI_get0_action_string(UI_STRING *uis); const char *UI_get0_result_string(UI_STRING *uis); + int UI_get_result_string_length(UI_STRING *uis); const char *UI_get0_test_string(UI_STRING *uis); int UI_get_result_minsize(UI_STRING *uis); int UI_get_result_maxsize(UI_STRING *uis); int UI_set_result(UI *ui, UI_STRING *uis, const char *result); + int UI_set_result_ex(UI *ui, UI_STRING *uis, const char *result, int len); =head1 DESCRIPTION @@ -60,9 +62,11 @@ associated with a B<UIT_BOOLEAN> type B<UI_STRING>. For all other B<UI_STRING> types, NULL is returned. See L<UI_add_input_boolean(3)>. -UI_get0_result_string() is used to retrieve the result of a prompt. +UI_get0_result_string() and UI_get_result_string_length() are used to +retrieve the result of a prompt and its length. This is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings. -For all other B<UI_STRING> types, NULL is returned. +For all other B<UI_STRING> types, UI_get0_result_string() returns NULL +and UI_get_result_string_length() returns -1. UI_get0_test_string() is used to retrieve the string to compare the prompt result with. @@ -74,7 +78,7 @@ retrieve the minimum and maximum required size of the result. This is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings. For all other B<UI_STRING> types, -1 is returned. -UI_set_result() is used to set the result value of a prompt. +UI_set_result_ex() is used to set the result value of a prompt and its length. For B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, this sets the result retrievable with UI_get0_result_string() by copying the contents of B<result> if its length fits the minimum and maximum size @@ -88,6 +92,11 @@ set to the NUL char C<\0>. See L<UI_add_input_boolean(3)> for more information on B<ok_chars> and B<cancel_chars>. +UI_set_result() does the same thing as UI_set_result_ex(), but calculates +its length internally. +It expects the string to be terminated with a NUL byte, and is therefore +only useful with normal C strings. + =head1 RETURN VALUES UI_get_string_type() returns the UI string type. @@ -103,6 +112,10 @@ UI_get0_result_string() returns the UI string result buffer for B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, NULL for any other type. +UI_get_result_string_length() returns the UI string result buffer's +content length for B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, +-1 for any other type. + UI_get0_test_string() returns the UI string action description string for B<UIT_VERIFY> type UI strings, NULL for any other type. diff --git a/doc/man3/UI_new.pod b/doc/man3/UI_new.pod index 469ea53a32..39b24daa3c 100644 --- a/doc/man3/UI_new.pod +++ b/doc/man3/UI_new.pod @@ -8,6 +8,7 @@ UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean, UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string, UI_add_error_string, UI_dup_error_string, UI_construct_prompt, UI_add_user_data, UI_dup_user_data, UI_get0_user_data, UI_get0_result, +UI_get_result_length, UI_process, UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method, UI_set_method, UI_OpenSSL, UI_null - user interface @@ -50,6 +51,7 @@ UI_get_method, UI_set_method, UI_OpenSSL, UI_null - user interface void *UI_get0_user_data(UI *ui); const char *UI_get0_result(UI *ui, int i); + int UI_get_result_length(UI *ui, int i); int UI_process(UI *ui); @@ -82,12 +84,12 @@ user-defined random data can be passed down to the underlying method through calls to UI_add_user_data() or UI_dup_user_data(). The default UI method doesn't care about these data, but other methods might. Finally, use UI_process() to actually perform the prompting and UI_get0_result() -to find the result to the prompt. +and UI_get_result_length() to find the result to the prompt and its length. A UI can contain more than one prompt, which are performed in the given sequence. Each prompt gets an index number which is returned by the UI_add and UI_dup functions, and has to be used to get the corresponding -result with UI_get0_result(). +result with UI_get0_result() and UI_get_result_length(). UI_process() can be called more than once on the same UI, thereby allowing a UI to have a long lifetime, but can just as well have a short lifetime. @@ -173,6 +175,9 @@ UI with UI_add_user_data() or UI_dup_user_data. UI_get0_result() returns a pointer to the result buffer associated with the information indexed by I<i>. +UI_get_result_length() returns the length of the result buffer associated with +the information indexed by I<i>. + UI_process() goes through the information given so far, does all the printing and prompting and returns the final status, which is -2 on out-of-band events (Interrupt, Cancel, ...), -1 on error and 0 on success. |