diff options
author | Richard Levitte <levitte@openssl.org> | 2017-05-28 09:35:11 +0200 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2017-05-31 19:00:24 +0200 |
commit | 545360c4dfbf90f63918be3d98e344adc7ca2d7f (patch) | |
tree | de6f313d6a48aa2e468cdba0d3137b099ac2c597 /doc | |
parent | 72d8b823bbe749da528f386408541ae1daa644c9 (diff) |
Add UI functionality to duplicate the user data
This can be used by engines that need to retain the data for a longer time
than just the call where this user data is passed.
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3575)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/UI_create_method.pod | 39 | ||||
-rw-r--r-- | doc/man3/UI_new.pod | 34 |
2 files changed, 54 insertions, 19 deletions
diff --git a/doc/man3/UI_create_method.pod b/doc/man3/UI_create_method.pod index 1c40153a3f..aefd41dac3 100644 --- a/doc/man3/UI_create_method.pod +++ b/doc/man3/UI_create_method.pod @@ -5,9 +5,11 @@ UI_METHOD, UI_create_method, UI_destroy_method, UI_method_set_opener, UI_method_set_writer, UI_method_set_flusher, UI_method_set_reader, -UI_method_set_closer, UI_method_set_prompt_constructor, -UI_method_set_ex_data, UI_method_get_opener, UI_method_get_writer, -UI_method_get_flusher, UI_method_get_reader, UI_method_get_closer, +UI_method_set_closer, UI_method_set_data_duplicator, +UI_method_set_prompt_constructor, UI_method_set_ex_data, +UI_method_get_opener, UI_method_get_writer, UI_method_get_flusher, +UI_method_get_reader, UI_method_get_closer, +UI_method_get_data_duplicator, UI_method_get_data_destructor, UI_method_get_prompt_constructor, UI_method_get_ex_data - user interface method creation and destruction @@ -26,6 +28,9 @@ interface method creation and destruction int UI_method_set_reader(UI_METHOD *method, int (*reader) (UI *ui, UI_STRING *uis)); int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui)); + int UI_method_set_data_duplicator(UI_METHOD *method, + void *(*duplicator) (UI *ui, void *ui_data), + void (*destructor)(UI *ui, void *ui_data)); int UI_method_set_prompt_constructor(UI_METHOD *method, char *(*prompt_constructor) (UI *ui, const char @@ -40,6 +45,8 @@ interface method creation and destruction int (*UI_method_get_closer(const UI_METHOD *method)) (UI *); char *(*UI_method_get_prompt_constructor(const UI_METHOD *method)) (UI *, const char *, const char *); + void *(*UI_method_get_data_duplicator(const UI_METHOD *method)) (UI *, void *); + void (*UI_method_get_data_destructor(const UI_METHOD *method)) (UI *, void *); const void *UI_method_get_ex_data(const UI_METHOD *method, int idx); =head1 DESCRIPTION @@ -148,6 +155,9 @@ UI_method_set_flusher(), UI_method_set_reader() and UI_method_set_closer() set the five main method function to the given function pointer. +UI_method_set_data_duplicator() sets the user data duplicator and destructor. +See L<UI_dup_user_data(3)>. + UI_method_set_prompt_constructor() sets the prompt constructor. See L<UI_construct_prompt(3)>. @@ -158,8 +168,9 @@ get that index. UI_method_get_opener(), UI_method_get_writer(), UI_method_get_flusher(), UI_method_get_reader(), -UI_method_get_closer() and UI_method_get_prompt_constructor() return -the different method functions. +UI_method_get_closer(), UI_method_get_data_duplicator(), +UI_method_get_data_destructor() and UI_method_get_prompt_constructor() +return the different method functions. UI_method_get_ex_data() returns the application data previously stored with UI_method_set_ex_data(). @@ -171,17 +182,19 @@ error. UI_method_set_opener(), UI_method_set_writer(), UI_method_set_flusher(), UI_method_set_reader(), -UI_method_set_closer() and UI_method_set_prompt_constructor() return -0 on success, -1 if the given B<method> is NULL. +UI_method_set_closer(), UI_method_set_data_duplicator() and +UI_method_set_prompt_constructor() +return 0 on success, -1 if the given B<method> is NULL. UI_method_set_ex_data() returns 1 on success and 0 on error (because CRYPTO_set_ex_data() does so). UI_method_get_opener(), UI_method_get_writer(), UI_method_get_flusher(), UI_method_get_reader(), -UI_method_get_closer() and UI_method_get_prompt_constructor() return -the requested function pointer if it's set in the method, otherwise -NULL. +UI_method_get_closer(), UI_method_get_data_duplicator(), +UI_method_get_data_destructor() and UI_method_get_prompt_constructor() +return the requested function pointer if it's set in the method, +otherwise NULL. UI_method_get_ex_data() returns a pointer to the application specific data associated with the method. @@ -190,6 +203,12 @@ data associated with the method. L<UI(3)>, L<CRYPTO_get_ex_data(3)>, L<UI_STRING(3)> +=head1 HISTORY + +UI_method_set_data_duplicator(), UI_method_get_data_duplicator() and +UI_method_get_data_destructor() +were added in OpenSSL 1.1.1. + =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 5b98cf8d0d..60a3fd672e 100644 --- a/doc/man3/UI_new.pod +++ b/doc/man3/UI_new.pod @@ -7,9 +7,9 @@ UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string, 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_get0_user_data, UI_get0_result, UI_process, -UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method, -UI_set_method, UI_OpenSSL, UI_null - user interface +UI_add_user_data, UI_dup_user_data, UI_get0_user_data, UI_get0_result, +UI_process, UI_ctrl, UI_set_default_method, UI_get_default_method, +UI_get_method, UI_set_method, UI_OpenSSL, UI_null - user interface =head1 SYNOPSIS @@ -44,6 +44,7 @@ UI_set_method, UI_OpenSSL, UI_null - user interface const char *object_desc, const char *object_name); void *UI_add_user_data(UI *ui, void *user_data); + int UI_dup_user_data(UI *ui, void *user_data); void *UI_get0_user_data(UI *ui); const char *UI_get0_result(UI *ui, int i); @@ -76,16 +77,19 @@ carry out the actual prompting. The first thing to do is to create a UI with UI_new() or UI_new_method(), then add information to it with the UI_add or UI_dup functions. Also, user-defined random data can be passed down to the underlying method -through calls to UI_add_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. +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. 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(). +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. + The functions are as follows: UI_new() creates a new UI using the default UI method. When done with @@ -149,13 +153,20 @@ description "pass phrase" and the file name "foo.key", that becomes string and may include encodings that will be processed by the other method functions. -UI_add_user_data() adds a piece of memory for the method to use at any +UI_add_user_data() adds a user data pointer for the method to use at any time. The builtin UI method doesn't care about this info. Note that several calls to this function doesn't add data, it replaces the previous blob with the one given as argument. +UI_dup_user_data() duplicates the user data and works as an alternative +to UI_add_user_data() when the user data needs to be preserved for a longer +duration, perhaps even the lifetime of the application. The UI object takes +ownership of this duplicate and will free it whenever it gets replaced or +the UI is destroyed. UI_dup_user_data() returns 0 on success, or -1 on memory +allocation failure or if the method doesn't have a duplicator function. + UI_get0_user_data() retrieves the data that has last been given to the -UI with UI_add_user_data(). +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>. @@ -191,6 +202,11 @@ 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 HISTORY + +UI_dup_user_data() +was added in OpenSSL 1.1.1. + =head1 COPYRIGHT Copyright 2001-2017 The OpenSSL Project Authors. All Rights Reserved. |